Are you a 3PL?
The Getting Started Guide is a little different for you.
Getting Started Guide for Merchants
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.
Use this postman collection to follow along with the API calls from this guide.
Before starting, you will need to sign up for a FlavorCloud account.
Step 1
Retrieve Shipping Rates
Step 2
Register Shipment Created Event
Step 3
Receive Shipping Info
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:
- 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
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": "CA",
"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": "CA",
"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": "{{API Key}}",
"Async": false,
"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": "{{API Key}}",
"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": "{{API Key}}",
"Events": [
"SHIPMENT_CREATED"
]
}
Response
{
"Status": "Success",
"Message": "WebHook Removed",
"RootRequestId": "f662e5be-93dd-4e2b-b3ba-142a8b237826"
}
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:
Bluetooth Wireless headphones
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": "{{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"
}
]
}
Response
{
"Products": [
{
"Classification": {
"HSCode": "851830",
"Success": "true"
},
"Description": "Bluetooth Wireless Headphone",
"Image": "https://m.media-amazon.com/images/I/71z97HfSZxS._AC_SX679_.jpg",
"Title": "Bluetooth Wireless Headphone"
}
],
"RootRequestId": "c5882293-3f8f-4375-965a-61fd078843e1"
}
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.