Are you a Merchant?
The Getting Started Guide is a little different for you.
Table of Contents
Additional Guides
Getting started for 3PLs, Platforms, or Shipping Providers
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.
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.
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.