Getting Started Guide for 3PLs

Third-party logistics providers (3PLs) and shipping platforms can integrate once and act on behalf of all of their merchants under a single set of API credentials. Your AppID and RestApiKey authenticate your platform; a per-merchant CustomerKey identifies and authorizes each merchant on every transaction.

Are you a merchant?

The Getting Started Guide is a little different for you. View the Merchant Guide →

Authenticate your platform

POST https://partnerapi.flavorcloud.com/Auth

Your AppID and RestApiKey are platform-level credentials — shared across all your merchants. Authenticate once, reuse the token.

{ "AppID": "{{APP_ID}}", "RestApiKey": "{{REST_API_KEY}}" }
// → { "Token": "eyJhbGci..." }

Understand CustomerKey

Every merchant you onboard gets a unique CustomerKey from FlavorCloud. Include it on every /Rates, /LandedCost, and /Shipments call to identify which merchant the transaction belongs to — and to validate that the merchant is associated with your account.

// Credential scopes
AppID + RestApiKey  →  authenticates your 3PL platform (shared, issued once)
CustomerKey         →  identifies the merchant per transaction (one per merchant)

TIP

Contact your FlavorCloud account manager or email support@flavorcloud.com to get a CustomerKey assigned for each merchant you onboard. It does not change once issued.

Get rates for a merchant

POST https://partnerapi.flavorcloud.com/Rates

Same as a standard rate call — add CustomerKey to identify the merchant.

{
  "Reference":         "MERCHANT-ORDER-001",
  "CustomerKey":       "{{CUSTOMER_KEY}}",   // ← identifies + authorizes merchant
  "WeightUnit":        "LB",
  "DimensionUnit":     "IN",
  "Currency":          "USD",
  "ReasonForExport":   "merchandise",
  "ShipFromAddress":   { "Name": "Merchant Brand Co.", "Country": "US", "..." },
  "ShipToAddress":     { "Country": "GB", "..." },
  "Pieces":  [{ "HSCode": "610910", "SalePrice": 50.00, "Quantity": 1, "..." }],
  "Package": { "Weight": 1.0, "..." }
}
// → { "Express": { "DDP": { "HashKey": "Z15DTMI", "..." }}}

Store per merchant order

Store the HashKey and DutyHashKey per merchant order — they're specific to that transaction.

Create the label for a merchant

POST https://partnerapi.flavorcloud.com/Shipments

Pass CustomerKey alongside the rate hash keys from the previous step.

{
  "Reference":     "MERCHANT-ORDER-001",
  "CustomerKey":   "{{CUSTOMER_KEY}}",    // ← same merchant CustomerKey
  "ServiceCode":   "STANDARD",
  "TermsOfTrade":  "DDP",
  "WeightUnit":    "LB", "DimensionUnit": "IN", "Currency": "USD",
  "ReasonForExport": "merchandise",
  "HashKey":       "Z15DTMI",
  "DutyHashKey":   "Z1Afo2b",
  "ShipFromAddress": { "..." },
  "ShipToAddress":   { "..." },
  "Shipments": [{ "Piece": [{ "..." }], "Package": { "..." } }]
}
// → { "ShipmentID": "ku3027lhufe", "LabelUrl": ["..."], "TrackingNumber": "..." }

Store per order

Store the ShipmentID per order — needed for return labels.

POST https://partnerapi.flavorcloud.com/Webhooks/Subscribe

Subscribe once. FlavorCloud pushes events to your URL for all merchants under your account.

{
  "WebHooksList": [
    { "EventName": "SHIPMENT_CREATED", "URL": "https://your-platform.com/webhooks/fc" },
    { "EventName": "TRACKING_UPDATES", "URL": "https://your-platform.com/webhooks/fc" }
  ]
}

Routing events

Webhook payloads include shipment_id and app_id — use these to route events to the right merchant in your system.

Shipment variations

The steps above cover a standard outbound B2C shipment for a merchant. Common variations use the same endpoints with minor additions.

📦 Multiple packages — Include one object per carton in the Shipments array. Each package gets its own label; the entire shipment shares one consolidated customs invoice. Use Package.Reference (e.g., "PKG-1") to match the right label to the right carton. Pass CustomerKey as usual.

🏢 B2B shipments — Add B2b: true, set ReasonForExport: "Sold / Commercial Transaction", use business names in address fields, and include the consignee's FederalTaxId. DDP is strongly recommended. Pass CustomerKey as usual.

🔄 Return labels — Add IsReturn: "Y" to both /Rates and /Shipments. Pass the original ShipmentID as ShipmentKey. Addresses are automatically reversed on the printed label. Pass CustomerKey as usual.

Next steps

All endpoints

Full endpoint documentation, parameters, and response schemas.

Create Shipments

Generate labels, customs docs, and tracking numbers for any merchant.

Subscribe Webhooks

Receive push events for all merchants under your account.

Merchant Guide

Rates, shipments, manifesting, and tracking for direct merchants.

Authenticate your platform#

Understand CustomerKey#

Get rates for a merchant#

Create the label for a merchant#

Subscribe to webhooks#

Shipment variations#

Next steps#

Authenticate your platform

Understand CustomerKey

Get rates for a merchant

Create the label for a merchant

Subscribe to webhooks

Shipment variations

Next steps