Getting Started Guide for Merchants

This page will go over best practices and common setups for the FlavorCloud API. By the end of it, you will be able to generate rates, print labels, and manifest (consolidate) shipments. For a more granular look at these calls and other endpoints, see the API reference.

Use this Postman collection to follow along with the API calls from this guide.

Are you a 3PL?

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

Before starting, you will need to sign up for a FlavorCloud account.

The four-step integration

Retrieve shipping rates

Calculate accurate total costs using full address, parcel, and package information. Learn how ↓

Subscribe to webhooks so you receive shipping info the moment a label is generated. Learn how ↓

Receive shipping info

Get back labels, tracking numbers, and customs forms for every shipment. Learn how ↓

Get detailed tracking info

Look up real-time tracking across every carrier we support. Learn how ↓

Additional scenarios

Need to handle returns? See the Returns Guide →

Authentication

Authentication to the FlavorCloud API is handled by using your APPID and RestApiKey. These are required in every call to the FlavorCloud API. You can find your APPID and RestApiKey in your FlavorCloud account settings.

There are two ways to send your APPID and RestApiKey to the FlavorCloud API:

In the body of the request

In the request URL

We will specify which style of authentication is needed for each API call.

Getting Rates

POST https://partnerapi.flavorcloud.com/Rates — View endpoint reference →

When you have the full address, parcel, and package information for a shipment, you can use the Rates endpoint to calculate accurate total costs.

It is important to note the weight of the combined pieces should not exceed the weight of the entire package. If these differ, we will use the higher weight between the package and the combined weight of the pieces.

The Rates endpoint has more requirements than Quotes and closely resembles our Shipment call. For DDP shipments, you are required to use the IncludeLandedCost flag.

Some responses may return Duty and Tax for the shipment as 0. This is likely because the value of the shipment is lower than the minimum threshold to qualify for duties and taxes to the country you are shipping to. The minimum value for applying duty and taxes is called the de minimis.

Response notes

Both Standard and Express arrays will be returned when there is a rate for the given service level. If only an express rate is available, Express will be the only service level returned.

Hash keys will be returned in the Rates response and should be sent for all future transactions containing the same information.

Example

Request

Response

{
  "AppID": "{{APP ID}}",
  "RestApiKey": "{{API Key}}",
  "Reference": "Reference56",
  "WeightUnit": "LB",
  "Currency": "USD",
  "DimensionUnit": "IN",
  "Insurance": "N",
  "ShipFromAddress": {
    "Name": "Flavorcloud",
    "AttentionName": "Jake Krachman",
    "AddressLine1": "200 Townsend Street",
    "City": "San Francisco",
    "Country": "US",
    "State": "CA",
    "Zip": "94107",
    "Phone": "5555555555",
    "Email": "jake.krachman@flavorcloud.com"
  },
  "ShipToAddress": {
    "Name": "Company Name",
    "AttentionName": "Receiver Name",
    "AddressLine1": "89 Pall Mall",
    "AddressLine2": "St. James's",
    "City": "London",
    "State": "UK",
    "Country": "GB",
    "Zip": "SW1Y 5HS",
    "Phone": "5555555555",
    "Email": "test@test.com"
  },
  "ReasonForExport": "merchandise",
  "IncludeLandedCost": true,
  "Pieces": [
    {
      "Quantity": 1,
      "Weight": 0.4,
      "SalePrice": 290.00,
      "HSCode": "920994",
      "OriginCountryCode": "US",
      "Description": "Blue Polyester T-Shirt"
    }
  ],
  "Package": {
    "Weight": 1.25
  }
}

Creating Shipments

POST https://partnerapi.flavorcloud.com/Shipments — View endpoint reference →

This call will create a label with the carrier for the passed shipments. You can pass one or multiple shipments as long as the to and from addresses are the same within the call. We will return a label, tracking, and customs forms for each shipment.

Address verification

At this time, we do not perform address verification on addresses entered into this call. If you submit a shipment with an invalid address, you will receive a generic no rates error.

The DutyHashKey and HashKey are returned in the Rating call. While they are not required, we suggest including them for all previously rated shipments. This decreases response times by removing the need to recalculate duties and taxes.

As mentioned under Getting Rates, the combined weight of individual pieces within an order should not exceed the total weight of the package, or the higher weight will be used.

Response notes

The response returns a ShipmentID. Store this ID for future reference — it is also used in the ManifestShipment call.

When SubmittedElectronically is true, you do not need to print the commercial invoice. We submit the invoice to the carrier and the form is for your reference only.

Example

Request

Response

{
  "AppID": "{{APP ID}}",
  "RestApiKey": "{{API Key}}",
  "Reference": "10874054",
  "ServiceCode": "STANDARD",
  "ShipFromAddress": {
    "Name": "Flavorcloud",
    "AttentionName": "Jake Krachman",
    "AddressLine1": "200 Townsend Street",
    "City": "San Francisco",
    "Country": "US",
    "State": "CA",
    "Zip": "94107",
    "Phone": "5555555555",
    "Email": "jake.krachman@flavorcloud.com"
  },
  "ShipToAddress": {
    "Name": "Company Name",
    "AttentionName": "Receiver Name",
    "AddressLine1": "2412A Victoria Ave.",
    "City": "Brandon",
    "State": "MB",
    "Country": "CA",
    "Zip": "R7B 0M5",
    "Phone": "5555555555",
    "Email": "test@test.com"
  },
  "Shipments": [
    {
      "Piece": [
        {
          "Quantity": 1,
          "Weight": 0.4,
          "SalePrice": 29.00,
          "HSCode": "920994",
          "OriginCountryCode": "US",
          "Description": "Blue Polyester T-Shirt"
        }
      ],
      "Package": {
        "Reference": "124",
        "Weight": 1.25,
        "Length": 1,
        "Width": 1,
        "Height": 1
      }
    }
  ],
  "HashKey": "1eqRtv",
  "DutyHashKey": "Z1M1N3b",
  "PickUpDate": "2021-09-27",
  "ReasonForExport": "merchandise",
  "WeightUnit": "LB",
  "Currency": "USD",
  "DimensionUnit": "IN",
  "TermsOfTrade": "DDP"
}

Manifesting Shipments

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

This call creates manifest files for the shipments that are passed and is usually done at the end of the day. There is no maximum on the number of shipments you can manifest, but it is best practice to close out fewer than 500 at a time. Consolidation is not required for all carriers.

Manifest from the dashboard

You can also manifest shipments via the FlavorCloud UI at app.flavorcloud.com/orders.

Example

Request

Response

{
  "AppID": "{{APP ID}}",
  "RestApiKey": "{{API Key}}",
  "Async": false,
  "ShipmentIDs": [
    "ku3027lhufe"
  ]
}

Creating a Webhook

POST https://partnerapi.flavorcloud.com/Webhooks/Subscribe — View endpoint reference →

This call subscribes the provided URL or URLs to a webhook. We recommend using Webhook.site or a similar service for testing — we have no affiliation with these providers.

Example

Request

Response

{
  "AppID": "{{APP ID}}",
  "RestApiKey": "{{API Key}}",
  "WebHooksList": [
    {
      "EventName": "SHIPMENT_CREATED",
      "URL": "https://webhook.site/c57722eb-5f2d-4122-a802-67bfaa2305e3"
    }
  ]
}

Unsubscribe a Webhook

POST https://partnerapi.flavorcloud.com/Webhooks/UnSubscribe — View endpoint reference →

This will unsubscribe the provided event or events from a webhook.

Example

Request

Response

{
  "AppID": "{{APP ID}}",
  "RestApiKey": "{{API Key}}",
  "Events": [
    "SHIPMENT_CREATED"
  ]
}

HS Code Lookup

POST https://partnerapi.flavorcloud.com/Classifications — View endpoint reference →

The Classifications endpoint helps you find HS codes for different products. Send a generic description of the product using the Description field. Generic descriptions classify better than brand-specific ones:

Bluetooth Wireless Headphones

Generic descriptions classify accurately.

Sennheiser HD 450BT

Brand and model names will not match well.

In the response we send back multiple possible classifications for your described product. Different descriptions may share the same HS codes — HS codes can classify single or multiple categories of goods.

Taking the first example above, the HS code is 851830. This code officially classifies "Head-ear-phones & Combined Microphone/speaker Sets." Since Bluetooth headphones fall into this category, we suggest this HS code.

Example

Request

Response

{
  "AppID": "{{APP ID}}",
  "RestApiKey": "{{API Key}}",
  "Reference": "Reference56",
  "Products": [
    {
      "Description": "Bluetooth Wireless Headphone",
      "Image": "https://m.media-amazon.com/images/I/71z97HfSZxS._AC_SX679_.jpg",
      "Title": "Bluetooth Wireless Headphone"
    }
  ]
}

Tracking Lookup

GET https://partnerapi.flavorcloud.com/Tracking/{AppID}/{RestApiKey}/{TrackingNumber} — View endpoint reference →

The tracking endpoint looks up tracking information for a shipment created in FlavorCloud. We return tracking information across all carriers we support. Status details are determined by the carrier.

Valid tracking statuses are:

Status	Meaning
`In Progress`	Label has been created but is not yet with the carrier
`In Transit`	Shipment has been picked up by a carrier
`Delivered`	Carrier has delivered the shipment

The EstimatedDelivery field is only available when the carrier supplies us with this information. Most carriers will not return this until the package has been handed off.

Use webhooks for live updates

We don't recommend using this call for regular tracking updates. See the Subscribe Webhooks endpoint for how to receive real-time updates via webhooks.

Example

Request

Response

Next steps

For a more detailed look at our API endpoints, browse the tutorials in the sidebar or use the API reference for in-depth information on individual endpoints.

B2B Guide

Best practices for high-volume B2B shipping integrations.

Returns Guide

How to handle returns end-to-end with the FlavorCloud API.

API Reference

Full endpoint documentation, parameters, and response schemas.

The four-step integration#

Authentication#

Getting Rates#

Example#

Creating Shipments#

Example#

Manifesting Shipments#

Example#

Creating a Webhook#

Example#

Unsubscribe a Webhook#

Example#

HS Code Lookup#

Example#

Tracking Lookup#

Example#

Next steps#

The four-step integration

Authentication

Getting Rates

Example

Creating Shipments

Example

Manifesting Shipments

Example

Creating a Webhook

Example

Unsubscribe a Webhook

Example

HS Code Lookup

Example

Tracking Lookup

Example

Next steps