Send a batch of orders
const url = 'https://api.connectato.com/v1/orders/batch';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"orders":[{"external_id":"example","number":"example","source_state":"example","source_status":"example","fulfillment_status":"example","test":true,"currency":"example","prices_include_tax":true,"totals":{"subtotal":"example","discount":"example","shipping":"example","tax":"example","total":"example"},"payment":{"method":"example","status":"example","gateway":"example","gateway_label":"example","cod":"example"},"billing_address":{"first_name":"example","last_name":"example","company":"example","email":"example","phone":"example","address_line_1":"example","address_line_2":"example","city":"example","region":"example","region_code":"example","postal_code":"example","country_code":"example","tax_id":"example"},"shipping_address":{"first_name":"example","last_name":"example","company":"example","email":"example","phone":"example","address_line_1":"example","address_line_2":"example","city":"example","region":"example","region_code":"example","postal_code":"example","country_code":"example","tax_id":"example"},"line_items":[{"external_id":"example","sku":"example","name":"example","quantity":1,"unit_price":"example","discount":"example","tax_rate":"example","tax":"example","total":"example","weight_kg":"example"}],"shipping_lines":[{"external_id":"example","code":"example","title":"example","price":"example","discount":"example","tax_rate":"example","tax":"example","total":"example"}],"fees":[{"external_id":"example","name":"example","tax_rate":"example","tax":"example","total":"example"}],"delivery":{"method":"example","carrier":"example","pickup_point":{"external_id":"example","provider":"example","name":"example","address":"example"}},"total_weight_kg":"example","placed_at":"2026-04-15T12:00:00Z","updated_at":"2026-04-15T12:00:00Z"}]}'};
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://api.connectato.com/v1/orders/batch \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "orders": [ { "external_id": "example", "number": "example", "source_state": "example", "source_status": "example", "fulfillment_status": "example", "test": true, "currency": "example", "prices_include_tax": true, "totals": { "subtotal": "example", "discount": "example", "shipping": "example", "tax": "example", "total": "example" }, "payment": { "method": "example", "status": "example", "gateway": "example", "gateway_label": "example", "cod": "example" }, "billing_address": { "first_name": "example", "last_name": "example", "company": "example", "email": "example", "phone": "example", "address_line_1": "example", "address_line_2": "example", "city": "example", "region": "example", "region_code": "example", "postal_code": "example", "country_code": "example", "tax_id": "example" }, "shipping_address": { "first_name": "example", "last_name": "example", "company": "example", "email": "example", "phone": "example", "address_line_1": "example", "address_line_2": "example", "city": "example", "region": "example", "region_code": "example", "postal_code": "example", "country_code": "example", "tax_id": "example" }, "line_items": [ { "external_id": "example", "sku": "example", "name": "example", "quantity": 1, "unit_price": "example", "discount": "example", "tax_rate": "example", "tax": "example", "total": "example", "weight_kg": "example" } ], "shipping_lines": [ { "external_id": "example", "code": "example", "title": "example", "price": "example", "discount": "example", "tax_rate": "example", "tax": "example", "total": "example" } ], "fees": [ { "external_id": "example", "name": "example", "tax_rate": "example", "tax": "example", "total": "example" } ], "delivery": { "method": "example", "carrier": "example", "pickup_point": { "external_id": "example", "provider": "example", "name": "example", "address": "example" } }, "total_weight_kg": "example", "placed_at": "2026-04-15T12:00:00Z", "updated_at": "2026-04-15T12:00:00Z" } ] }'Scope: write_orders.
Up to 50 orders of a store app, each whole and named by its external_id, taken in one by one as if sent alone;
the answer holds one result per order, in the batch’s order. For a store’s history and for what a
reconciliation found missing or older: counted apart from the live orders’ rate limit, and checked behind them.
One invalid order refuses the batch (422, errors per orders.<n>.<field>).
Refusals (code, the reason in detail): not_a_store (403), integration_paused (409), order_in_progress
(409: another send of one of its orders is still being taken in; the orders before it are taken, send the batch
again).
Authorizations
Section titled "Authorizations"Parameters
Section titled "Parameters"Header Parameters
Section titled "Header Parameters"1 to 255 visible ASCII characters
A unique value per operation, sent again on a retry: a success or a definitive refusal is replayed for 24 hours; a validation failure, a 429 or a refusal whose code may pass later is not kept, so a retry with the same key runs again.
Request Bodyrequired
Section titled "Request Bodyrequired"Up to 50 orders a store app sends at once (its history, or what a
reconciliation found missing or older), each whole and named by its own
external_id, once per batch. Every order is validated as one sent alone
(the fields of POST /orders); one invalid order refuses the batch whole.
object
object
What the store’s own status means for us, and nothing more: whether the store still considers the order live, cancelled it, or closed it. Set on every sync through the store’s status mapping (settings, editable per integration); the store’s raw value stays in source_status_raw. A fact about the source, never shown as the order’s status: the one status the merchant works with is {@see OrderStatus}, derived from this and the rest.
New values may appear: treat one you do not know as such.
Fulfillment lifecycle, unified across direct stores and marketplaces. Nullable on the order until the source reports a fulfillment state. New values may appear: treat one you do not know as such.
object
object
Our own nomenclator of how an order is paid, independent of the store’s gateway names. Each store gateway maps onto one case through the driver’s payment_method catalog, overridable per integration; the raw gateway stays on the order. Downstream reads only this: the courier collects on CashOnDelivery, the invoice picks its collect type from it.
New values may appear: treat one you do not know as such.
Payment lifecycle. Nullable on the order: some sources do not expose it (marketplaces that own the payment use NotApplicable). New values may appear: treat one you do not know as such.
object
object
object
object
object
object
Where the buyer asked to receive the order, as the store told us: never guessed from the method’s name. A pickup point is a courier’s locker, office or partner shop; a store pickup is the merchant’s own location, no courier.
address |
pickup_point |
store_pickup |
mixed The order’s delivery groups asked for different deliveries (several Woo packages). |
object
Example generated
{ "orders": [ { "external_id": "example", "number": "example", "source_state": "example", "source_status": "example", "fulfillment_status": "example", "test": true, "currency": "example", "prices_include_tax": true, "totals": { "subtotal": "example", "discount": "example", "shipping": "example", "tax": "example", "total": "example" }, "payment": { "method": "example", "status": "example", "gateway": "example", "gateway_label": "example", "cod": "example" }, "billing_address": { "first_name": "example", "last_name": "example", "company": "example", "email": "example", "phone": "example", "address_line_1": "example", "address_line_2": "example", "city": "example", "region": "example", "region_code": "example", "postal_code": "example", "country_code": "example", "tax_id": "example" }, "shipping_address": { "first_name": "example", "last_name": "example", "company": "example", "email": "example", "phone": "example", "address_line_1": "example", "address_line_2": "example", "city": "example", "region": "example", "region_code": "example", "postal_code": "example", "country_code": "example", "tax_id": "example" }, "line_items": [ { "external_id": "example", "sku": "example", "name": "example", "quantity": 1, "unit_price": "example", "discount": "example", "tax_rate": "example", "tax": "example", "total": "example", "weight_kg": "example" } ], "shipping_lines": [ { "external_id": "example", "code": "example", "title": "example", "price": "example", "discount": "example", "tax_rate": "example", "tax": "example", "total": "example" } ], "fees": [ { "external_id": "example", "name": "example", "tax_rate": "example", "tax": "example", "total": "example" } ], "delivery": { "method": "example", "carrier": "example", "pickup_point": { "external_id": "example", "provider": "example", "name": "example", "address": "example" } }, "total_weight_kg": "example", "placed_at": "2026-04-15T12:00:00Z", "updated_at": "2026-04-15T12:00:00Z" } ]}Responses
Section titled "Responses"Array of PushedOrderResource
object
object
The app’s own id of the order, as sent.
Created (first seen); updated (stored as sent); stale (the version held is newer, or has the same updated_at: nothing written, order is the version held); refused (left out by the store’s import rules: nothing stored). New values may appear: treat one you do not know as such.
Why it was refused: before_cutoff (placed before the store’s import cut-off day), excluded_status (its source_status is one the merchant leaves out), test_order (test orders are left out); null otherwise.
The order as held, as GET /orders/{id} shows it; null when refused.
object
The order’s public id (ord_...).
The number the merchant and the buyer know, as the store shows it; null when the store gives none.
The store’s own id of the order.
The store integration (int_..., see /integrations) it came from; null once that integration was removed.
The store’s vendor code: shopify, woocommerce, trendyol, test_store; app for a partner’s app that is a store (which one: integration_id). New values may appear: treat one you do not know as such.
Derived from the facts, never set by hand or by the store: checking, needs_attention, to_process, processed, cancelled, closed. New values may appear: treat one you do not know as such.
The store’s own fulfillment state (filter[fulfillment_status]): unfulfilled, partial, fulfilled, shipped, delivered, returned, restocked, on_hold; null when the store gives none. New values may appear: treat one you do not know as such.
How the order came back (filter[returns]): in_store (marked returned in the store), by_courier (the parcel brought back, until the store restocks, cancels or closes the order). Empty when neither.
When its AWB and invoice were last printed from the app; null while never printed (filter[printed]=printed or not_printed). An AWB undone clears it.
The open issues, blocking first; at most 250. Codes only: the app words them.
object
The exact problem, a stable snake_case code (phone_invalid). Order: address_missing, field_missing, field_too_long, phone_invalid, postal_code_invalid, region_not_found, locality_not_found, locality_sector_missing, payment_method_missing, payment_method_unmapped, pickup_point_missing, pickup_point_unidentified, correction_conflict, correction_conflict_emptied, delivery_service_released. AWB: route_unavailable, route_
The step it holds: awb or invoice. New values may appear: treat one you do not know as such.
The field path (shipping.phone, order.total_weight); null for the order as a whole.
Missing, invalid, not_found, mismatch, unconfigured, conflict, suspicious. New values may appear: treat one you do not know as such.
Blocking (stops its step) or warning. New values may appear: treat one you do not know as such.
Who placed it: the billing contact, else the shipping one.
object
The address the invoice is made out to; null when the store sent none.
object
The fiscal code (CUI, VAT number), for a company.
Where the parcel goes (for a pickup point, only the contact counts); null when the store sent none.
object
The fiscal code (CUI, VAT number), for a company.
In the store’s order; at most 250 (see line_items_count).
object
The product’s name, as sold.
A decimal string, trailing zeros trimmed (2).
One unit before discounts, in the store’s price convention (prices_include_tax).
object
The line’s discount, its share of order discounts included.
object
A percentage (19.0000).
object
The line after every discount, tax included.
object
Every line of the order, also those past the list’s bound.
object
The store’s own id of the shipping method.
The method’s name, as the buyer saw it.
Before discounts, in the store’s price convention.
object
object
object
After discounts, tax included.
object
object
object
Signed: a surcharge positive, an adjustment negative; tax included.
object
ISO 4217; every amount of the order is in it.
Whether the store’s prices (unit prices, subtotal, shipping prices) include tax.
object
object
object
object
object
object
object
Cod, card, bank_transfer, cash, gift_card, store_credit, other; null while the store’s gateway is not mapped. New values may appear: treat one you do not know as such.
Pending, authorized, partially_paid, paid, partially_refunded, refunded, voided, failed, not_applicable; null when the store gives none. New values may appear: treat one you do not know as such.
Cash on delivery: what is left to collect from the buyer; null without.
object
object
What the buyer asked: address, pickup_point, store_pickup, mixed (a shipment’s delivery_method takes the first two). New values may appear: treat one you do not know as such.
The carrier the buyer picked at checkout for a delivery to the door; null for any or another type.
The point the buyer picked; null unless type is pickup_point.
object
The point’s id in its provider’s ids; null while the store named none.
Whose ids the point’s id is in.
The courier service the AWB ships with; null until one is picked.
object
The courier connection (int_...).
In that connection’s service codes.
Manual (the merchant), rule (a delivery rule), fallback (the organization’s default). New values may appear: treat one you do not know as such.
The parcel’s weight in kilograms (the store’s, or the merchant’s correction).
When the buyer placed it, as the store says.
When it last changed at its store, as the store says (a store app’s updated_at, to the microsecond): the version held, which a store app compares with its own.
Example generated
{ "data": [ { "external_id": "example", "result": "example", "reason": "example", "order": { "id": "example", "number": "example", "external_id": "example", "integration_id": "example", "vendor": "example", "status": "example", "fulfillment_status": "example", "returns": [ "example" ], "printed_at": "2026-04-15T12:00:00Z", "issues": [ { "code": "example", "step": "example", "field": "example", "kind": "example", "severity": "example", "detected_at": "2026-04-15T12:00:00Z" } ], "customer": { "name": "example", "email": "example", "phone": "example" }, "billing_address": { "name": "example", "first_name": "example", "last_name": "example", "company": "example", "email": "example", "phone": "example", "address_line_1": "example", "address_line_2": "example", "city": "example", "region": "example", "region_code": "example", "postal_code": "example", "country_code": "example", "locality_code": "example", "tax_id": "example" }, "shipping_address": { "name": "example", "first_name": "example", "last_name": "example", "company": "example", "email": "example", "phone": "example", "address_line_1": "example", "address_line_2": "example", "city": "example", "region": "example", "region_code": "example", "postal_code": "example", "country_code": "example", "locality_code": "example", "tax_id": "example" }, "line_items": [ { "sku": "example", "name": "example", "quantity": "example", "unit_price": { "amount": "example", "currency": "example" }, "discount": { "amount": "example", "currency": "example" }, "tax_rate": "example", "tax": { "amount": "example", "currency": "example" }, "total": { "amount": "example", "currency": "example" } } ], "line_items_count": 1, "shipping_lines": [ { "code": "example", "title": "example", "price": { "amount": "example", "currency": "example" }, "discount": { "amount": "example", "currency": "example" }, "tax_rate": "example", "tax": { "amount": "example", "currency": "example" }, "total": { "amount": "example", "currency": "example" } } ], "fees": [ { "name": "example", "tax_rate": "example", "tax": { "amount": "example", "currency": "example" }, "total": { "amount": "example", "currency": "example" } } ], "currency": "example", "prices_include_tax": true, "totals": { "subtotal": { "amount": "example", "currency": "example" }, "discount": { "amount": "example", "currency": "example" }, "shipping": { "amount": "example", "currency": "example" }, "tax": { "amount": "example", "currency": "example" }, "total": { "amount": "example", "currency": "example" } }, "payment": { "method": "example", "status": "example", "cod": { "amount": "example", "currency": "example" } }, "delivery": { "method": "example", "carrier": "example", "pickup_point": { "external_id": "example", "provider": "example", "name": "example", "address": "example" }, "service": { "integration_id": "example", "code": "example", "selected_by": "example", "selected_at": "2026-04-15T12:00:00Z" } }, "total_weight_kg": "example", "placed_at": "2026-04-15T12:00:00Z", "source_updated_at": "2026-04-15T12:00:00Z", "created_at": "2026-04-15T12:00:00Z", "updated_at": "2026-04-15T12:00:00Z" } } ]}Headers
Section titled "Headers"Requests allowed per minute (per caller; before authentication, failed attempts per address).
Requests left in the current minute.
true when this is the stored answer of an earlier request with the same Idempotency-Key.
Missing or malformed Idempotency-Key (idempotency_key_required, idempotency_key_invalid).
object
The documentation URL of the code.
A short summary of the error, in English.
The HTTP status, repeated.
The stable code: one of bad_request, unauthenticated, insufficient_scope, forbidden, not_found, method_not_allowed, payload_too_large, validation_failed, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused, idempotency_in_progress, conflict, rate_limited, server_error, unavailable, or the code an endpoint declares for a refused action.
The explanation for this case, in English.
Validation only: the messages per field.
object
Example generated
{ "type": "https://example.com", "title": "example", "status": 1, "code": "example", "detail": "example", "errors": { "additionalProperty": [ "example" ] }}Headers
Section titled "Headers"Requests allowed per minute (per caller; before authentication, failed attempts per address).
Requests left in the current minute.
No valid access token.
object
The documentation URL of the code.
A short summary of the error, in English.
The HTTP status, repeated.
The stable code: one of bad_request, unauthenticated, insufficient_scope, forbidden, not_found, method_not_allowed, payload_too_large, validation_failed, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused, idempotency_in_progress, conflict, rate_limited, server_error, unavailable, or the code an endpoint declares for a refused action.
The explanation for this case, in English.
Validation only: the messages per field.
object
Example generated
{ "type": "https://example.com", "title": "example", "status": 1, "code": "example", "detail": "example", "errors": { "additionalProperty": [ "example" ] }}Headers
Section titled "Headers"Requests allowed per minute (per caller; before authentication, failed attempts per address).
Requests left in the current minute.
Bearer: send an access token as a Bearer token.
The app was not granted the scope (insufficient_scope).
object
The documentation URL of the code.
A short summary of the error, in English.
The HTTP status, repeated.
The stable code: one of bad_request, unauthenticated, insufficient_scope, forbidden, not_found, method_not_allowed, payload_too_large, validation_failed, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused, idempotency_in_progress, conflict, rate_limited, server_error, unavailable, or the code an endpoint declares for a refused action.
The explanation for this case, in English.
Validation only: the messages per field.
object
Example generated
{ "type": "https://example.com", "title": "example", "status": 1, "code": "example", "detail": "example", "errors": { "additionalProperty": [ "example" ] }}Headers
Section titled "Headers"Requests allowed per minute (per caller; before authentication, failed attempts per address).
Requests left in the current minute.
A request with this Idempotency-Key is still running, or the action is refused by the record’s state.
object
The documentation URL of the code.
A short summary of the error, in English.
The HTTP status, repeated.
The stable code: one of bad_request, unauthenticated, insufficient_scope, forbidden, not_found, method_not_allowed, payload_too_large, validation_failed, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused, idempotency_in_progress, conflict, rate_limited, server_error, unavailable, or the code an endpoint declares for a refused action.
The explanation for this case, in English.
Validation only: the messages per field.
object
Example generated
{ "type": "https://example.com", "title": "example", "status": 1, "code": "example", "detail": "example", "errors": { "additionalProperty": [ "example" ] }}Headers
Section titled "Headers"Requests allowed per minute (per caller; before authentication, failed attempts per address).
Requests left in the current minute.
true when this is the stored answer of an earlier request with the same Idempotency-Key.
Validation failed (validation_failed, errors per field), the action’s rules refuse it, or an Idempotency-Key was reused for another request (idempotency_key_reused).
object
The documentation URL of the code.
A short summary of the error, in English.
The HTTP status, repeated.
The stable code: one of bad_request, unauthenticated, insufficient_scope, forbidden, not_found, method_not_allowed, payload_too_large, validation_failed, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused, idempotency_in_progress, conflict, rate_limited, server_error, unavailable, or the code an endpoint declares for a refused action.
The explanation for this case, in English.
Validation only: the messages per field.
object
Example generated
{ "type": "https://example.com", "title": "example", "status": 1, "code": "example", "detail": "example", "errors": { "additionalProperty": [ "example" ] }}Headers
Section titled "Headers"Requests allowed per minute (per caller; before authentication, failed attempts per address).
Requests left in the current minute.
true when this is the stored answer of an earlier request with the same Idempotency-Key.
Too many requests: retry after Retry-After seconds.
object
The documentation URL of the code.
A short summary of the error, in English.
The HTTP status, repeated.
The stable code: one of bad_request, unauthenticated, insufficient_scope, forbidden, not_found, method_not_allowed, payload_too_large, validation_failed, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused, idempotency_in_progress, conflict, rate_limited, server_error, unavailable, or the code an endpoint declares for a refused action.
The explanation for this case, in English.
Validation only: the messages per field.
object
Example generated
{ "type": "https://example.com", "title": "example", "status": 1, "code": "example", "detail": "example", "errors": { "additionalProperty": [ "example" ] }}Headers
Section titled "Headers"Requests allowed per minute (per caller; before authentication, failed attempts per address).
Requests left in the current minute.
Seconds to wait before retrying.