Book a shipment
const url = 'https://apibase.ecomweb.app/api/v1/stores/example/orders/1/shipments';const options = { method: 'POST', headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'}, body: '{"service_id":"7bK2mQx9Lp","weight_gr":1500,"length_cm":20,"width_cm":15,"height_cm":10,"cod_amount":0,"freight_payment_method":"cash","use_insurance":true,"note":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://apibase.ecomweb.app/api/v1/stores/example/orders/1/shipments \ --header 'Content-Type: application/json' \ --header 'x-api-key: <x-api-key>' \ --data '{ "service_id": "7bK2mQx9Lp", "weight_gr": 1500, "length_cm": 20, "width_cm": 15, "height_cm": 10, "cod_amount": 0, "freight_payment_method": "cash", "use_insurance": true, "note": "example" }'Books a shipment for the order with the AllinGo carrier, which creates a waybill and schedules a pickup, then marks the order fulfilled. The order must be confirmed or processing, unfulfilled, without an active shipment, and the store must have a connected carrier account and a pickup address. If any later step fails the carrier booking is cancelled again. Booking on a test-mode account creates a simulated shipment.
Required scopes: write:orders
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The order ID.
The store’s ref, as returned by GET /stores.
Request Bodyrequired
Section titled “Request Bodyrequired”object
AllinGo service_id
Example
7bK2mQx9LpGrams
Example
1500Cm
Example
20Cm
Example
15Cm
Example
10VND to collect; 0 for prepaid
Example
0Note to the courier
Responses
Section titled “Responses”object
Carrier platform that booked the shipment. Always allingo.
Whether the booking was made on the carrier’s test or live environment.
Normalized status of the shipment.
Shipment ID.
The carrier platform’s own status code.
Tracking ID of the shipment on the carrier platform, or null.
Tracking ID issued by the delivery partner, or null until one is attached.
Code of the delivery partner, such as ghn.
Name of the delivery partner.
Logo URL of the delivery partner, or null.
ID of the carrier service that was booked.
Name of the carrier service.
Public tracking page on the carrier platform, or null.
Public tracking page of the delivery partner, or null.
Amount the courier collects from the recipient; 0 for a prepaid order.
Total carrier fee, or null while it is not known.
When the shipment was booked, as an ISO 8601 timestamp.
When the shipment was cancelled, or null.
Why the shipment was cancelled, or null.
When the shipment was delivered, or null.
Tracking history, newest first.
object
What recorded the event: a carrier webhook, a manual change or the system.
Event ID.
Normalized shipment status after this event.
The carrier’s name for the status, or null.
When the event happened, as an ISO 8601 timestamp.
Where the parcel was, or null.
A note from the carrier or the merchant, or null.
URLs of proof photos attached to the event.
Example
{ "provider_code": "allingo", "mode": "test", "status": "booked", "events": [ { "source": "webhook" } ]}The request is malformed or failed validation.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The key is missing, invalid, revoked or expired.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The resource does not exist in this store.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The request conflicts with the resource’s current state.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The request is valid but cannot be processed.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}