Newsletter
FFM – Inbound
  • Home
  • FFM – Inbound

Introduction

ffm.jpg

Last update :

Toolbox / Tips

The Inbound Shipments API enables sellers to notify Octopia Fulfillment warehouses that they are sending inventory to the warehouse. Known as a supply order, this process is critical for efficient stock reception, traceability, and coordination across different countries.

Sellers first need to ensure that the products they plan to send are properly referenced logistically. This is done by registering the GTIN, packaging dimensions, condition, traceability, and customs-related information via the POST /fulfillment-products endpoint. If a product is not previously referenced, any subsequent supply order involving it will be refused.

Once products are referenced, sellers can initiate the supply order by specifying the products, their quantities and their destination. After system validations (e.g. referencing products, country access), the request is forwarded to Octopia Fulfillment. If Accepted, a delivery note is generated for inclusion with the physical shipment. The warehouse then receives the goods, and reception statuses are updated accordingly.

Important — FR, ES, and UK Warehouse Availability Depending on Your Context

The REST Fulfillment API allows storage in FR, ES, and UK warehouses covering all Octopia Fulfillment as 3PL service usecases and external orders.
⚠️ However, products sold on http://Cdiscount.com using Fulfillment services, rely on a specific FR warehouse which does not yet support inbound shipments through APIs. 

  • Cdiscount and Octopia sellers using Fulfillment for sales on Cdiscount.com and other marketplaces within the Octopia marketplaces network, cannot create Supply Orders to the FR warehouse via the REST API
    => inventory supply must be done through the Seller Portal.

Access to certain destinations (e.g. storageCountry: Spain) requires prior activation by an account manager.

Key Attributes

Attribute

Description

inboundShipmentId

Unique identifier for the inbound shipment

reference

Seller’s internal reference for this inbound

code

Auto-generated system code for the inbound (e.g., 100_1689869896673)

status

Current processing status (see lifecycle below)

storageCountry

Target warehouse country (e.g., FR, ES, GB)

supplyMode

Supply method: Fulfillment or XDock

items

List of products included in the inbound

productId

Octopia internal product identifier

gtin

Product barcode (must be referenced first)

productCondition

New, RefurbishedLikeNew, etc.

orderedQuantity

Quantity announced in the inbound request

receiptedQuantity

Quantity actually received by the warehouse

litigationQuantity

Quantity in dispute (e.g., damaged, mislabelled)

receptionDate

Timestamp of warehouse reception

refuseDetail.reason

Reason for refusal (e.g., unknown GTIN)

hasDeliveryNote

Indicates if a delivery note is available

Status Lifecycle

Status

Description

Created

Inbound created and submitted by the seller

Referencing

Product referencing in progress

Referenced

All products successfully referenced

Processing

Inbound received by logistics system, pending validation

Accepted

Inbound accepted by the warehouse/logistics

Refused

Inbound refused due to validation/referencing issues

AppointmentScheduled

Warehouse scheduled a reception slot

InProgress

Reception in progress at warehouse

PartiallyDone

Some products received, others missing

Done

All products received and validated

AutomaticallyDone

System-closed inbound (e.g., after timeout or full reception)

Seller Workflow

inbound.png

Data Availability Period

Data remains available for 25 months after its last update date.

Data refers to : any manipulated object ressource (product/inventory/shipment) as a whole, including ressource and properties.

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

Reference a Fulfillment Product

Prerequisites

  • Products must be declared before any attempt to create an inbound shipment.

  • The GTIN and productCondition must form a unique pair.

  • The sellerProductReference must be unique for each couple of productCondition + GTIN

  • If the product already exists, it cannot be updated, only enriched with missing fields.

This endpoint allows sellers to reference a product that will be stored in a fulfillment warehouse. It is a mandatory prerequisite to initiate any inbound shipment (POST /inbound-shipments). Without referencing, the system will reject the supply order.

This reference declaration provides logistics with key information such as the GTIN, packaging dimensions, weight, condition, customs references, and hazard classification. Once submitted, the product becomes eligible for inclusion in the inbound flow.

Typical scenarios:

  • Creating a brand-new product that has never been stocked before

  • Providing packaging details for international shipping (e.g., customs codes)

  • Adding traceability flags (e.g., IMEI, serial numbers) for regulated products

The response will either confirm creation or return the pre-existing data if the product is already known.

Octopia stores products in a globally shared catalog. This enables extensive product knowledge and federated base product data, including logistic properties, under a single product sheet per GTIN.

Creation precedence applies for each additional information submitted to the catalog.

  • Unknow products will be created

  • Existing products will be completed (if relevant)

sellerProductReference remains unique for any given seller.

Product information restituted can then differ from what was initially submitted through product referencing if the product was previously existing. (this includes but is not limited to : label, dimensions, category properties)

Endpoint to use

  • Request body example:

{
  "gtin": "0697691193670",
  "label": "MORPILOT Sac de transport chien chat",
  "sellerId": 12345,
  "sellerProductReference": "5291030-cd",
  "productCondition": "New",
  "dimensionMinimum": 5,
  "dimensionMedium": 10,
  "dimensionMaximum": 100,
  "weight": 12,
  "categoryUn": "1234",
  "categoryIcpe": "1234",
  "hasExpirationDate": true,
  "traceability": "SerialNumber",
  "customsReference": "1234.56.78",
  "productValue": 5,
  "originCountryCode": "FR",
  "language": "fr-FR"
}

Important notes

  • No update allowed: If the product already exists, new values will not overwrite existing ones. Only empty fields can be populated.

  • Packaging dimensions: All size and weight fields refer to the packed product, as stored in the warehouse.

  • Stock consistency: The sellerProductReference should match the identifier used on sales channels and plugins to ensure alignment with inventory and stock sync later.

  • Retrieving product information: use GET /products to retrieve full product details including logistic details.

Create an Inbound Shipment

Prerequisites

  • The seller must be authorized to ship to the specified country.

  • Logistic referencing must be completed for all products.

  • Active service for targetted storage and shipping country.

Storage/Shipment Country specifics

  • Spain : Requires beforehand service activation by an account manager

This endpoint allows sellers to notify Octopia that they are planning to send stock to a warehouse. It marks the beginning of the inbound lifecycle and is required to trigger referencing and logistics validation. This include creating a supply order for France, United Kingdom or Spain.

Once the request is submitted, the system checks product references and access rights. If valid, the information is forwarded to the logistics partner. The supply order is either accepted or refused, with feedback provided in follow-up calls.

Endpoint to use

  • Request body example:

{
  "reference": "REF01",
  "storageCountry": "FR",
  "supplyMode": "Fulfillment",
  "items": [
    {
      "gtin": "6402386942259",
      "productCondition": "New",
      "quantity": 5
    }
  ]
}

Important notes

  • Country control: Spain (ES) requires prior manual activation by an account manager.

  • Duplicate GTINs: Each GTIN/condition combination must appear only once per shipment.

  • Validation errors: Unauthorized countries or missing references will result in a 400 Bad Request.

Count Inbound Shipments by Filters

Prerequisites

  • Filters can be used to segment the count by reference, code, supplyMode, country, date, or status.

This endpoint returns the number of inbound shipments matching a given set of filters. It is commonly used in back-office dashboards or monitoring jobs to assess shipment volumes, success rates, or SLA conformance.

For example, an integrator may count how many shipments were refused last week, or how many inbounds are scheduled to Spain this month.

Once submitted, the system applies the filters and returns a count integer field with no payload content beyond that.

Endpoint to use

Important notes

  • Efficient usage: Ideal for quick overviews without loading full shipment objects.

  • Matching filters: Same parameters as the search endpoint (date, status, reference…).

  • Empty result: A valid 200 with count = 0 indicates no matching inbounds.

Retrieve Inbound Shipments by Filters

Prerequisites

  • Cursor-based pagination is implemented.

  • Filtering supports status, dates, countries, and more.

This endpoint allows sellers to retrieve a list of inbound shipments that meet certain criteria. It supports a wide range of filters, including status (e.g., Created, Accepted), creation date, country, supply mode, and reference codes.

Use cases include:

  • Retrieving the last 10 inbounds for a seller

  • Finding all “Refused” inbounds for a specific product

  • Filtering all “Accepted” shipments to Spain with a specific product reference

The response provides detailed information on each shipment, including statuses, product lines, reception status, and refusal details if applicable.

Endpoint to use

Important notes

  • Pagination mechanism: Uses a Link header with a cursor to move through results.

  • Data richness: Includes product-level information and reception history.

  • Ordering: Use orderBy=Asc|Desc to control the result order by creation date.

Retrieve a Specific Inbound Shipment

Prerequisites

  • Requires the UUID of the inbound shipment.

This endpoint is used to consult the detailed status and data for a specific inbound shipment. It returns all fields available: reference, country, supply mode, list of items (with GTINs), reception status, and logistics interactions.

Use cases include:

  • Viewing a refused shipment with reasons and impacted GTINs

  • Checking if reception has started or completed

  • Verifying whether a delivery note has been generated

This endpoint is typically called when a user selects a shipment from a list to view full details.

Endpoint to use

Important notes

  • Reception data: Includes quantity received vs. ordered, and litigation counts.

  • Refusal diagnostics: refuseDetail provides clear reasons and affected products.

  • Traceability: Creation and update timestamps are always returned.

Retrieve a Delivery Note for a Shipment

Prerequisites

  • The shipment must have been at least accepted.

  • The hasDeliveryNote field should be checked beforehand.

This endpoint provides access to the delivery note, which is required for warehouse reception. The delivery note is returned in base64-encoded PDF format. Sellers must decode and print this file which has to be provided at warehouse reception.

Intended use cases:

  • Generating the PDF after a successful inbound acceptation

  • Automating the printing of delivery documents before physical shipment

Endpoint to use

Important notes

  • Base64 handling: The file must be decoded client-side before printing.

  • Error handling: A 404 response may indicate the note is not yet available.

  • Compliance: Warehouses may reject deliveries missing this document.

FAQ

 What is an inbound shipment?

It’s a supply order that tells the warehouse you’re sending products to them. It’s the first operational step in using Octopia Fulfillment.

Once the inbound is created and accepted, you receive a delivery note to physically send your goods.

 What information is required to create an inbound shipment?

You need to provide at least:

  • The storageCountry (e.g. FR, ES, GB)

  • A list of products with:

    • gtin

    • productCondition

    • quantity

 Can I send a product that hasn’t been referenced yet?

No — all products must be referenced first using the logistic referencing API (POST /fulfillment-products).

If a product is missing or invalid, the inbound shipment will be rejected during the Referencing workflow stage (status = Refused).

 Can I deliver to any country?

You can only create an inbound to countries you’re authorized for.

Some countries (like Spain) require prior activation by your account manager. Otherwise, the warehouse will reject the request.

 What happens after I submit the inbound shipment?

  1. Upon submission you receive an inboundId

  2. The system checks product referencing

  3. The warehouse is notified

  4. The status moves from Created →[…]→ Accepted or Refused

  5. Once accepted, you can download the delivery note PDF and proceed to ship.

 How do I get the delivery note?

Use this endpoint:
GET /inbound-shipments/{inboundShipmentId}/delivery-notes

You’ll receive a base64-encoded PDF document. It must be printed and added to your physical shipment.

 Can I schedule a delivery date?

Not directly through the API.

Some inbound flows may later trigger an appointment (status = AppointmentScheduled), but that is handled by the logistic partner.

 Can I update or cancel an inbound?

No, once submitted, inbounds cannot be modified. If the request is invalid, it will be Refused. You can then create a new corrected one.

You can cancel the request but only manually on the Octopia fulfillment portal, this cannot be done through the API.

 How do I track the status of my inbounds?

Use either:

  • GET /inbound-shipments with filters (status, reference, country, etc.)

  • GET /inbound-shipments/{inboundShipmentId} for full details

Statuses include:
Created, Referencing, Accepted, InProgress, Done, Refused, PartiallyDone, etc.
Please see technical documentation on detailled statuses

 What does “HasDeliveryNote = false” mean?

It means the warehouse has not yet approved the shipment — no delivery note is available. Wait for the inbound status to become Accepted before requesting the delivery note.

 What happens after the warehouse receives the shipment?

They perform a reception scan and update the status to:

  • InProgress or PartiallyDone

  • Then eventually: Done or AutomaticallyDone

Product-level information like receiptedQuantity, litigationQuantity, and reception dates is then available in the GET /stocks and GET /inbound-shipments endpoints.

 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.

© Octopia 2021 - 2026  —  Legal · API T&C · Octopia T&C · Illegal Content  —  Privacy Policy · Cookie management