Newsletter
Orders Management
  • Home
  • Orders Management

Introduction

transacation_order.jpg

Last update :

Toolbox / Tips

This documentation describes how to manage your orders on Cdiscount and the various Octopia sales channels. It details the different endpoints available and their use, to enable developers to integrate these functions efficiently.

Global overiew of order management.

As an Octopia seller, I’m responsible for collecting and processing orders received through the various channels. To do this, a set of endpoints are available to collect the necessary data and act on your customers’ orders. In this section, we’ll look at the different use cases you can use to manage your orders.

Order Lifecycle :

Upon receiving a new order, Octopia Order Management proceeds to a set of controls to ensure the order is valid. This includes for instance enriching the order with the appropriate data such as the logistic supply mode and commission fees, or controlling the stock and offer status. If and only if all controls are valid will the order be made available to you.

The order will then move through the different states below, according to the actions you perform and the order’s supply mode:

Each order state has the following meaning:

  • Processing: incoming order in the system, indicates that the order is still under review and not yet ready for further processing.

  • WaitingAcceptance: if you chose to validate yourself your orders, you will first have to validate or refuse to fulfill the order (only on Cdiscount)

  • Refused:  Order has been refused (by the seller)

  • Accepted: Order is awaiting final marketplace controls.

  • InPreparation: This status means the order is ready to be shipped by the seller if the supply mode is “Seller”, or is being prepared by the warehouse if the supply mode is “Fulfillment” or “Xdock”.

  • Shipped: indicates the order has been collected by the carrier and is on its way to your customer

  • Delivered: order has been delivered to the end customer (not available on all shipping carriers)

  • Cancelled: an order may be refunded at any time during its lifecycle, resulting into a “cancelled” status. A cancelation may be triggered because of logistic troubles, upon customer request raised through a discussion (see Discussion Management) or by the sales channel’s Customer Services Department. 

The supply mode helps identifying the logistic funnel processing the order :

  • it may be a logistic partner of your choice connected to Octopia, in which case the supply mode value is “Fulfillment” : the status updates will then be provided by the partner itself

  • it may be yourself or logistic partner of your choice not connected to Octopia, in which case the supply mode value is “Seller” : the status updates will then be provided by you

See also : Octopia Delivery Modes

Order line management 

The Order Management  feature allows you to manage your orders at the item level according to the sales channel configuration.

For instance, if the sales channel allows order line management and you receive an order containing 2 items from this sales channel, you may ship one the item on a Monday and the second item the following day. You may also refuse only one of both items.

Note that even when managing orders at the item level, you can only ship order lines that are in the InPreparation status and have supplyMode = “Seller”.

However, not all sales channels are capable of managing orders on item level yet and they may prefer to disable this feature. In which case, updates on item level are not allowed. This means you may only ship a complete order.

Seller Workflow

orders.png

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

Count orders using filters

Prerequisites

  • Understand how filters like status, supplyMode, salesChannelId, createdAtMin or updatedAtMin work.

Allow sellers to estimate the number of orders matching given criteria — without retrieving any order details.
It is particularly useful if you want to:

  • Get a global indicator of order volume based on a status (e.g., “How many InPreparation orders today?”),

  • Generate statistics without retrieving full order details,

  • Optimize your API calls by reducing the volume of transferred data.

Endpoint to use

Important notes :

  • Filters are optional but highly recommended to avoid counting your entire historical data set.

  • Other features also have a route count. However, not all of them return an integer. You need to manage these specifiers on a case-by-case basis.

Retrieve orders using filters

Prerequisites

  • Understand Octopia’s order lifecycle and supply modes.

  • Know how to use time-based filters (created/updated).

  • Be familiar with pagination and sorting parameters.

Allow sellers to retrieve a list of orders by applying filters such as supply modes, order status, dates, sales channel, or business logic (B2B)…
It is designed to give sellers full visibility over their orders and enables them to:

  • List all orders matching specific statuses, dates, supply modes, or shipment statuses,

  • Retrieve critical information needed for order preparation, shipping, or customer support,

  • Manage operations efficiently by accessing real-time order details.

This endpoint supports advanced filtering and pagination to optimize data retrieval.

Endpoint to use

Important notes :

  • Shipping addresses for Fulfillment orders are hidden until shipment.

  • Without any date filters, only latest orders will be returned. Always include at least one time filter (updatedAtMin or createdAtMin) in automated processes.

  • Maximum pageSize is 100. Results are paginated — check Link headers.

Retrieve an order by its ID

Prerequisites

  • Know the orderId from a prior call (e.g. GET /orders).

Allow the seller to retrieve a specific order in detail, for inspection, UI display, or issue handling.
It includes all the same data as /orders, and is typically used for:

  • Order detail pages in a seller back-office

  • Issue resolution (support, refund, cancellation)

  • Tracking / delivery follow-up

Endpoint to use

Important notes

  • Information available through this endpoint is intended only for shipping and end-customer billing.

  • Fulfillment orders will only expose the shipping address after shipment.

  • Selling Price Vs Offer Price : offerPrice is the price defined by the seller for the offer, while sellingPrice is the final price paid by the customer after applying any discounts or promotions.

Approve an order

Prerequisites

  • This functionality applies only to the Cdiscount sales channel.

  • Orders must be in status WaitingAcceptance to be approved.

  • Approval must be done before a deadline, after which the order may auto-expire.

  • Automatic order approval can be enabled from the Octopia Seller Portal (OSP).

Allow Cdiscount sellers to manually accept an order, confirming they are ready to fulfill it.
This ensures the seller has reviewed stock availability, pricing, and fulfillment capacity before proceeding.

Cdiscount orders are initially created with the status WaitingAcceptance.
To confirm the seller’s intent to process the order, they must either:

  • Accept the order manually via API or Portal

  • Or enable automatic approval via the Octopia Seller Portal (OSP) settings

Once the order is approved:

  • Its status transitions to Acceptedfor final control

  • Then it reaches InPreparation and becomes eligible for shipment declaration (/shipments)

  • The cancellation process changes (some cancellation reasons become restricted)

Endpoint to use

Aucun endpoint trouvé avec l'operationId « post-orders-orderId-approval-status ».

Ship an order

Prerequisites

  • The order must be in InPreparation status and at least one line status must be InPreparation.

  • The order’s supplyMode must be Seller (not Fulfillment).

  • You must have the order ID and associated line IDs to ship.

  • Carriers and parcel numbers must be provided.

Allow the seller to confirm that products have been shipped, by declaring carrier name and parcel number.
You must call this API before parcel collection by your carrier.

This is a critical step in the order lifecycle to trigger downstream processes such as customer notification, invoicing, and commission calculation.

Each shipment can contain:

  • One or multiple parcels

  • One or multiple order lines per parcel

  • Tracking URL (optional but recommended)

Once declared:

  • The order status moves to Shipped (or remains InPreparation for partial shipments)

Endpoint to use

Important:

  • Not all sales channels allow partial shipment.

  • Cdicount only enables one parcel per complete order.

  • Trying to ship an order that is already cancelled or in an invalid status will be rejected.

  • For Fulfillment supply modes, you do not call this endpoint — the warehouse does it.

  • Orders in Refused, Cancelled, Shipped or Delivered status cannot be shipped.

Examples of shipment payloads

Full shipment (all order lines shipped in one parcel)
[
  {
    "parcelNumber": "PARCEL-001",
    "carrierName": "Chronopost",
    "trackingUrl": "https://track.example.com/PARCEL-001",
    "orderLineIds": [
      "LINE1",
      "LINE2",
      "LINE3"
    ]
  }
]
Partial shipment (some order lines only)
[
  {
    "parcelNumber": "PARCEL-002",
    "carrierName": "Colissimo",
    "trackingUrl": "https://track.example.com/PARCEL-002",
    "orderLineIds": [
      "LINE1"
    ]
  }
]
Multiple parcels for a single order line

You can associate the same orderLineId to multiple parcels, if the item is shipped in parts or through different transporters:

[
  {
    "carrierName": "LaPoste",
    "orderLineIds": [
      "AYGC",
      "BFCD"
    ],
    "parcelNumber": "PARCEL1",
    "trackingUrl": "http://tracking.example.com/PARCEL1"
  },
  {
    "carrierName": "DPD",
    "orderLineIds": [
      "BFCD"
    ],
    "parcelNumber": "PARCEL2",
    "trackingUrl": "http://tracking.example.com/PARCEL2"
  },
  {
    "carrierName": "Chronopost",
    "orderLineIds": [
      "BFCD"
    ],
    "parcelNumber": "PARCEL3",
    "trackingUrl": "http://tracking.example.com/PARCEL3"
  }
]

In this example:

  • Line AYGC is shipped with 1 parcel (PARCEL1)

  • Line BFCD is shipped with 3 parcels: PARCEL1, PARCEL2, and PARCEL3
    Each with its own carrier and tracking URL.

This is useful for oversized products, separate warehouse routing, or multi-part packaging.

Important notes :

  • Multiple parcels for a single order line is not available on Cdiscount marketplace

Sub-case — know the carrier available

Allow the seller to retrieve the list of shipping carriers available for parcel declarations.

Calling GET /carriers provides:

  • The list of aknown carrierName values

This helps ensure:

  • Parcel declarations use normalized and valid carrier names

  • Buyers receive proper tracking experience (e.g., via known tracking URLs)

Endpoint to use

Important notes

  • The carrierName field is free-form, but we recommend using a value from the bounded list to ensure reliability.

  • Not all carriers are compatible with all delivery modes

  • If the carrier is not provided, the shipment may be considered invalid

Cancel an Order

Allow the seller to cancel one or multiple lines from an order, or the entire order if necessary.
Cancellation may be needed for out-of-stock situations, customer requests, pricing errors, etc.

The commercial gesture system works in three steps:

  1. Retrieve the list of cancellation reasons applicable to the order

  2. Submit a cancellation request:

    1. Either for the full order

    2. Or only for specific lines (partial)

  3. Retrieve cancellation requests to track their processing

Sub-case 1 – Retrieve cancellation reasons

To retrieve the list of cancellation reasons accepted for a given context (seller, customer, sales channel).

Cancellation reasons depend on:

  • The type of requester (Seller, Customer, etc.)

  • The sales channel configuration (Not all sales channels allow partial cancellation)

  • The order or line status (Accepted, Shipped, Delivered, etc.)

This endpoint ensures you only use valid and applicable reasons in subsequent cancellation requests.

Endpoint to use

Important notes

  • Using an invalid reason in a cancellation request will result in a 400 or 409 error

  • The list may vary by sales channel and order status — always retrieve it dynamically

  • Not all sales channels allow partial cancellation

Sub-case 2.a – Submit a full cancellation request

Prerequisites

  • You must have retrieved a valid cancellation reason code first

To cancel the entire order in one request, including all lines.

This endpoint:

  • Registers a total cancellation request for the full order

  • Allows you to choose whether to refund shipping costs (shippingCostRefund)

  • Applies a single reason code to the entire cancellation

Endpoint to use

Example:

{
  "orderSellerId": "SCID01210525142759UT8E",
  "reason": "seller-refusal",
  "shippingCostRefund": true
}

Important notes

  • You cannot use this if any line has already been partially cancelled

  • For Fulfillment orders, cancellation is only allowed if lines are Shipped or Delivered

Sub-case 2.b – Submit a partial cancellation request

Prerequisites

  • You must identify each line to cancel (lineId, offerId)

  • Each line needs an individual reason

To cancel only some lines from a given order.

This endpoint:

  • Accepts a list of lines to cancel

  • Applies line-level cancellation reasons

  • Allows per-line control over shipping refund

Endpoint to use

Example

{
  "orderSellerId": "SCID01210525142759UT8E",
  "lines": [
    {
      "lineId": "AY01",
      "offerId": "OFFER123",
      "reason": "missing-product",
      "shippingCostRefund": true
    },
    {
      "lineId": "BY02",
      "offerId": "OFFER456",
      "reason": "reference-mistake",
      "shippingCostRefund": false
    }
  ]
}

Important notes

  • This does not cancel the whole order — only the specified lines

  • Re-submitting a cancellation for the same line will trigger a 409 Conflict

Sub-case 3 – Retrieve cancellation requests

Prerequisites

  • At least one of these filters is required: orderSellerId, cancellationRequestId

To retrieve all existing cancellation requests for a given order or line.

This endpoint helps:

  • Track partial and total cancellation status

  • Audit who triggered the cancellation (user type, ID)

  • Understand rejections or errors from previous requests

Endpoint to use

Make a commercial gesture

Prerequisites

  • The sales channel must allow commercial gestures for the seller (depends on Saleschannel configuration).

  • The order must be in a post-shipment status (Shipped or Delivered).

  • You must retrieve the gesture configuration before creating a gesture.

Allow a seller to submit, track and validate commercial gesture requests on a given order, such as:

  • Refund for missing item

  • Compensation for delay

  • Refund of shipping or return fees

Gestures are useful for customer satisfaction, quality control follow-up, or loyalty strategies.

The commercial gesture system works in three steps:

  1. Check the sales channel configuration to validate if gestures are allowed and within limits

  2. Submit a gesture request with amount, reason, and optional comment

  3. Track or retrieve previous gesture requests for follow-up or support purposes

Important notes

  • All gesture requests are asynchronous: they are validated later based on internal rules (order status, amount, etc.).

Sub-case 1 – Check the sales channel configuration

To check if a sales channel allows commercial gestures, and retrieve:

  • Maximum allowed rate (%) over the order amount

  • Maximum allowed fixed amount

  • Authorized currency

Use this endpoint before submitting a gesture to avoid rejection due to exceeding:

  • Global max gesture budget

  • Currency mismatches

  • Disabled feature at channel level

Endpoint to use

Aucun endpoint trouvé avec l'operationId « get-orders-orderId-commercial-gestures-available-amounts ».

Important notes

  • Gesture limits are applied on order amount after cancelled lines are excluded

  • Currency must match the sales channel

  • Some channels explicitly forbid gestures (you’ll get allowsGesture: false)

Sub-case 2 – Submit a gesture request

Prerequisites

  • You must know the gesture limits (via previous endpoint)

  • Order must be in Shipped or Delivered status

  • Amount must be below channel limit

  • A valid reason code must be used

To create a new commercial gesture request for a given order, including:

  • Reason (MissingProduct, ShippingFees, etc.)

  • Amount

  • Optional reasonDetails if reason is Other

When calling this endpoint, the system:

  • Validates input (status, reason, limits)

  • Queues the gesture for back-office review

  • Assigns a unique request ID and response status (InProgress, Rejected, Done)

You can track the request later via the listing endpoint.

Endpoint to use

Example

{
  "orderId": "SCID01210525142759UT8E",
  "reason": "MissingProduct",
  "reasonDetails": "Left earbud was not in the package",
  "amount": 9.99
}

Important notes

  • reasonDetails is mandatory if reason is set to Other

  • Order must be post-shipped (cannot create gestures on Accepted or InPreparation)

  • The same gesture cannot be re-submitted if already processed (duplicate = rejected)

Sub-case 3 – retrieve previous gesture

Prerequisites

  • Provide either orderId, status, or date filters to limit scope

To retrieve all existing gesture requests submitted for a given order or channel, with their status and audit data.

This endpoint returns:

  • All commercial gesture requests by the seller

  • Their status (InProgress, Rejected, Done)

  • Reasons, amounts, and possible rejection messages

  • Created / updated timestamps

Useful for:

  • Tracking open gestures

  • Auditing denied requests

  • Displaying gesture history in UIs

Endpoint to use

Important notes

  • The response is paginated — use cursors for navigation

  • If a request is Rejected, details are provided under errors[]

  • Combine this endpoint with order info to show complete gesture history per order

FAQ

 What are the different order statuses, and what do they mean?

An order is created when a customer successfully places a purchase through a connected sales channel.
It becomes visible to the seller via the API once it passes internal eligibility checks (offer status, stock availability, etc.).

Status

Meaning

WaitingAcceptance

Awaiting manual validation by the seller.

Accepted

Order accepted and ready to be prepared.

InPreparation

Order is being processed before shipping.

Shipped

Tracking info has been submitted.

Delivered

Optional — not used in all integrations.

Cancelled

Cancelled by the customer, seller, or system.

Rejected

Order failed validation (e.g. out-of-stock).
 What is “supply mode” and why does it matter?

Each order line has a supplyMode:

  • Seller: you handle storage, preparation, shipping, returns.

  • Fulfillment: Octopia Fulfillment handles operations.

Your actions depend on this mode: for example, you must provide tracking for Seller mode, but not for Fulfillment.

 How do I know when I need to ship an order?

Look at the order’s status (Accepted or InPreparation) and the field shippedAtMax.

This is the latest shipping date you must respect to comply with SLA.

 What happens if I don’t accept or ship the order in time?

You risk:

  • Automatic cancellation.

  • SLA penalties affecting your seller score.

  • Temporary suspension if thresholds are repeatedly missed.

Use the /sellers/indicators endpoint to monitor your performance metrics.

 How do I upload invoices or billing documents?

😅

If enabled for your channel:

  • Use the /orders/invoices API.

  • Attach PDF or XML invoice using order reference.

 What should I do if I receive an order in “Rejected” state?

It means the order failed validation (e.g. offer inactive, no stock).
You don’t need to take action — but you should:

  • Investigate your offer status.

  • Monitor your rejection rate.

Rejections do not count against SLA but may indicate catalog issues.

 Why is VAT at “0”?

The order retrieval API only returns information relevant to order management, not billing.

Depending on your company’s country, the shipment departure country, and the target marketplace, you might responsible for calculating, collecting, and declaring VAT (which is therefore not covered by the marketplace).

Other conditions may apply according to Directive 2017/2455/EU of 5 December 2017, see related documentation here.

The amount of VAT, or rather its calculation, is then responsibility of the seller. The rate (in the API) is returned as declared when your offers are updated/created and depending on the product category, this leads to the return of an uncalculated value in the “amount” field.

Exact VAT amounts paid or collected are still retrievable at the accounting level in Financial operations API.

 Why is Offerid required for partial cancellations?

The offerId uniquely identifies the specific product listing (product + condition + sales channel) sold in the order.
In a partial cancellation, you’re cancelling a specific line within a multi-product order.

Even if the orderLineId is known, the offerId is used to:

  • Match the product to the seller catalog.

  • Validate that the seller is authorized to cancel that specific item.

  • Ensure consistency in refund, stock reallocation and SLA tracking.

 How to handle returns on non-FFM orders ?

If the order’s supplyMode is Seller, you (the seller) are fully responsible for handling the return flow, including:

  • Providing a return address to the customer.

  • Issuing refund or replacement.

  • Optionally generating a return label manually.

Octopia does not manage return logistics or tracking for non-FFM orders.

 What is a valid tracking URL?

A valid tracking URL must:

  • Begin with http:// or https://.

  • Be a complete, public link to the carrier’s tracking page.

  • Allow the customer (or Octopia) to click and follow the shipment without authentication.

  • Be correctly encoded (no spaces or illegal characters).

Valid examples:

https://www.laposte.fr/suivre-vos-envois?code=3Y00523771050
https://www.ups.com/track?tracknum=1Z12345E0205271688

Invalid examples:

  • https://carrier.com/track (missing tracking number)

  • ftp://track.com/123 (wrong protocol)

  • https://tracking.local/internal/abc123 (not publicly accessible)

You can validate the tracking URL format using the following regular expression:

^(http(s?)|HTTP(S?))\:\/\/[0-9a-zA-Z]([-.\w]*[0-9a-zA-Z])*(:(0-9)*)*(\/?)([a-zA-Z0-9\-\.\?\,\~\'\/\\\+&%\$#_=!]*)?$
 How paids the service fees ?

Service fees (such as payment in instalments, marketplace services, compliance charges) are typically:

  • Charged to the customer as part of the order total.

  • Then deducted from the seller payout in the financial settlement.

The seller may see service fees reflected in:

  • The order object (serviceFees list).

  • The invoices and operations under the Finance API (e.g., Operation.ServiceFinancialFlow, invoiceServiceFilePath).

To reconcile payments and service fees: use the /operations or /invoices endpoints.