Merchant API: create a failed shipment notification

About this article

This article explains how to use POST /v2/shipments/mark-import-as-failed to trigger a notification in ChannelEngine's notification center, alerting all users in your tenant that the shipments of a given order, exported by your merchant system, could not be imported into ChannelEngine.

Table of contents

Introduction

Overview

Requirements

Available API endpoints

• Endpoint: create a failed shipment import notification

Example request

Common issues

Next steps

Introduction

Your merchant system exports shipments to ChannelEngine via POST /v2/shipments. If ChannelEngine cannot import a shipment, the shipment does not appear on ChannelEngine. This can happen because of validation issues, for example when the sum of the shipment-line quantities exceeds the quantity of the corresponding order line. In that case, you can use POST /v2/shipments/mark-import-as-failed to send a notification through ChannelEngine's notification center.

Calling this endpoint triggers a notification that is visible to all users in your ChannelEngine tenant, alerting them that the shipments of one or more orders were not successfully imported into ChannelEngine. This gives your team visibility into the failure directly on ChannelEngine, without requiring them to check external logs or wait for someone to report the issue manually.

Use this endpoint as part of your error handling logic. Once the cause of the failure is resolved, export the corrected shipments again via POST /v2/shipments.

Users can also check the status of the import on ChannelEngine. In Settings, Scheduled tasks, the Import shipments from merchant task shows the status Failed.

Overview

Refer to the diagram below to visualize how a failed shipment import notification fits into the shipment export flow.

Requirements

Before making your first API call, you need the following:

• A ChannelEngine account with at least one channel connected.
• A Merchant API key generated on ChannelEngine at Settings, Merchant API keys.
• Your base API URL constructed from your account subdomain: https://{your-subdomain}.channelengine.net/api.
• One or more ChannelEngine order IDs for the orders whose shipments failed to import. These are returned in the response body of GET /v2/orders/new or GET /v2/orders as the Id field on each order.

Authentication

Every request to the Merchant API must include your API key in the x-ce-key request header:

x-ce-key: your-api-key-here

Available API endpoints

This article covers the following endpoint:

• Create a failed shipment import notification: POST /v2/shipments/mark-import-as-failed
  Triggers a notification in ChannelEngine's notification center for all users in your tenant, indicating that the shipments of the specified orders, exported by your merchant system, could not be imported into ChannelEngine.

Endpoint: create a failed shipment import notification

POST /v2/shipments/mark-import-as-failed sends a notification via ChannelEngine's notification center to all users in your tenant. The notification identifies the affected orders and signals that the import of their shipments into ChannelEngine did not succeed. It does not create the shipment and does not affect the marketplace.

Request body

The request body is a JSON object containing the identifier type and an array of order objects. Each object in the array identifies one order for which a notification should be sent.

Response body

Response codes

Example request

The example below sends a failed shipment import notification for two orders. The first order failed because the shipment line quantities exceed the order line quantity, and the second because a tracking number is too long. Replace the Identifier values with the actual order IDs from your order retrieval response.

POST https://{your-subdomain}.channelengine.net/api/v2/shipments/mark-import-as-failed
x-ce-key: your-api-key-here
Content-Type: application/json

{
  "IdentifierType": "ORDER_ID",
  "Models": [
    {
      "Identifier": 63,
      "FailExportMessage": "Sum of shipment line quantities exceeds order line quantity. OrderLineId: 63, expected: 1, actual: 2"
    },
    {
      "Identifier": 64,
      "FailExportMessage": "Tracking number exceeds the maximum length of 50 characters"
    }
  ]
}

A successful response looks like this:

{
  "StatusCode": 200,
  "RequestId": null,
  "LogId": null,
  "Success": true,
  "Message": "Item successfully updated",
  "ExceptionType": null,
  "ValidationErrors": {}
}

After a successful call, all users in your ChannelEngine tenant see a notification in the Notification center indicating that the shipments of the specified orders were not imported into ChannelEngine. The Import shipments from merchant task in Settings, Scheduled tasks also shows the status Failed.

Common issues

Next steps

• After resolving the issue, export the corrected shipments again via POST /v2/shipments.
• To send the equivalent notification for orders, check out Merchant API: create a failed order export notification.
• For guidance on handling API errors and response codes more broadly, check out Merchant API: errors and response codes.
• For best practices on building resilient integrations, including retry logic and error classification, check out Merchant API: best practices.
• For the full shipment workflow, including creating shipments, retrieving labels, and updating tracking details, check out Merchant API: shipments.
• Include the RequestId and LogId values from any response, when present, when contacting ChannelEngine Support about a specific API call.