Newsletter
FFM – Outbound
  • Home
  • FFM – Outbound

Introduction

ffm.jpg

Last update :

Toolbox / Tips

The Outbound Shipments API allows sellers to instruct Octopia Fulfillment to dispatch products stored in warehouses to end customers. This includes creating shipping orders, tracking parcel statuses and managing cancellations.

Business Context & Principles

Before initiating an outbound shipment, the product must be properly referenced in the Octopia system using either a combination of productId and productCondition, or a valid sellerProductReference. If the product is unknown or incorrectly identified, the shipping order will be asynchronously rejected.

Once a product is registered and properly stocked (see inventory, Available), the seller can create an outbound request specifying shipment delivery address, delivery mode, and item details. Depending on the outbound context, additional constraints may apply (see #Create Outbound)

Once Created, the outbound order is passed to the logistic partner. If Accepted, the order moves into Inpreparation and is eventually Shipped to the recipient. Throughout the process, sellers can monitor outbound shipment status, retrieve carrier and parcel information, and – if and when applicable – request cancellation.

Cancellations are only allowed under specific conditions (i.e., before the order is marked as shipped).

This API is designed for operational integration with Octopia’s Fulfillment network across multiple countries.

Key Attributes

Field

Description

outboundShipmentId

Unique identifier of the outbound shipment

reference

Seller’s reference for the shipment

status

Lifecycle status of the shipment.

Possible values:

Created – Shipment is created but not yet validated

Accepted – Shipment accepted by logistics

InPreparation – Shipment is being prepared

Shipped – Shipment has left the warehouse

PartiallyShipped – Only some items shipped

Delivered – Shipment was delivered

Cancelled – Shipment was cancelled

Rejected – Shipment was refused

state.value

Shipment validity: Valid or Invalid

storageCountry

Warehouse country code (FR, ES, etc.)

deliveryMode

Shipping mode: THD, EHD, PPMR, etc.

deliveryAddress

Full delivery address (first name, country code, postal code…)

items

Products included in the shipment

createdAt

Date when the shipment was created

statusUpdatedAt

Timestamp of the last status change

parcels

Physical parcels (with carrier, tracking, delivery date, etc.)

parcels[].status

Parcel status: Packaged, Cancelled, Shipped, Delivered

cancellationRequest

Cancellation metadata, if cancellation was requested

Seller Workflow

outbound_new.png

In this section we will look at how to manage the following cases and ensure maximum control of your orders:

Create an Outbound Shipment

Prerequisites

  • Products must be properly created, supplied and identifiable either by sellerProductReference or by the pair productId + productCondition.

  • Delivery address must include a valid country code (see ISO_3166-1).

  • Delivery mode must be defined for each item, and must be valid for the origin and destination countries.

  • If the delivery mode is of type pickup point (e.g.: PPMR), the pickupId must be provided in the delivery address.

  • If the delivery country is Switzerland (CH), pricing fields (unitSalesPrice, shippingCost, currencyCode) must be provided.

This endpoint is used to create an outbound shipment order from a fulfillment warehouse.

It initiates the outbound process by registering the request with the logistics partner. Once validated, the warehouse proceeds to preparation, shipping, and final delivery.

The system automatically assigns the best logistics partner based on stock availability, delivery country, and performance criteria — unless a storageCountry is explicitly specified.

Endpoint to use

  • Request body example:

{
  "reference": "123456",
  "deliveryAddress": {
    "firstName": "Noel",
    "lastName": "Flantier",
    "email": "noel.flantier@gmail.com",
    "phone": "0600000000",
    "city": "Paris",
    "postalCode": "75000",
    "countryCode": "FR",
    "line": "4 rue de Rio"
  },
  "items": [
    {
      "productId": "WIK0683498200512",
      "productCondition": "New",
      "expectedQuantity": 1,
      "delivery": {
        "mode": "THD"
      }
    }
  ]
}

Important notes

  • Providing productId/productionCondition is optional when sellerProductReference si available

  • Seller product reference is prioritized: If both productId/productCondition and sellerProductReference are present, only sellerProductReference will be used.

  • Pricing fields must be provided when shipping to a country with customs control, such as Switzerland.

  • Invalid or incomplete product identification will cause the shipment creation to be Rejected.

Count Outbound Shipments by Filters

Prerequisites

  • Filters must be provided in query parameters to scope the count appropriately.

This endpoint returns the number of outbound shipments matching a set of filtering criteria.

It is useful for monitoring dashboards, pagination, and performance tracking. It supports filters such as status, country, date ranges, and state.

Endpoint to use

Important notes

  • This endpoint does not return objects, only a numeric count.

  • Use filters consistently with the list endpoint to ensure accuracy.

  • Zero is a valid result, indicating no shipments match the criteria.

Retrieve Outbound Shipments by Filters

Prerequisites

  • Cursor-based pagination is implemented using encoded cursors in the Link header.

  • Filters can include date ranges, status, state, delivery country, and more.

This endpoint retrieves a list of outbound shipments based on filter criteria.

The result includes details for each shipment: reference, delivery info, items, status, and parcel tracking details.

It is essential for displaying outbound shipment history, analyzing processing flows, and tracking parcel dispatches.

Endpoint to use

Important notes

  • Pagination is cursor-based: Use the Link header to navigate between pages.

  • Parcel-level detail is included, enabling customer level restitution.

  • Delivery modes are relevant per item and must be matched with valid partner capabilities.

Retrieve a Specific Outbound Shipment

Prerequisites

  • Requires the unique UUID of the outbound shipment.

This endpoint retrieves a full detail view of a single outbound shipment.

It includes reference data, delivery address, product list, parcel data, shipping and delivery dates, cancellation status, and rejection reasons if applicable.

Endpoint to use

Aucun endpoint trouvé avec l'operationId « get-outbound-shipments-outboundShipmentId ».

Important notes

  • Cancellations are visible in the cancellationRequest object, including status and origin.

  • Parcel details include tracking numbers, weights, carrier names, and shipping timelines.

  • Traceability data is available if the product requires serial or IMEI tracking.

Request an Outbound Shipment Cancellation

Prerequisites

  • Cancellation is allowed only when the shipment status is Created, Accepted, or InPreparation.

  • A cancellation reason must be provided, it is recommended to use one of the documented list in the endpoint’s description.

This endpoint allows a seller to request cancellation of a shipping order that has not yet been fully processed or shipped.

If the shipment is still in an eligible state, the system will either reject it directly or forward the request to the logistics partner for review.

Endpoint to use

  • Request body example:

{
  "outboundShipmentId": "cd795c4c-b9c6-403e-96f3-2ee049c80bf1",
  "reason": "Cancellation at customer's request"
}

Important notes

  • Direct rejections occur when the shipment is in Created.

  • Requests in Accepted or InPreparation are subject to logistic partner decision.

  • Cancellations are forbidden once the shipment is Shipped, Delivered, Rejected, or already Cancelled.

Retrieve a Cancellation Request

Prerequisites

  • Requires the UUID of the cancellation request.

This endpoint retrieves the details of a previously submitted outbound shipment cancellation request.

It includes status (Created, InProgress, Accepted, or Rejected), the entity who submitted the request, the reason, and the timestamp.

Endpoint to use

Aucun endpoint trouvé avec l'operationId « get-outbound-cancellation-request-outboundCancellationRequestId ».

Important notes

  • Cancellation status is also available directly within the shipment object under cancellationRequest.

  • This endpoint is helpful when cancellation decisions are pending or delayed.

  • Traceability is improved with timestamps and the source of the request (API, Connector, Seller).

FAQ

 What is an outbound shipment?

It’s a shipping order you send to Octopia so our logistics partner can deliver products stored in fulfillment warehouses on your behalf.

It includes:

  • Who receives the parcel (delivery address)

  • What to ship (product + quantity)

  • How to ship (delivery mode)

  • Optional: your reference or pricing data

 What do I need to create an outbound shipment?

At minimum:

  • A reference (your internal order ID)

  • A valid deliveryAddress (country, city, postalCode…)

  • One or more items with:

    • productId + productCondition OR sellerProductReference

    • expectedQuantity

    • A valid delivery.mode (e.g. THD, PPMR, etc.)

 Should I include pricing or taxes in the request?

Yes — for shipments to customs regulated destinations (e.g. Switzerland), fields like unitSalesPrice, shippingCost, and currencyCode are mandatory.

 What are the common causes of rejection?

  • The product ID or reference is unknown or not available in the specified warehouse

  • Missing delivery mode or invalid for the country

  • Missing required pricing fields for destination country with customs requirement

  • You don’t have permission for the storageCountry

 What are the valid delivery modes?

Modes vary by country and include:

  • THD – Standard (no signature)

  • SHD, EHD – Signature required

  • PPMR – Pick-up point (requires pickupId)

  • WSHD, FDHD, SRHD – Bulky delivery modes

  • SB2B – B2B delivery mode

Each product’s size and destination has impact on eligible modes.

Note that this list is not exhaustive and some delivery modes might require prior activation or authorization at the account level.

See also Octopia Delivery Modes and provided values enumeration in the technical documentation of POST /outbound-shipments

 How do I track shipment progress?

Use:

  • GET /outbound-shipments (list with filters)

  • GET /outbound-shipments/{id} (details)

You’ll see status, parcel tracking, and delivery info per item.

 What do the outbound statuses mean?

  • Created – Order accepted by API, not yet confirmed

  • Accepted – Order validated by logistics system

  • InPreparation – Order being packed

  • Shipped – Parcel sent to carrier

  • Delivered – Parcel delivered to customer

  • Cancelled – Shipment cancelled (before being shipped)

  • Rejected – Rejected due to invalid data

 How do I cancel an outbound shipment?

Use POST /outbound-cancellation-requests and provide:

  • The outboundShipmentId

  • A valid reason (e.g. “Customer request”, “Suspected fraud”)

If the status is already Shipped, cancellation will be rejected.

 Can I update an outbound shipment?

No. Once created, shipments cannot be modified. You must cancel and re-create a new one if something went wrong.

 Can I test in sandbox?

There is no sandbox available.

Due to the nature of some of the manual operations involved in processing product data, receiving physical goods, and packaging shipments, along with synchronizing multiple warehouses and databases, conducting complete tests is relatively complicated and thus not provided as a common possibility.