Returns Guide

This guide covers key information regarding the handling of returns in the FlavorCloud API. By the end, you will be able to rate and create return shipments. For a more granular look at returns calls and endpoints, see the API reference.

New to FlavorCloud?

Start with the Getting Started Guide for Merchants for general account setup and core API concepts before working with returns.

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

Rating Return Shipments

POST https://partnerapi.flavorcloud.com/Shipments — View endpoint reference →

Rating return shipments via FlavorCloud is straightforward — pass the IsReturn parameter as "Y".

Example

Request

Response

{
  "AppID": "{{AppID}}",
  "RestApiKey": "{{RestApiKey}}",
  "Reference": "TestOutbound2",
  "WeightUnit": "LB",
  "Currency": "USD",
  "IsReturn": "Y",
  "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": "Receiver Name",
    "AddressLine1": "2412A Victoria Ave.",
    "City": "Brandon",
    "State": "MB",
    "Country": "CA",
    "Zip": "R7B 0M5",
    "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
  }
}

Creating Return Shipments

POST https://partnerapi.flavorcloud.com/Shipments — View endpoint reference →

You can create return shipments via the FlavorCloud API. Follow these guidelines when constructing the request:

Pass the IsReturn parameter as "Y".

The addresses for the return shipment should be the same as the outbound label. FlavorCloud automatically swaps the to and from addresses on the label when creating the return shipment.

Return shipments are associated with outbound shipments using the Reference property and the ShipmentID property. Use the same Reference for the return shipment as the outbound shipment.

Within the create return shipment call, pass the ShipmentID of the outbound call as the ShipmentKey.

All returns are DDU. In most cases, returns travel duty-free.

Looking up the outbound ShipmentID

If you don't have the ShipmentID for the original shipment when creating the return, you can retrieve it using the Get Shipments endpoint.

Example

Request

Response

{
  "AppID": "{{APP ID}}",
  "RestApiKey": "{{RestApiKey}}",
  "Reference": "TestOutbound2",
  "ServiceCode": "STANDARD",
  "ShipmentKey": "kv1asvnh5x9",
  "IsReturn": "Y",
  "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": "Receiver 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": "Z1R3zB7",
  "ReasonForExport": "return",
  "WeightUnit": "LB",
  "Currency": "USD",
  "DimensionUnit": "IN",
  "TermsOfTrade": "DDU"
}

Next steps

Merchant Guide

Best practices and common setups for the FlavorCloud API.

B2B Guide

Configure B2B-specific fields, customs documentation, and tracking.

API Reference

Full endpoint documentation, parameters, and response schemas.

Rating Return Shipments#

Example#

Creating Return Shipments#

Example#

Next steps#

Rating Return Shipments

Example

Creating Return Shipments

Example

Next steps