Codept Merchant API
In this section we describe the Codept Merchant API, outline all available endpoints for this API and explain how to use each endpoint.
Further information, such as the base endpoint, an example curl snippet that you can use to try out the API, and the details of the authentication mechanism, can be found in the section Getting started with the Codept API.
A note about system states#
Codept internally tracks the state of every sales, purchase and shipment order and notifies you of any changes by means of asynchronous messages. You do not need to track order state in your own systems and can rely instead on Codept for this aspect of your operations.
We cover the Merchant API messages in more detail in the Messages section.
If there is a problem with an API request that is visible at the moment of the request, the Codept API will return an appropriate response: for example, if your JSON is malformed or if a field is incorrectly formatted.
However, errors in the actual order process can’t always be surfaced immediately. Messages must first travel between Codept and the downstream logistics provider to determine that there is in fact an error.
For example, if a warehouse doesn’t send an order response for a specific order within the normal timeframe (which can differ for each provider), this error won’t be surfaced in the API response or the webhook messages Codept sends to your system. Instead, the error will appear in the Codept user interface.
In the Codept interface you can access both an overview of all current errors (called Clarify Matrix) and a detailed view of each order and item on the Order Detail page. In addition, the Codept operations team constantly monitors process errors and proactively works to solve any frequent issues with logistics providers.
Error response format#
Sometimes there is a problem with a request you issue to the Codept Merchant API. In such cases the API will return a response in the following format, designed to help you understand and fix the issue:
When reaching out to the Codept team for help with any API request for which you are seeing an error, please provide the full API response (of course including the error message) when opening a support ticket so that the team can help you understand the issue.
Successful response#
Since every response status other than request validation is communicated by means of asynchronous messages, all API requests that pass validation will return a 200 OK status with the following response in the body:
Order types#
The Codept API distinguishes between three order types.
A sales order is created when a customer places an order with a merchant and indicates that a logistics provider should send an order to a customer.
A purchase order is created when a merchant sends inventory to a logistics provider to inform the provider that items will arrive.
Merchant API endpoints#
In this section we provide a short summary of available API endpoints.
You can find the full reference of all the endpoints with example payloads and possible error messages on our API reference page.
POST /api/v1/sales/orders#
Create a sales order.
Example payload and potential error messages.
POST /api/v1/sales/orders/cancel#
Cancel part or all of a sales order.
Example payload and potential error messages.
POST /api/v1/purchase/orders#
Create a purchase order.
Example payload and potential error messages.
Merchant API messages#
The Codept API internally manages the state of all your orders and communicates any changes in order states, such as when an order transitions from created to shipped, or a returned order transitions from created to received.
Message format and delivery#
Codept messages are sent in JSON format and conform to the API entities' schema.
Messages are delivered to an endpoint in your infrastructure configured during the Codept onboarding process. If you’d like to change the endpoint at which you receive messages, please reach out to the Codept support team.
Keep in mind that Codept will only use the messages to notify you of successful order creations and status updates. Errors are communicated as follows:
If there is an error processing in API call that can be immediately detected, the Codept API will return an error in response to your API call. See the descriptions of the various API endpoints for all possible error responses.
If a problem occurs during the item tracking process, such as a missing response from the warehouse, a missing shipment notification, or a process error, an error will be shown in the Codept console. You can log into the console by navigating to the Codept admin page. Note: you should have received your Codept credentials as part of your onboarding process. If you haven’t received the credentials, or if you've misplaced them, please contact the Codept support team.
On your side, the system that receives the messages must return a 200 OK status for each message; otherwise, the message will be not be marked received, and either the delivery will be retried or an error will appear in the Codept user interface.
Message types#
Codept sends three types of messages.
An order response is sent when a logistics provider acknowledges receipt of a sales order.
A shipment notification is sent when a logistics provider confirms shipment of a parcel. This message includes tracking information for the parcel, if available.
A return arrival confirmation is sent when a logistics provider receives and processes a return of an item.
A stock update is sent when a logistics provider reports an update about available stocks.
Message verification#
To allow you to verify that a message really comes from Codept, each Codept message includes a HMAC signature in the Authorization header. See the Message verification doc for the explanation of how you can verify the messages coming from Codept.
Available messages#
Merchant messages#
POST https://<client-base-url>/orderResponse#
Confirms a successfully processed order.
Important notes:
- If an error was generated for an order, no success message will be sent.
- Multiple
orderResponsemessages may be generated for a single order that contains multiple SKUs, as those SKUs may be fulfilled independently. - It is possible that order creation will succeed for some portions of an order while failing for other portions.
Headers:
Authorization:<HMAC signature>Content-Type:application/json
Example payload:
POST https://<client-base-url>/shipmentNotification#
Confirms a successful shipment of an order or part of an order.
Headers:
Authorization:${HMAC signature}Content-Type: `application/json
Example payload:
POST https://<client-base-url>/returnArrivalConfirmation#
Confirms arrival of a returned item to a logistics center.
Headers:
Authorization:${HMAC signature}Content-Type: `application/json
Example payload:
POST https://<client-base-url>/stockUpdate#
Sends a stock update.
Headers:
Authorization:${HMAC signature}Content-Type:application/json
Example payload: