Get Orders

Time	Status	User Agent
Retrieving recent requests…

Retrieve a paginated list of orders with nested destination address, origin locations, packages, products, and shipments.

Query parameters

Pagination

Parameter	Type	Default	Description
`limit`	number	`20`	Number of orders per page.
`page`	number	`1`	Page number to retrieve.

The totals field in the response indicates the total number of results that match the filter.

Identity filters

Parameter	Type	Description
`order_ids`	array	Up to 300 order IDs.
`order_identifiers`	array	Up to 300 store order identifiers.
`order_name`	string	Order name, for example `"#1290", "290"`.

Workflow status filter: `filter`

Use filter to segment orders by their general lifecycle status. filter and analytics are mutually exclusive; use only one at a time.

Value	Description
`payment-pending`	Waiting for payment confirmation.
`label-pending`	Paid and ready to generate a label.
`pickup-pending`	Shipment created and waiting for pickup.
`shipped`	In transit after carrier pickup.
`canceled`	Order or shipment canceled.
`other`	Miscellaneous status.
`completed`	All packages fulfilled.

Shipment analytics filter: `analytics`

Use analytics to segment orders by the status of their active shipments. analytics and filter are mutually exclusive; use only one at a time.

Value	Applies when...
`unfulfillment`	The order is `payment-pending` and has unfulfilled packages.
`fulfillment`	The order is paid and no shipment has been created yet.
`ready-to-ship`	A shipment has been created with status `Created`.
`out-for-delivery`	The carrier is out for delivery.
`in-transit`	The shipment has been picked up or is in transit.
`delivered`	The shipment has been delivered.
`with-incidents`	The shipment has an incident, such as damage or loss.
`returned`	The shipment was returned to sender.

Additional filters

Parameter	Type	Description
`status_id`	number	General status ID. See Status catalogs.
`status_payment`	array	Payment status: `pending`, `paid`, or `cod`.
`fulfillment_status_id`	array	Fulfillment status IDs. See Status catalogs.
`origin_address_id`	array	Origin location IDs.
`shop_id`	array	Shop IDs.
`destination_country_code`	array	Destination country ISO codes.
`weight`	array	Weight ranges as strings, for example `"1-5"` for 1–5 kg or `"5-"` for more than 5 kg.
`weight_unit`	string	Unit for `weight`: `KG` or `LB`.
`carrier`	string	Carrier name, for example `"fedex"` or `"estafeta"`.
`shipping_method`	array	Shipping service names.
`tracking_number`	string	Exact tracking number.
`product_name`	string	Product name.
`sku`	string	Product SKU.
`product_id`	array	Product IDs.
`quote`	string	Quoted carrier or service name. Minimum length: 3 characters.
`quote_service`	array	Quoted service names.
`tags`	array	Orders that include all specified tags. Maximum: 50 tags.
`logistic_mode`	string	Logistic mode: `me1`, `me2`, `custom`, or `FULFILLMENT_BY_SELLE`.
`date`	string	Creation month and year in `YYYY-MM` format.
`date_from`	string	Start date in ISO 8601 format.
`date_to`	string	End date in ISO 8601 format.

Sorting

Parameter	Values	Description
`sort_by`	Field name	Field used to sort results. Without this parameter, results are limited to the last 6 months.
`sort_direction`	`asc`, `desc`	Sort direction.

Status catalogs

`status_id`: order workflow status

ID	Name
`1`	Payment Pending
`2`	Label Pending
`3`	Pickup Pending
`4`	Shipped
`5`	Canceled
`6`	Other
`7`	Completed

`fulfillment_status_id`: fulfillment status

ID	Name
`1`	Fulfill
`2`	Partial Fulfill
`3`	Unfulfill
`4`	Other
`5`	On Hold

`ecart_status_id`: payment status

ID	Name
`1`	Paid
`2`	Pending
`3`	Refunded
`4`	Cancel
`5`	Other
`7`	authorized
`8`	partially_paid
`9`	partially_refunded
`10`	shipped
`11`	on_hold
`12`	completed

`shipment.info_status.id`: shipment status per package

ID	Name	ID	Name
`1`	Created	`17–19`	Delivery attempts
`2`	Shipped	`20`	Return problem
`3`	Delivered	`21`	Address error
`4`	Canceled	`22`	Undeliverable
`5`	Information	`23`	Delayed
`7`	Pending	`24`	Rejected
`8`	Picked Up	`25`	1 pickup attempt
`9`	Out for Delivery	`26`	Partially Shipped
`10`	Lost	`27`	Partially Delivered
`11`	Returned	`28`	Delivery attempt
`12`	Pickup at Office	`29`	Customs Delay
`13`	Delivered at Origin	`30`	Non-serviceable origin
`14`	Damaged	`31`	Assigned
`15`	Redirected	`32`	Dead freight
`16`	Out for Pickup	`38`	Misrouted

Response structure

{
  "orders_info": [],
  "countries": [],
  "totals": 0
}

Field	Type	Description
`orders_info`	`Order[]`	Orders that match the query parameters.
`countries`	`string[]`	Destination country ISO codes available in your account.
`totals`	number	Total number of matching results for pagination.

Order object

Field	Type	Description
`id`	number	Internal Envia order ID.
`status_id` / `status_name`	number / string	General workflow status.
`ecart_status_id` / `ecart_status_name` / `ecart_status_class`	number / string / string	Payment status.
`fulfillment_status_id`	number	Fulfillment status.
`created_at_ecommerce`	datetime	Creation date in the ecommerce platform.
`estimated_delivery_in`	datetime \| null	Estimated delivery date.
`logistic.mode`	string \| null	Logistic mode.
`order`	object	Order data, including prices, identifiers, and COD.
`order_comment`	object	Internal comment.
`customer`	object	Customer `name`, `email`, and `phone`.
`shop`	object	Shop `id` and `name`.
`ecommerce`	object	Ecommerce platform `id` and `name`.
`shipment_data`	object	Destination address and origin locations with packages.
`tags`	array	Order tags.
`is_favorite`	boolean	Whether the order is marked as favorite.

Package object

Packages are returned inside shipment_data.locations[].packages.

Field	Type	Description
`id`	number	Package ID.
`fulfillment.status`	number	Package-level fulfillment status.
`weight` / `weight_unit`	number / string	Package weight and unit.
`dimensions`	object	Package `height`, `length`, and `width`.
`length_unit`	string	Length unit: `CM` or `IN`.
`package_type_id`	number	Package type: `1` box, `2` pallet, or `3` envelope.
`insurance` / `declared_value`	number / number	Insured value and declared value.
`additional_services`	array	Additional services.
`is_return`	boolean	Whether this is a return package.
`quote`	object	Selected quote, including `price`, `carrier_name`, `service_name`, and related fields.
`shipment`	object	Active shipment. See Shipment object.
`products`	array	Products in the package.

Shipment object

Shipments are returned inside each package.

Field	Type	Description
`tracking_number`	string \| null	Tracking number.
`bol`	string \| null	Bill of lading.
`file`	string \| null	Label URL.
`track_url`	string \| null	Public tracking URL.
`created_at`	datetime \| null	Shipment creation date.
`service_name`	string \| null	Shipping service used.
`total_cost` / `currency`	number / string	Shipment cost and currency.
`shipment_id`	number \| null	Envia shipment ID.
`info_status`	object	Shipment status fields: `id`, `name`, `class_name`, `dashboard_color`, and `is_cancellable`.

Errors

Status	Cause
`400`	Invalid parameter, such as an incorrect `weight` format or more than 50 `tags`.
`401`	Missing or invalid token.
`403`	The token does not have permission to access orders for this account.
`422`	Query parameter validation error.
`500`	Internal server error.

Notes

Without sort_by, the API automatically limits results to the last 6 months relative to the account's most recent order.
filter and analytics are mutually exclusive. Use only one at a time.