Warehouse API
In this section we describe the Codept Warehouse 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 in the Warehouse API#
Codept internally tracks the state of every sales, purchase and shipment order submitted by a merchant and notifies you of any changes by means of asynchronous messages (or callbacks). 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 Codept callbacks in more detail in the Warehouse API Messages section below.
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 merchant to determine that there is an error. The errors that can’t be surfaced right away will instead appear in the Codept warehouse 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 the merchants.
Error response format#
Sometimes there is a problem with a request you issue to the Codept API. In such cases the API will return a response in the following format, designed to help you understand and fix the issue. For example, when you're missing required (e.g. orderId) field, you'll get message similar to:
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 through an asynchronous message, all API requests that pass validation will return a 200 OK status with an empty body in the response.
Request types#
The Codept Warehouse API supports the following tasks:
Sending an order response confirming that an order a merchant sent is accepted.
Sending a shipment notification to the merchant when your warehouse ships an order.
Handling a stock update for a specific merchant.
Warehouse 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/shipment-notification#
By sending a request to this endpoint you can notify the merchant that you shipped a package to the end customer.
Example payload and potential error messages.
POST /api/v1/merchant/{merchantCodeptId}/stock-update#
Use this endpoint to update the merchant on the stock amounts in your warehouse. It’s important to keep the stock levels in sync, otherwise the counts for individual items can diverge over time between the warehouse systems and the merchant systems due to lost and damaged stock and theft.
Example payload and potential error messages.
POST /api/v1/sales/order-response#
The order response endpoint allows you to notify the merchant that you have received the order they sent.
Example payload and potential error messages.
Warehouse API messages#
The Codept API internally manages the state of all the orders the merchants have in progress and communicates any changes in order states, such as when an order is created or cancelled.
Message format and delivery#
Codept messages are sent in JSON format and conform to the same schema that the entities from the API endpoints use.
Messages are delivered to an endpoint in your infrastructure configured in your Codept settings. 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 events. 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 all API endpoints above for all possible error responses.
If a problem occurs during the item tracking process, such as a process error on the merchant side, an error will be shown in the Codept web interface. 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, if you need to reset the credentials, or if you need help logging in, 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 as received, and either Codept will retry the delivery of the message or an error will appear in the Codept web interface.
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.
Message types#
Codept sends four types of messages as part of the Warehouse API.
When Codept receives a request from a merchant that it wants to import new products to a warehouse it sends a product data message to the warehouse.
When Codept receives a request from a merchant that it wants to reserve a place for some items in a warehouse it sends a purchase order message to the warehouse.
When Codept receives a sales order payload from a merchant it process it and sends sales order message to the warehouse.
When Codept receives an order cancel from a merchant it process it and sends order cancel message to the warehouse.
Available messages#
POST https://<warehouse-base-url>/salesOrder#
Communicates that a new order was created.
Important notes:
- A single order message can require multiple
orderResponsecalls from you if the order contains multiple SKUs that will be fulfilled independently.
Headers:
Authorization:${HMAC signature}Content-Type: `application/json
Example payload:
POST https://<warehouse-base-url>/cancelOrder#
Notifies of an order that’s been cancelled by the merchant.
POST https://<warehouse-base-url>/purchaseOrder#
Notifies that the merchant has sent stock to the warehouse.
POST https://<warehouse-base-url>/products#
This message is sent when a merchant creates one or more new products.
Product Data#
You can retrieve merchant product data through our API. Please contact us for detailed specifications
Return Arrival#
When a return arrives at your warehouse you can inform a merchant about it so that they can refund or contact their customers. You can let them know both about the arrival and quality of the returned goods. Please contact us for detailed specifications.