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:

{
    "uuid": "9dbb0cb3-e921-44be-abac-600e1d9fd04e",
    "message": "Request failed - status: 400 - body: Order with order id order#13 already exists"
}

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 accepted

Order types#

A shipment order is sent to a parcel company to create and pick up a parcel.

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/shipment/orders`#

Create a shipment 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.

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.

A shipment order response is sent when a carrier confirms shipment of a parcel. This message includes tracking information for the parcel, if available.

A delivery notification is sent when a carrier confirms a delivery (attempt) at the customer.

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>/shipmentOrderResponse`#

Confirms shipment.

Headers:

Authorization: ${HMAC signature}
Content-Type: application/json

Example payload:

{
    "orderId": "orderId#50007",
    "customerId": "customerId",
    "merchantCodeptId": "MT_DE_2",
    "shippingAddress": {
        "name": "John",
        "lastName": "Doe",
        "additionalName": "additionalName",
        "companyName": "Codept",
        "street": "Kollwitzstraße",
        "houseNumber": "64",
        "zip": "10435",
        "city": "Berlin",
        "state": "BE",
        "country": "DE",
        "postbox": "postbox",
        "gpsLocation": "gpsLocation",
        "telephoneNumber": "+4917695363136",
        "addressRemark": "red door in the back yard"
    },
    "parcels": [
        {
            "carrierName": "UPS",
            "carrierService": "standard",
            "clientReferenceNumber": "reference-number#1",
            "trackingId": "1ZX9X7856820459156",
            "base64LabelImage": "Cl5YQQ0KXkxSTg0KXk1OWQ0KXk1GTixODQpeTEgxMCwxMg0KXk1DWQ0KXlBPSQ0KXlBXODEyDQpeQ0kyNw0KXkZPMjg0LDUyNF5CWTNeQkNOLDEwNyxOLE4sTixBXkZWNDIwMTA0MzVeRlMNCl5GTzY2LDc5Ml5CWTNeQkNOLDIwOCxOLE4sTixBXkZWMVpYOVg3ODU2ODIwNDU5MTU2XkZTDQpeRk8yMCw0MzFeQ1ZZXkJEM15GSF9eRkQwNjgyNzYxMDQzNSBbKT5fMUUwMV8xRDk2MVoyMDQ1OTE1Nl8xRFVQU05fMURYOVg3ODVfMUQyNjBfMURfMUQxLzFfMUQyXzFETl8xRF8xREJFUkxJTl8xREJFXzFFXzA0XkZTDQpeRk8xNSw3XkEwTiwyMCwyNF5GVk1ZQ1MgSU5DXkZTDQpeRk8xNSwyN15BME4sMjAsMjReRlYxMjM0NTY3ODleRlMNCl5GTzE1LDQ3XkEwTiwyMCwyNF5GVk1ZQ1NNWUNTIElOQ15GUw0KXkZPMTUsNjdeQTBOLDIwLDI0XkZWTEVHSUVOREFNTSAxMjNeRlMNCl5GTzE1LDg3XkEwTiwyMCwyNF5GVjEwMTE1ICBCRVJMSU4gQkVeRlMNCl5GTzE1LDE0Ml5BME4sMjgsMzJeRlZTSElQIFRPOiBeRlMNCl5GTzYxLDE2Nl5BME4sMjgsMzJeRlZDT0RFUFReRlMNCl5GTzYxLDE5NF5BME4sMjgsMzJeRlY0OTE3Njk1MzYzMTM2XkZTDQpeRk82MSwyMjJeQTBOLDI4LDMyXkZWSk9OQVNHUlVOV0FMRF5GUw0KXkZPNjEsMjUxXkEwTiwyOCwzMl5GVktPTExXSVRaU1RSQd9FIDY0XkZTDQpeRk82MSwyNzleQTBOLDQ1LDQ0XkZWMTA0MzUgIEJFUkxJTiAgQkVeRlMNCl5GTzQ0Niw5XkEwTiwzMCwzNF5GVjIgS0deRlMNCl5GTzY4Myw5XkEwTiwyOCwzMl5GVjEgT0YgMV5GUw0KXkZPNTA4LDUxXkEwTiwyMiwyNl5GVlNIUCM6IFg5WDcgODU5SyBITDReRlMNCl5GTzUwOCw3M15BME4sMjIsMjZeRlZTSFAgV1Q6IDEuNSBLR15GUw0KXkZPNTA4LDk1XkEwTiwyMiwyNl5GVkRXVDogMywyLDFeRlMNCl5GTzI2OSw0MzZeQTBOLDgwLDcwXkZWREVVIDE1MyA1LTAwXkZTDQpeRk8xMCwxMDMxXkEwTiwyMiwyNl5GVkJJTExJTkc6IFAvUF5GUw0KXkZPNTg2LDEwMzVeQTBOLDYwLDY0XkZWRURJXkZTDQpeRk8xNzUsMTIwM15BME4sMTQsMjBeRlZYT0wgMjAuMDguMDUgICAgICAgICAgTlY0NSAzMS4wQSAwNy8yMDIwKl5GUw0KXkZPMjI0LDg1M15BME4sOTUsNzReRlZTQU1QTEVeRlMNCl5GTzksNjcwXkEwTiw1Niw1OF5GVlVQUyBTVEFOREFSRF5GUw0KXkZPOSw3MzFeQTBOLDI2LDMwXkZWVFJBQ0tJTkcgIzogMVogWDlYIDc4NSA2OCAyMDQ1IDkxNTZeRlMNCl5GTzY4OSw2NTBeR0IxMjQsMTI1LDEyNCxCLDBeRlMNCl5GTzAsNjQ4XkdCODExLDE0LDE0LEIsMF5GUw0KXkZPMCw0MjNeR0I4MTIsNCw0LEIsMF5GUw0KXkZPMjQ0LDQyM15HQjQsMjI1LDQsQiwwXkZTDQpeRk8wLDc3NF5HQjgxMiw1LDUsQiwwXkZTDQpeRk8wLDEwMTNeR0I4MTIsMTQsMTQsQiwwXkZTDQpeRk82MjksMTE0NwpeR0ZBLDAwOTY5LDAwOTY5LDAxOSxGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRjAwMDAwMDAwMA0KRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkYwMDAwMDAwMDANCkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGMDAwMDAwMDAwDQpGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRjAwMDAwMDAwMA0KRjAwMDAwMDAwMDAwMDFGODAwMDAwMDAwMDAwMEYwMDAwMDAwMDANCkYwMDAwMDAwMDAwMDAxRjgwMDAwMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwM0Y4MUY4M0ZDMDAwMDAwMDAwRjAwMDAwMDAwMA0KRjAwMDAwMDAwMDNGODFGODNGQzAwMDAwMDAwMEYwMDAwMDAwMDANCkYwMDAwMDAwMDBGRkY5RjlGRkYwMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwRkZGOUY5RkZGMDAwMDAwMDAwRjAwMDAwMDAwMA0KRjAwMDAwMDAwMEZGRkZGRkZGRkMwMDAwMDAwMEYwMDAwMDAwMDANCkYwMDAwMDAwMDBGRkZGRkZGRkZDMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwRjA3RkZGRjBGQzAwMDAwMDAwRjAwMDAwMDAwMA0KRjAwMDAwMDAwMEYwN0ZGRkYwRkMwMDAwMDAwMEYwMDAwMDAwMDANCkYwMDAwMDAwMDBGQzFGRkZDM0YwMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwRkMxRkZGQzNGMDAwMDAwMDAwRjAwMDAwMDAwMA0KRjAwMDAwMDAwMEZGRkZGRkZGRjAwMDAwMDAwMEYwMDAwMDAwMDANCkYwMDAwMDAwMDBGRkZGRkZGRkYwMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwM0ZGRkZGRkZDMDAwMDAwMDAwRjAwMDAwMDAwMA0KRjAwMDAwMDAwMDNGRkZGRkZGQzAwMDAwMDAwMEYwMDAwMDAwMDANCkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGMDAwMDAwMDAwDQpGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRjAwMDAwMDAwMA0KRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkYwMDAwMDAwMDANCkYwMDAwMDAwMDAwMUZGRkZGMDAwMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwMDFGRkZGRjAwMDAwMDAwMDAwRjAwMDAwMDAwMA0KRjAwMDAwMDAwMDAzRkZGOUZDMDAwMDAwMDAwMEYwMDAwMDAwMDANCkYwMDAwMDAwMDAwM0ZGRjlGQzAwMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwM0ZFMUY4N0ZDMDAwMDAwMDAwRjAwMDAwMDAwMA0KRjAwMDAwMDAwMDNGRTFGODdGQzAwMDAwMDAwMEYwMDAwMDAwMDANCkYwMDAwMDAwMDBGRjgxRjgzRkYwMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwRkY4MUY4M0ZGMDAwMDAwMDAwRjAwMDAwMDAwMA0KRjAwMDAwMDAwMEZFMDFGODAzRjAwMDAwMDAwMEYwMDAwMDAwMDANCkYwMDAwMDAwMDBGRTAxRjgwM0YwMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwRjAwMUY4MDBGMDAwMDAwMDAwRjAwMDAwMDAwMA0KRjAwMDAwMDAwMEYwMDFGODAwRjAwMDAwMDAwMEYwMDAwMDAwMDANCkYwMDAwMDAwMDAwMDAxRjgwMDAwMDAwMDAwMDBGMDAwMDAwMDAwDQpGMDAwMDAwMDAwMDAwMUY4MDAwMDAwMDAwMDAwRjBGRkRDMUMwMA0KRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkYwRkZEQzFDMDANCkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGMDBDMUUzQzAwDQpGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRjAwQzFFM0MwMA0KRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkYwMEMxQTJDMDANCkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGMDBDMUI2QzAwDQpGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRkZGRjAwQzFCNkMwMA0KMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMEMxQjZDMDANCjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDBDMTlDQzAwDQowMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwQzE5Q0MwMA0KMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMEMxOUNDMDANCjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDBDMTg4QzAwDQowMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMA0KMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDANCjAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwDQpeRE4NCl5YWg0K"
        }
    ]
}

`POST https://<client-base-url>/deliveryNotification`#

Confirms a delivery (or delivery attempt).