Create Shipments - FlavorCloud Partner API Documentation

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

Determines if this call is executed synchronously or asynchronously. Default is false.

Default:

false

Reference

string

required

Your Order Number, the reference you use to communicate information about this shipment to your customer. For Shopify Orders, pass the Order_Number from the Shopify Order.

LabelFormat

enum<string>

optional

The format of the label you would like generated (ZPL/PDF). LabelFormat Default is PDF

Allowed values:

PDFZPL

Default:

PDF

WeightUnit

enum<string>

optional

Weight unit of the shipment. Default in KG

Allowed values:

KGLB

Default:

Currency

string

optional

ISO Currency code, default is USD

Default:

USD

DimensionUnit

enum<string>

optional

DImensions unit of the shipment. Default is CM

Allowed values:

INCM

Default:

Insurance

enum<string>

optional

Specify if insurance is required. Default is N

Allowed values:

Default:

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:

Default:

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

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

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, 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

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

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