Orders
Orders
An Order in Ecart API is the purchase: the moment a customer confirms a transaction in any connected store. Every ecommerce platform represents purchases differently—different structures, field names, and workflows. Ecart API maps each platform's native order into a single canonical shape, so you can list, filter, and read orders the same way whether the store runs on one platform or another.
| What you do | Result |
|---|---|
| List orders (with filters: dates, status, etc.) | Same response structure for every store. |
| Get one order by id | Same fields, normalized. |
So: an Order in Ecart API is the purchase in a normalized form—your app does not need to know the differences between one ecommerce's orders and another's.
In many ecommerces, an order includes a unique id, human-readable number, line items (products and quantities), customer snapshot, billing and shipping addresses, payment and fulfillment status, totals, dates, and one or more shipment units (in Ecart API these are Packages). Create, update, and delete operations depend on each platform; listing and getting orders are supported across all integrated platforms. For endpoint details, see the API Reference (orders).
API endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/v2/orders | List orders with filters. |
| GET | /api/v2/orders/count | Count orders matching the same filters. |
| GET | /api/v2/orders/{id} | Get a single order by its platform id. |
| POST | /api/v2/orders | Create an order. Not available on all platforms. |
| PUT | /api/v2/orders/{id} | Update an order. Not available on all platforms. |
| DELETE | /api/v2/orders/{id} | Delete or cancel an order. Not available on all platforms. |
| POST | /api/v2/orders/{id}/complete | Mark an order as complete. Platform-dependent. |
| POST | /api/v2/orders/{id}/cancel | Cancel an order. Platform-dependent. |
Note: The
{id}parameter is the order's identifier on the connected platform. Ecart API does not generate its own ids for orders; it uses whatever the platform returns.
Query filters
When listing orders, you can pass query parameters to filter, paginate, and sort. Ecart API translates these canonical filters into whatever the connected platform expects.
| Parameter | Description |
|---|---|
ids | Comma-separated list of order ids. |
limit | Maximum number of orders per page. Default varies by platform (typically 50). |
page | Page token or page number for pagination. |
sinceId | Return orders created after this id (cursor-based pagination). |
createdAt[from], createdAt[to] | Filter by creation date range. ISO 8601 recommended. |
updatedAt[from], updatedAt[to] | Filter by last-updated date range. |
status[status] | Filter by the platform's native order status (e.g. open, closed, cancelled). |
status[financial] | Filter by financial status (e.g. paid, pending, refunded). |
status[ecartapi] | Filter by Ecart API canonical status: pending, paid, shipped, cancelled, refunded, authorized, partially_paid, partially_refunded, on_hold, completed. Recommended for cross-platform logic. |
fulfillmentStatus | Filter by fulfillment state (e.g. fulfilled, unfulfilled, partially_fulfilled). |
search | Free-text search (e.g. order name or number). |
sort, sortBy | Sort direction and field (platform-dependent). |
customerId | Filter orders by customer. |
marketplaceId, channel | Marketplace or fulfillment channel (relevant for some platforms). |
sandbox | Set to true for sandbox/test mode where supported. |
Important: Not every filter works on every platform. When in doubt,
createdAt,status[ecartapi], andlimitare the most universally supported. For full reference, see the API Reference (orders).
Main response fields
Every order response follows the same canonical shape. Key areas:
| Area | Main fields |
|---|---|
| Root | id, number, name, email, currency, tags, reference, note |
| Status | status.ecartapi (canonical—use this for cross-platform logic), status.status, status.financial |
| Fulfillment | fulfillmentStatus.ecartapi (e.g. fulfilled, unfulfilled, partially_fulfilled) |
| Totals | totals.subtotal, totals.discount, totals.shipping, totals.tax, totals.total (all strings) |
| Dates | dates.createdAt, dates.updatedAt, dates.paidAt, dates.deliveredAt, dates.canceledAt |
| Customer | customer.id, customer.email, customer.firstName, customer.lastName, customer.phone (snapshot at order time) |
| Addresses | billingAddress, shippingAddress (same structure: address1, city, postalCode, country, state, etc.) |
| Items | items[] — line items with id, productId, variantId, sku, name, quantity, price, fulfillment (order-scoped snapshot, not catalog products) |
| Packages | packages[] — summary of each package: id, fulfillmentOrderId, status, type, locationId; for full detail use the Packages endpoints |
Monetary values are returned as strings to avoid floating-point issues. Prefer status.ecartapi over native status fields when building platform-agnostic logic.
Typical flow
1. List or get orders with filters (e.g.
createdAt,status[ecartapi]).
2. Get one order by id when you need full details or its packages.
3. Use packages (or Packages endpoints) when you need to fulfill—each package has a fulfillmentOrderId used when creating a Fulfillment.
For create/update payloads and per-platform behaviour, see the API Reference (orders).
Updated 30 days ago