Quick Start Guide

This guide will go over best practices and common setup for the Flavorcloud API. By the end of this guide, 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 You Start

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

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.

Getting Rates

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

When you have the full address, parcel, and package information for a shipment then 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 shipment, you are required you use the include_landed_cost 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. The minimum value for applying duty and taxes is called the “de minimis”.

Response Note

Both standard and express arrays will be returned when there is a rate for the given service level i.e., if there is only an express rate available, express will be the only service level returned.

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

Example

Request

{

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

"Zip": "94107",

"Phone": "5555555555",

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

},

"ShipToAddress":{

"Name": "Company Name",

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

}

}

Response

{

""RateId": 7165631,

"Reference": "Reference56",

"Currency": "USD",

"Express": {

"DDP": {

"HashKey": "Z15DTMI",

"ShippingCost": 0,

"ActualShippingCost": 29.18,

"Insurance": 0,

"DiscountedShippingCost": 0,

"Days": "2-3 business days",

"Carrier": "FlavorCloud",

"LandedCostDetail": {

"AIT": 0,

"Duty": 7,

"SalesTax": 66,

"LandedCost": 73,

"DutyHashKey": "Z1Afo2b",

"ActualAIT": 0,

"ActualDuty": 7,

"ActualSalesTax": 66,

"ActualLandedCost": 73

}

},

"DDU": {

"HashKey": "Z2rHnBP",

"ShippingCost": 0,

"ActualShippingCost": 23.18,

"Insurance": 0,

"DiscountedShippingCost": 0,

"Days": "2-3 business days",

"Carrier": "FlavorCloud"

}

},

"RootRequestId": "b0f9e4f2-53c9-4d8f-8376-dba956367e40",

}

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"

}

Unsubscribe a Webhook

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

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"

}

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.

Some other topics we recommend looking at are:

Example

Request

{

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

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

"Events": [

"SHIPMENT_CREATED"

]

}

Response

{

"Status": "Success",

"Message": "WebHook Removed",

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

}

Classifications

HS code lookup

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

The Classifications endpoint is great for assisting in finding HS codes for different products. Send a generic description of the product using the descriptions element. An example of this would be:

thumbs-up

Bluetooth Wireless headphones

thumbs-down

Sennheiser HD 450BT

In the response we will send back multiple possible classifications for your described product.  Different descriptions may have the same HS codes, as HS codes can be used to classify single or multiple categories of goods.

If we take the first example from above, the HS code would be 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

{

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

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

"Reference": "Reference56",

"SKU": "SKU56",

"Description": "Bluetooth Wireless headphones"

}

Response

{

"SKU": "SKU56",

"Classifications":[

{

"HSCode": "851830",

"VectorWeight": 89.62,

"Description": "bluetooth headphones",

"TransportCode":[],

"ExportCode":[]

},

{

"HSCode": "851762",

"VectorWeight": 87.83,

"Description": "bluetooth headset",

"TransportCode":[

TG012

],

"ExportCode":[]

},

{

"HSCode": "851762",

"VectorWeight": 83.68,

"Description": "iphone bluetooth headset",

"TransportCode":[

TG012

],

"ExportCode":[]

},

{

"HSCode": "851830",

"VectorWeight": 82.53,

"Description": "bluetooth earpiece",

"TransportCode":[],

"ExportCode":[]

},

{

"HSCode": "847180",

"VectorWeight": 82.46,

"Description": "bluetooth adapter",

"TransportCode":[],

"ExportCode":[]

},

{

"HSCode": "851830",

"VectorWeight": 79.79,

"Description": "computer headphones",

"TransportCode":[],

"ExportCode":[]

},

{

"HSCode": "851769",

"VectorWeight": 79.59,

"Description": "bluetooth transmitters",

"TransportCode":[],

"ExportCode":[]

},

{

"HSCode": "851830",

"VectorWeight": 79.36,

"Description": "iphone headphones",

"TransportCode":[],

"ExportCode":[]

},

{

"HSCode": "851830",

"VectorWeight": 78.96,

"Description": "earphones",

"TransportCode":[],

"ExportCode":[]

},

{

"HSCode": "847160",

"VectorWeight": 78.35,

"Description": "apple wireless bluetooth mouse",

"TransportCode":[],

"ExportCode":[]

},

{

"HSCode": "851830",

"VectorWeight": 77.25,

"Description": "earbuds",

"TransportCode":[],

"ExportCode":[]

},

{

"HSCode": "851830",

"VectorWeight": 76.86,

"Description": "headset",

"TransportCode":[],

"ExportCode":[]

},

{

"HSCode": "900490",

"VectorWeight": 75.77,

"Description": "VR headset",

"TransportCode":[],

"ExportCode":[]

},

{

"HSCode": "851821",

"VectorWeight": 75.1,

"Description": "bluetooth speaker",

"TransportCode":[],

"ExportCode":[]

},

{

"HSCode": "851830",

"VectorWeight": 73.79,

"Description": "headphones",

"TransportCode":[],

"ExportCode":[]

},

{

"HSCode": "850440",

"VectorWeight": 73.73,

"Description": "Wireless Phone Charger",

"TransportCode":[],

"ExportCode":[

"ED099"

]

},

{

"HSCode": "851830",

"VectorWeight": 73.59,

"Description": "iphone headset",

"TransportCode":[],

"ExportCode":[]

},

{

"HSCode": "851769",

"VectorWeight": 73.2,

"Description": "wireless router",

"TransportCode":[],

"ExportCode":[]

},

{

"HSCode": "851830",

"VectorWeight": 72.7,

"Description": "headphone amplifier",

"TransportCode":[],

"ExportCode":[]

},

{

"HSCode": "847160",

"VectorWeight": 71.61,

"Description": "wireless keypad",

"TransportCode":[],

"ExportCode":[]

},

],

]"RootRequestId": "fd8dac83-a855-4073-9909-ea2e6ad053e7"

}

Tracking

One-off 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 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.

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"

}