Shipment Completion API

Endpoint Details

The following endpoint marks an order shipment as complete, captures payment for the shipment, and triggers a shipment confirmation email:

POST integration/api/shipping/v1/shipments/complete-shipment

All Integration Server endpoints, including this API, require authentication. For more information, see Integration Server API Security.

The endpoint accepts a JSON request body and returns a JSON response.

An OpenAPI specification for the endpoint is available at:

GET integration/api/shipping/v1/shipments/api-docs

Request Body

Field	Type	Required	Description	Example
shipmentNumber	string	Yes	The shipment number of the order shipment to complete. The shipment must be in RELEASED status.	100001-1
carrierTrackingNumber	string	No	The carrier-supplied tracking number to record on the shipment.	1Z999AA10123456784

Example:

{
  "shipmentNumber": "100001-1",
  "carrierTrackingNumber": "1Z999AA10123456784"
}

Response

Success (200 OK)

Field	Type	Description	Example
shipmentNumber	string	The shipment number that was completed.	100001-1
orderNumber	string	The order number associated with the completed shipment.	100001
status	string	The new status of the shipment after completion.	SHIPPED
message	string	A human-readable result message.	Shipment completed successfully.

Example:

{
  "shipmentNumber": "100001-1",
  "orderNumber": "100001",
  "status": "SHIPPED",
  "message": "Shipment completed successfully."
}

Errors

Errors are returned as a JSON object with a single error field describing the failure:

{
  "error": "Shipment not found: 100001-1"
}

The following status codes can be returned:

Status Code	Condition
400 Bad Request	The shipmentNumber is missing or blank, or the shipment is not in RELEASED status.
404 Not Found	No shipment exists with the supplied shipmentNumber.
409 Conflict	The shipment has already been completed (status is SHIPPED). This response is also returned if a concurrent request completes the same shipment first, allowing the caller to treat the request as idempotent.
500 Internal Server Error	The shipment could not be completed due to a server-side failure such as a payment capture error. The response body contains a generic error message to avoid leaking internal details; the underlying cause is logged on the Integration Server.

Behavior

When a valid request is received, the Integration Server performs the following actions:

1. Validates that a shipment with the supplied shipmentNumber exists and is in RELEASED status.
2. Captures payment for the shipment via the configured payment provider.
3. Transitions the shipment status to SHIPPED and records the carrierTrackingNumber on the shipment, if one was supplied.
4. Publishes an order-shipment-shipped event to the VirtualTopic.ep.orders virtual topic. The shipment-shipped email handler consumes this event and sends a confirmation email to the customer.

The shipment confirmation email is therefore sent asynchronously, after the API has returned its response. For more information about the email handler and the underlying virtual topic, see JMS Queues.