FlavorCloud Partner API Documentation
  1. Shipments
FlavorCloud Partner API Documentation
  • Authentication
    • Get Auth Token
      POST
  • Rates
    • Get Rates
      POST
    • Get Rate Detail
      GET
    • Get Multi Quote
      POST
    • Get Multi Rates
      POST
    • Get Quote
      POST
  • Shipments
    • Create Shipments
      POST
    • Get Shipments
      GET
    • Cancel Shipments
      PUT
  • Tracking
    • Get Tracking Detail
      GET
  • Batches
    • Create Batch
      POST
    • Update Batch - Add Shipment
      PUT
    • Update Batch - Remove Shipment
      PUT
    • Close Batch
      POST
    • Get Batch
      GET
  • Classifications
    • Get Classification
      POST
  • Customer
    • Add Customer
      POST
    • Get Customers
      GET
  • Landed Cost
    • Get Landed Cost
      POST
  • Manifest
    • Manifest Shipment
      POST
    • Get Manifest
      GET
  • Webhooks
    • Subscribe Webhooks
    • Unsubscribe Webhooks
  • Invoices
    • Get Invoice Detail
    • Get Invoices
  1. Shipments

Create Shipments

POST
/Shipments
Shipments
A Shipment is a container for all the information required to generate a shipping label and commercial invoice (in the case of international shipments). This api returns a ShipmentID that can be used to retrieve the necessary docs for the shipment. The shipment call is billable, see your contract for rates.
When creating Shipments, Reference values are required and must be unique. Providing a duplicate Reference value will return the Shipment previously created with that Reference. If a Shipment pertaining to the supplied Reference value is/was canceled, and then resubmit, the response will return the same ShipmentID with a new tracking number.

Request

Authorization
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
Body Params application/json
CustomerKey
string 
optional
Your unique FlavorCloud Customer Key we created.
HashKey
string 
optional
The unique identifier of your Individual Rate option. Provide this value if you have already made a request for an individual rate. If a valid rate HashKey is provided we will make the ServiceCode and TermsOfTrade fields optional in the /Shipment partner API.
If there is no rate HashKey provided or invalid rate HashKey, then the ServiceCode and TermsOfTrade fields will be required in the /Shipment partner API.
DutyHashKey
string 
optional
The unique identifier of the landed costs for your rate option. Provide this value if you have already made a request for an individual rate.
PickUpDate
string 
optional
Shipment PickUpDate (ISO Date) in text format YYYY-MM-DD; EX: 2024-07-30
Async
boolean 
optional
This field for your response for the call as asynchronous or synchronous
Default:
false
Reference
string 
required
It's important to know this number must be unique per shipment request to create a new request. This field is for your reference and must be unique. It is advised to provide your order number here. Duplicate Reference values may not be provided, otherwise they will return the Shipment previously created with the provided Reference.
LabelFormat
enum<string> 
optional
LabelFormat Default is PDF
Allowed values:
PDFZPL
Default:
PDF
WeightUnit
enum<string> 
optional
Unit for weight of the shipment. Default in KG
Allowed values:
KGLB
Default:
KG
Currency
string 
optional
Currency for the rate, Default is USD
Default:
USD
DimensionUnit
enum<string> 
optional
Unit for dimensions of the shipment. Default is CM
Allowed values:
INCM
Default:
IN
Insurance
enum<string> 
optional
Specify if insurance is required. Default is N
Allowed values:
YN
Default:
N
ServiceCode
string 
optional
Service code. Possible values could be 'STANDARD' | 'STANDARD-ECONOMY' | 'EXPRESS' | 'EXPRESS-ECONOMY'. Default is STANDARD. If a valid rate HashKey is provided we will make the ServiceCode and TermsOfTrade fields optional in the /Shipment partner API.
If there is no rate HashKey provided or invalid rate HashKey, then the ServiceCode and TermsOfTrade fields will be required in the /Shipment partner API.
TermsOfTrade
string 
optional
Terms of trade can be Delivery Duties Paid (DDP) or Delivery Duties Unpaid (DDU). Default is DDP if not specified. If a valid rate HashKey is provided we will make the ServiceCode and TermsOfTrade fields optional in the /Shipment partner API.
If there is no rate HashKey provided or invalid rate HashKey, then the ServiceCode and TermsOfTrade fields will be required in the /Shipment partner API.
IsReturn
enum<string> 
optional
You can easily create return labels. All you need to do is set the is_return parameter to "Y".
Allowed values:
YN
Default:
N
ShipmentKey
string 
optional
ShipmentKey is required for Return Shipments
ShipFromAddress
object (ShipFromAddress) 
required
Name
string 
optional
Name of person. Both name and company can be included
Default:
Test Shipper
AttentionName
string 
optional
Name of attention, if person
Default:
Test Shipper
LocationName
string 
optional
This property allows you to supply a specific name of a location you have on your FlavorCloud account. If you supply a name of a location that exists on your FlavorCloud account, the address information for the location will be used. If you supply a name of a location that does not exist on your FlavorCloud account, a new location will be created with the address information supplied
Default:
AddressLine1
string 
required
First line of the address
AddressLine2
string 
optional
Second line of the address
AddressLine3
string 
optional
Third line of the address
City
string 
required
Full city name
State
string 
optional
State or province
Country
string 
required
ISO 3166 country code for the country the address is located in
Zip
string 
optional
ZIP or postal code
Phone
string 
required
Phone number to reach the person or organization
Email
string 
required
Email to reach the person or organization
ShipToAddress
object (ShipToAddress) 
required
Name
string 
required
Name of person. Both name and company can be included
Default:
Test consignee
AttentionName
string 
optional
Name of attention, if person
Default:
Test consignee
AddressLine1
string 
required
First line of the address
AddressLine2
string 
optional
Second line of the address
AddressLine3
string 
optional
Third line of the address
City
string 
required
Full city name
State
string 
optional
State or province
Country
string 
required
ISO 3166 country code for the country the address is located in
Zip
string 
optional
ZIP or postal code
Phone
string 
required
Phone number to reach the person or organization
Email
string 
required
Email to reach the person or organization
FederalTaxId
string 
optional
Federal tax identifier of the person or organization
StateTaxId
string 
optional
State tax identifier of the person or organization
Shipments
array[object (ShipmentsModel) {3}] 
required
Piece
array[object (Piece) {12}] 
required
Package
object (ShipmentPackage) 
required
ITNNumber
string 
optional
ITNNumber
ReasonForExport
string 
optional
State the key reason for the shipment. It is required to accurately process the shipment through Customs clearance. Possible values could be 'documents', 'gift', 'merchandise', 'returned_goods', 'sample', or 'replacement'. If no value is provided, the default is 'Merchandise'.
Choose "merchandise" or "documents" when considered a sale and the documentation will be customized accordingly.
Choose "gift" when it is sample being sent to an influencer or customer and there was no sale involved. Choose "returned_goods" when merchandise that was sold is being returned/rejected by customer.
Choose "replacement" when merchandise is being sent as a replacement or exchange to the customer for a prior sale.
Choose "sample" when sample products are being sent to customers free of cost and no sale was involved.
Default:
merchandise
Metadata
object (Metadata) 
optional
IndiaExportInfo
object (IndiaExportInfo) 
optional
B2b
boolean 
optional
Enable this flag for Business to business
Default:
false
Example
{
  "Async": false,
  "Reference": "test-create-shipment-001",
  "HashKey": "588d4ff7-9b21-4028-ba2e-333507bf53d8",
  "LabelFormat": "PDF",
  "WeightUnit": "LB",
  "Currency": "USD",
  "DimensionUnit": "IN",
  "Insurance": "N",
  "ServiceCode": "EXPRESS",
  "TermsOfTrade": "DDP",
  "IsReturn": "N",
  "ReasonForExport": "merchandise",
  "B2b": false,
  "ShipmentKey": "",
  "ShipFromAddress": {
    "Name": "FC Rates",
    "AttentionName": "",
    "AddressLine1": "1562 Washington St",
    "AddressLine2": "",
    "AddressLine3": "",
    "City": "San Francisco",
    "State": "CA",
    "Country": "US",
    "Zip": "94109",
    "Phone": "1111111111",
    "Email": "test@test.com"
  },
  "ShipToAddress": {
    "Name": "FC Rates",
    "AttentionName": "FC Rates",
    "AddressLine1": "49 Montcalm Ave",
    "AddressLine2": "",
    "AddressLine3": "",
    "City": "York",
    "State": "ON",
    "Country": "CA",
    "Zip": "M6E 4N8",
    "Phone": "1111111111",
    "Email": "test@test.com"
  },
  "Shipments": [
    {
      "Piece": [
        {
          "Quantity": 1,
          "Weight": 0.1,
          "Length": 1,
          "Width": 1,
          "Height": 1,
          "SalePrice": 10,
          "HSCode": "610910",
          "OriginCountryCode": "US",
          "Description": "T-SHIRT",
          "SKU": "1234567890",
          "Material": "",
          "Category": [
            "merchandise"
          ]
        }
      ],
      "Package": {
        "Weight": 0.5,
        "Length": 1,
        "Width": 1,
        "Height": 1,
        "Reference": ""
      }
    }
  ]
}

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://partnerapi.flavorcloud.com/Shipments' \
--header 'Content-Type: application/json' \
--data-raw '{
    "Async": false,
    "Reference": "test-create-shipment-001",
    "HashKey": "588d4ff7-9b21-4028-ba2e-333507bf53d8",
    "LabelFormat": "PDF",
    "WeightUnit": "LB",
    "Currency": "USD",
    "DimensionUnit": "IN",
    "Insurance": "N",
    "ServiceCode": "EXPRESS",
    "TermsOfTrade": "DDP",
    "IsReturn": "N",
    "ReasonForExport": "merchandise",
    "B2b": false,
    "ShipmentKey": "",
    "ShipFromAddress": {
        "Name": "FC Rates",
        "AttentionName": "",
        "AddressLine1": "1562 Washington St",
        "AddressLine2": "",
        "AddressLine3": "",
        "City": "San Francisco",
        "State": "CA",
        "Country": "US",
        "Zip": "94109",
        "Phone": "1111111111",
        "Email": "test@test.com"
    },
    "ShipToAddress": {
        "Name": "FC Rates",
        "AttentionName": "FC Rates",
        "AddressLine1": "49 Montcalm Ave",
        "AddressLine2": "",
        "AddressLine3": "",
        "City": "York",
        "State": "ON",
        "Country": "CA",
        "Zip": "M6E 4N8",
        "Phone": "1111111111",
        "Email": "test@test.com"
    },
    "Shipments": [
        {
            "Piece": [
                {
                    "Quantity": 1,
                    "Weight": 0.1,
                    "Length": 1,
                    "Width": 1,
                    "Height": 1,
                    "SalePrice": 10,
                    "HSCode": "610910",
                    "OriginCountryCode": "US",
                    "Description": "T-SHIRT",
                    "SKU": "1234567890",
                    "Material": "",
                    "Category": [
                        "merchandise"
                    ]
                }
            ],
            "Package": {
                "Weight": 0.5,
                "Length": 1,
                "Width": 1,
                "Height": 1,
                "Reference": ""
            }
        }
    ]
}'

Responses

🟢200Create Shipments Response
application/json
Body
(tsType: Omit<ShipmentResponse, 'ConsolidateLabel'>, schemaOptions: { exclude: [ 'ConsolidateLabel' ] })
ShipmentID
string 
required
The unique id for the shipment that can be used to retrieve it later
Status
string 
required
Status
Reference
string 
required
The reference id that was sent in the request
Message
string 
optional
Message
TrackingNumber
string 
required
Tracking number for the shipment
TrackingUrl
string 
optional
The url to fetch the live tracking status of the shipment
LabelUrl
array[string]
required
Carrier
string 
required
Carrier
CustomsInvoiceURL
string 
required
The url to fetch the generated consolidated label
SubmittedElectronically
boolean 
optional
SubmittedElectronically
Example
{
  "ShipmentID": "string",
  "Status": "string",
  "Reference": "string",
  "Message": "string",
  "TrackingNumber": "string",
  "TrackingUrl": "string",
  "LabelUrl": [
    "string"
  ],
  "Carrier": "string",
  "CustomsInvoiceURL": "string",
  "SubmittedElectronically": true
}
🟠401Authentication Error
🟠422Validation Error
🔴500Error Response
Modified at 2025-04-28 20:48:57
Previous
Get Quote
Next
Get Shipments
Built with