Are you a Merchant?

The Getting Started Guide is a little different for you.

Getting started for 3PLs

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

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

3PLIntegration_SetUpAccount

Step 1

Retrieve Shipping Rates

Icon_Generic_Logistics_2

Step 2

Register Shipment Created Event

3PLIntegration_AddNewUser

Step 3

Receive Shipping Info

Icon_Generic_Logistics

Step 4

Get Detailed Tracking Info

Additional Scenarios

Dealing with Returns

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:

  1. In the body of the request
  2. In the request URL

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

Creating Shipments

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

This call will create a label with the carrier for the passed shipments. You can pass 1 or multiple shipments if the ‘to’ and ‘from’ address are the same within the call. We will return a label, tracking, and customs forms for each shipment.

At this time, we do not perform address verification on addresses entered into this call. While we are looking to add this feature, at present, if you enter 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 you include them for all previously rated shipments. This decreases response times by removing the need to recalculate duties and taxes for this call.

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 Note

In the response you will be returned a shipment ID. Please store this ID for future reference. The ID will also be used in the ManifestShipment call.

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

Example

Request

{

"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": "US",

"Zip": "94107",

"Phone": "5555555555",

"Email": "jake.krachman@flavorcloud.com"

},

"ShipToAddress":{

"Name": "Company Name",

"AttentionName": "Reciever 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"

}

Response

{

"ShipmentID": "ku3027lhufe",

"Reference": "10874054",

"TrackingNumber": "9299927280",

"LabelUrl": [

"https://cdn.flavorcloud.com/s-10874054298992412399927280-10874054298992999272809299927280-label.pdf"

],

"Carrier": "DHL",

"TrackingUrl": "https://app.flavorcloud.com/brandedTracking?ref=1087124054&tr_no=9299927280&carrier=DHL&destination=Brandon,%20CA",

"SubmittedElectronically": true,

"CustomsInvoiceURL": "https://cdn.flavorcloud.com/s-1087405429899299927280-1087405429899299927280-invoice.pdf",

"RootRequestId": "62073634-c180-4d0a-8906-ccd940b02cce"

}

Manifesting Shipments

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

This call will create manifest files for the shipments that are passed and is usually done at the end of the day. While there is no maximum on the number of shipments you can manifest, it is best practice to close out less than 500 at a time. Consolidation is not required for all carriers. You can also manifest shipments via our UI at https://app.flavorcloud.com/orders.

Example

Request

{

"AppID": "{{APP ID}}",

"RestApiKey": "{{RestApiKey}}",

"Async": true,

"ShipmentIDs": [

"ku3027lhufe"

]

}

Response

{

"OnwardShipmentIDs":[

"kuek7mkaz8s",

],

"ConsolidatedShipmentID": "kuek8dg88ge",

"RootRequestId": "e3903777-50d8-4677-95a8-54658efdec4d"

}

Creating a Webhook

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

This call will subscribe the provided URL/URLS to a webhook. We recommend using Webhook.site or a similar site for testing, though we have no affiliation with these providers.

Example

Request

{

"AppID": "{{APP ID}}",

"RestApiKey": "{{RestApiKey}}",

"WebHooksList": [

{

"EventName": "SHIPMENT_CREATED",

"URL": "https://webhook.site/c57722eb-5f2d-4122-a802-67bfaa2305e3 "

}

]

}

Response

{

"Reference": "Reference26",

"Status": "Success",

"Message": "Subscribed successfully",

"RootRequestId": "98282373-558b-4d4a-96f1-68adf1a35b5d"

}

POST - https://partnerapi.flavorcloud.com/Webhooks/UnSubscribe

Unsubscribe a Webhook

This will unsubscribe the provided Event/Events from a webhook.

Example

Request

{

"AppID": "{{APP ID}}",

"RestApiKey": "{{RestApiKey}}",

"Events": [

"SHIPMENT_CREATED"

]

}

Response

{

"Status": "Success",

"Message": "WebHook Removed",

"RootRequestId": "f662e5be-93dd-4e2b-b3ba-142a8b237826"

}

Tracking Lookup

GET -https://partnerapi.flavorcloud.com/Tracking/{AppID}/{RestApiKey}/{TrackingNumber}

The tracking endpoint can help lookup tracking information for a shipment created in FlavorCloud. We will return tracking information across all carriers we support. Status details are determined by the carrier. Valid tracking statuses are:

  • In Progress – Label has been created but is not with carrier
  • In Transit – Shipment has been sent with a carrier
  • Delivered – Carrier has delivered the shipment

The EstimatedDelivery field will only be available when the carrier supplies us with this information. Most carriers will not return this information until the package has been sent to them.

Please note: We don’t recommend using this call to receive regular tracking updates. Please see our reference documentation to learn how to get real-time updates for your shipments with webhooks.

Example

Request

 
 
 
 
 
 
 
 
 
 
 
 
 
 

Response

{

"Reference": "123456",

"TrackingNumber": "1688900097625",

"EstimatedDelivery": "",

"TrackingHistory": [

{

"Location": "",

"StatusDate": "2021-09-28T18:14:12",

"StatusDetail": "Shipment created and label generated APC LAX",

"Status": "In Progress"

}

],

"RootRequestId": "5a42d525-8541-492c-a2b3-60f0b6d51a17"

}

Next Steps

For a more detailed look at our API endpoints select from our tutorials on the sidebar. You can also use our reference docs for more in depth information regarding individual endpoints.