← Back to Partners Overview

Partner Integration Docs

Technical specifications and setup steps for wholesaling and fulfilling orders on our behalf.

1. API Webhook Integration (Real-Time)

If you have an automated WMS (Warehouse Management System), we can POST order details to your endpoint in real-time immediately after successful payment checkout.

POST https://your-warehouse.com/api/intake

Headers: Content-Type: application/json, Authorization: Bearer <YOUR_API_KEY>

Example Payload:

{
  "order_id": "018e1e0c-7e1e-7e1e-7e1e-7e1e7e1e7e1e",
  "currency": "USD",
  "amount": 3839, // Price in cents ($38.39)
  "shipping": {
    "name": "Jane Doe",
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US",
    "email": "[email protected]"
  },
  "items": [
    {
      "sku": "ethiopian-highland-black-seed-oil-100ml",
      "name": "Ethiopian Highland Black Seed Oil - 100ml",
      "quantity": 1,
      "price": 38.39
    }
  ]
}

2. Email Manifest Integration

For manual warehouses, our system sends structured HTML packing slips instantly to your intake inbox.

Subject: [Order Manifest] Dispatch Request - Order #018e1e0c

Deliver to:

Jane Doe

123 Main Street, Apt 4B, New York, NY, 10001, US

Items to Pack:

• 1x Ethiopian Highland Black Seed Oil - 100ml (SKU: ethiopian-highland-black-seed-oil-100ml)

3. Fulfillment Portal Setup

Every supplier receives access to our secure web portal to track outstanding items and upload tracking numbers.

  1. We create a partner user account for you.
  2. Login at /login using your partner credentials.
  3. Navigate to the Fulfillment Dashboard.
  4. Review processing orders in your queue, print packing sheets, and enter the **Carrier** & **Tracking Number** when shipped to complete the order.

4. Automated Stripe Connect Payouts

We use **Stripe Connect Destination Charges** to split customer payments. As soon as a transaction succeeds on our storefront:

  • Your connected Stripe account receives the **wholesale price** (75% of retail price) automatically.
  • The retail markup (25%) is retained in our platform account as our sales commission.
  • Funds are paid out directly to your bank account based on your Stripe Connect schedule.

Configuration: During onboarding, our team will send you a Stripe Connect onboarding link to link your corporate bank account.

5. Outbound Shipping Callback API

For API-integrated warehouses, once an order is shipped from your facility, your system should notify our backend to set the order status to `shipped` and register the tracking number.

Step 1: Obtain a Session Token

Authenticate by posting your partner credentials to our login endpoint:

POST https://blackseedoil.com/api/auth/login

Body: { "email": "your-partner-email", "password": "your-password" }

Response: { "success": true, "token": "session_token_here", ... }

Step 2: Retrieve Outstanding Orders (Pull Model)

Instead of waiting for push webhooks, you can fetch all active orders currently assigned to you and waiting to be packaged:

GET https://blackseedoil.com/api/orders/fulfillment

Headers: Authorization: Bearer <session_token>

Response: { "data": [ { "id": "order_id", "amount": 3839, "shippingAddress": {...}, "items": [...] } ] }

Step 3: Upload Tracking Details

Send a PUT request containing the carrier and tracking details. Use the token obtained in Step 1 as a Bearer authorization header:

PUT https://blackseedoil.com/api/orders/<order_id>/ship

Headers: Authorization: Bearer <session_token>, Content-Type: application/json

Body: { "carrier": "dhl", "tracking_number": "1Z999AA10123456784" }

6. Direct Thermal Printing (Zebra Cloud Connect)

For advanced warehouses looking for automated physical printing, our system supports **Zebra Cloud Connect**.

  • We generate compliant **ZPL (Zebra Programming Language)** label files automatically.
  • We dispatch the ZPL files directly to the IP address or Cloud ID of the Zebra thermal printer(s) inside your facility.
  • No browser clicks or local print servers required—shipping labels print out automatically on the warehouse floor when the order is marked as processing.

Configuration: Provide your Zebra Cloud printer ID and required label dimension (e.g. 4x6 thermal paper) during onboarding.