FlavorCloud API: Cross-Border Rates, Landed Cost, Labels and Tracking

FlavorCloud is a cross-border shipping service. One getallrates request quotes a parcel across FlavorCloud's carrier network at each service level, with the duties and taxes for a Delivered Duty Paid (DDP) delivery, and one submitshipment request creates the label and the customs invoice with the carrier FlavorCloud picked. The flavorcloud carrier talks to the FlavorCloud Partner API.

Credentials#

FlavorCloud issues an AppID and a RestApiKey in its admin console. RocketShipIt exchanges them for a short-lived token on every request, so there is nothing to refresh on your side.

The same values can come from the environment as RS_FLAVORCLOUD_APPLICATION_ID and RS_FLAVORCLOUD_KEY. The key and the token are redacted from meta.debug_information.

No sandbox#

FlavorCloud has no test environment. Rates, landed cost and tracking calls are free, but every submitshipment call creates a real, billable shipment. The test parameter has no effect. Cancel shipments you do not use with voidshipment.

Supported actions#

Address validation, pickups, manifests and return labels are not supported yet.

Required parameters#

FlavorCloud needs more than a domestic carrier does:

• Both addresses need a phone number (ship_phone, to_phone) and an email (ship_email, to_email).
• Every shipment needs at least one customs line. Each line needs customs_description, a six-digit customs_hs_tariff, customs_quantity, customs_weight and a per-unit customs_line_amount (or a line total in customs_value, which is divided by the quantity).
• Each package needs a weight; labels also need length, width and height.

Rates#

getallrates returns one rate per service level and terms of trade. The service level is in service_code and the terms of trade in payment_type:

{
  "desc": "FlavorCloud Express DDP (DHL Express Worldwide)",
  "service_code": "EXPRESS",
  "payment_type": "DDP",
  "rate": 29.18,
  "currency": "USD",
  "est_delivery_time": "2-3 business days",
  "carrier_name": "DHL Express Worldwide",
  "rate_id": "Z15DTMI",
  "duty_rate_id": "Z1Afo2b",
  "rate_detail": [ { "amount": 29.18, "currency": "USD", "type": "shipping" } ],
  "taxes": [
    { "amount": 7,  "currency": "USD", "type": "duty",        "desc": "Import duty" },
    { "amount": 66, "currency": "USD", "type": "sales_tax",   "desc": "Sales tax / VAT" },
    { "amount": 0,  "currency": "USD", "type": "ait",         "desc": "Additional import taxes and fees" },
    { "amount": 73, "currency": "USD", "type": "landed_cost", "desc": "Total duties, taxes and fees" }
  ]
}

• rate is the shipping charge after your account's business rules. commercial_rate is the undiscounted carrier cost and negotiated_rate the discounted one.
• DDP rates carry the duties and taxes in taxes; the landed_cost entry is the total the recipient would otherwise pay on delivery. rate does not include it. DDU rates have no taxes.
• rate_id is FlavorCloud's HashKey and duty_rate_id its DutyHashKey. Pass both back on submitshipment to lock in the quoted price and duties.
• Service levels are EXPRESS, EXPRESS-ECONOMY, STANDARD and STANDARD-ECONOMY. FlavorCloud only returns the levels available for the lane. For an economy rate, FlavorCloud's label API documents the service code ECONOMY.
• carrier_name is the carrier FlavorCloud will hand the parcel to when it names one at rating time; otherwise it is FlavorCloud and the carrier is chosen when the label is created.

Set incoterms to DDP or DDU to request only those terms, and service to one service level to request only that one. Shipments with more than one package are rated with /MultiRates; every package gets its own label.

Creating a label#

{
  "carrier": "FlavorCloud",
  "action": "submitshipment",
  "params": {
    "application_id": "YOUR_APP_ID",
    "key": "YOUR_REST_API_KEY",
    "reference_value": "ORDER-56789",
    "service": "EXPRESS",
    "incoterms": "DDP",
    "rate_id": "Z15DTMI",
    "duty_rate_id": "Z1Afo2b",
    "image_type": "rs_zpl",
    "currency": "USD",
    "weight_unit": "LB",
    "length_unit": "IN",
    "shipper": "Acme Apparel",
    "ship_contact": "Shipping Department",
    "ship_addr1": "200 Townsend Street",
    "ship_city": "San Francisco",
    "ship_state": "CA",
    "ship_code": "94107",
    "ship_country": "US",
    "ship_phone": "4155550100",
    "ship_email": "[email protected]",
    "to_name": "Jane Smith",
    "to_addr1": "89 Pall Mall",
    "to_city": "London",
    "to_code": "SW1Y 5HS",
    "to_country": "GB",
    "to_phone": "442071234567",
    "to_email": "[email protected]",
    "packages": [ { "weight": 1.25, "length": 12, "width": 8, "height": 3 } ],
    "customs": [
      {
        "customs_description": "Blue Polyester T-Shirt",
        "customs_quantity": 1,
        "customs_weight": 0.4,
        "customs_line_amount": 29.00,
        "customs_hs_tariff": "610910",
        "customs_origin_country": "US"
      }
    ]
  }
}

Parameter mapping#

Every request creates a new shipment, even when the reference was used before.

Response#

Each entry in packages carries its own label, base64 encoded, with the tracking number FlavorCloud assigned to that package. shipment_id is FlavorCloud's ShipmentID, which voidshipment needs. documents holds:

• commercial_invoice: the customs invoice PDF. Its metadata says whether FlavorCloud filed it electronically (submitted_electronically). When that is false, print it and attach it to the package.
• links: no content, only metadata with the carrier FlavorCloud picked, the branded tracking_url and the original label_url_N links.

A label or invoice that could not be downloaded is reported as a Warning in errors with its URL, and the rest of the response is returned.

Landed cost#

landedcost quotes duties, taxes and fees without rating shipping. Send the addresses and customs lines as for a label, plus either rate_id (a HashKey from getallrates) or freight_charges so FlavorCloud can include the shipping cost in the dutiable value. The response maps onto the standard landed cost fields: total_duties, total_vat (sales tax), total_shipment_level_taxes_and_fees (FlavorCloud's AIT), total_duty_and_tax and grand_total (duties and taxes plus freight_charges when given).

Tracking#

Pass the tracking_number from submitshipment. Events are returned most recent first with FlavorCloud's status in status_code (In Progress, In Transit, Delivered) and a generic status_type (pre_transit, in_transit, delivered). A Delivered event fills delivered_time and delivery_detail.

Voiding#

voidshipment cancels a shipment by shipment_id (FlavorCloud's ShipmentID from submitshipment), not by tracking number.

Errors#

FlavorCloud validation failures list each offending field. RocketShipIt returns the summary first, then one error per field with FlavorCloud's path to it:

"errors": [
  { "code": "VALIDATION_FAILED", "description": "The request body is invalid. See error object `details` property for more info.", "type": "Error" },
  { "code": "required", "description": "ShipToAddress: should have required property 'Phone'", "type": "Error" },
  { "code": "minLength", "description": "Pieces/0/HSCode: should NOT be shorter than 6 characters", "type": "Error" }
]

An authentication failure is reported the same way with the code AUTHENTICATION_ERROR; check application_id and key.