How it works

The Orders API enables you to address new marketplace orders to the merchants you selected. It offers 3 services :

• create a new order

• retrieve a specific order using your orderId

• retrieve a list of orders thanks to a set of filters.

Pre-requesites : In order to create and retrieve orders, you need a valid access token

Marketplace orders' lifecycle

If you are using Octopia to process marketplace orders, your orders will evolve through the following order states:

• Processing : upon receiving your order, the order management system will proceed to a set of controls and enrichments to ensure your order's readiness.

• Rejected : if any of the controls reveals a problem, your order will be rejected with a self explanatory error message. You may decide to cancel the order, although we do not advise to generate an automatic cancellation upon this status.

• Accepted : if all controls are successful, then your order will be considered as "accepted" and will become available to the different stakeholders (merchant, logistics connector, finance...).

• inPreparation : this status is only available on orders being shipped by a logistics partner connected to Octopia. It informs you your order is being prepared in the warehouse.

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

• Delivered : the order has been delivered to your customer (please note that this status is not available yet).

• Cancelled : an order may be canceled at any time during its lifecycle. A cancelation may be triggered because of logistic troubles, upon customer request raised through a discussion (see Discussion Management) or by your own Customer Services Department. 

Note : by the end of year 2021, you will be able to manage your orders at order line level 

Cancelation reasons

For each status change to "cancelled", a cancelation reason will detail the motive of this change.
The following cancellation reasons may be triggered at different steps of the order life cycle: 

Order refund

By the end of year 2021, a new feature will be provided to address customer refunds. It will allow a merchant to trigger customer refunds after an order cancelation or a commercial gesture.

In the meantime, order refunds should be triggered in your system upon an order status change to "cancelled".

In addition, the choice is given to the merchant to specify if the order must be refunded with or without shipping costs: for instance, an order cancelation after shipment is mostly refunded without shipping costs, as the delivery service as been performed.

The information of shipping costs refund is given through the order cancelation reason: for each order cancelation, a cancelation reason will translate if the shipping costs need to be refunded to the final customer or not.

The following format is used: cancelation-reason-WithShippingCost or cancelation-reason-WithOutShippingCost

For instance:

• Seller-refusal-WithShippingCost

• Reference-error-WithOutShippingCost

Please note, as soon as the Refund API will be available and according to the version you are connected to, the cancelation reason will be simplified to display the motive only.

Dropshipping orders' lifecycle

If you are using Octopia to process dropshipping orders, your orders will evolve through the following order states:

• pending : if you subscribed to the direct payment by credit card solution, you orders will be set to "pending" while payment processing. If payment fails, your order status will change to "rejected", if not to "processing".

• processing : upon receiving your order, the order management system will proceed to a set of controls and enrichments to ensure your order's readiness.

• rejected : if any of the controls reveals a problem, your order will be rejected with a self explanatory error message. You may decide to cancel the order, although we do not advise to generate an automatic cancellation upon this status.

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

• cancelled : an order may be canceled at any time during its lifecycle. A cancelation may be triggered because of logistic troubles or upon customer request.