List orders

curl -X GET 'https://order.api.e-cross.tech/ext/orders?status=READY_TO_SHIP&nextPageToken=' \
  -H 'Authorization: Bearer YOUR_TOKEN'

{
  "orders": [
    {
      "orderId": "ACME-ECOM-TEST-003",
      "merchantId": "ACME",
      "salesChannelOrderId": "TEST-003",
      "salesChannel": "ECOM",
      "status": "READY_TO_SHIP",
      "fulfillmentWarehouseType": "MERCHANT",
      "value": 234,
      "taxType": "DDU",
      "currency": "BRL",
      "foreignCurrency": "USD",
      "customerDocument": "1234567890",
      "creationDate": "2023-10-27T19:10:00Z",
      "lastUpdateDate": "2023-10-27T19:18:54.301Z",
      "totals": {
        "orderValue": 234,
        "itemsGross": 234,
        "itemsDiscount": 0,
        "shippingGross": 0,
        "shippingDiscount": 0,
        "taxes": 0,
        "grossInboundValue": 234,
        "fees": 0,
        "netInboundValue": 234
      },
      "totalsForeignCurrency": {
        "orderValue": 45,
        "itemsGross": 45,
        "itemsDiscount": 0,
        "shippingGross": 0,
        "shippingDiscount": 0,
        "taxes": 0,
        "grossOutboundValue": 45,
        "fees": 0,
        "netOutboundValue": 45
      },
      "items": [
        {
          "id": "c62c9ca2-de02-4580-94e5-e1fef5cb8e7c",
          "skuId": "ACME-1",
          "salesChannelSkuId": "1",
          "ean": "0799439112766",
          "quantity": 1,
          "name": "Awesome Toy",
          "countryOfOrigin": "CN",
          "listPrice": 234,
          "salePrice": 234,
          "foreignListPrice": 45,
          "foreignSalePrice": 45,
          "invoicedPrice": 45,
          "weight": 0.16,
          "hsCode": "29362900"
        }
      ],
      "customer": {
        "type": "PERSON",
        "firstName": "John",
        "lastName": "Doe",
        "document": "1234567890",
        "email": "john.doe@e-cross.tech",
        "phone": {
          "countryCode": "55",
          "areaCode": "11",
          "number": "999999994"
        },
        "billingAddress": {
          "country": "BR",
          "state": "SP",
          "city": "São Paulo",
          "postalCode": "01218-000",
          "street": "Alameda Cleveland",
          "number": "31",
          "neighborhood": "Campos Elíseos",
          "receiverName": "John Doe"
        }
      },
      "shipping": {
        "outboundCountry": "CN",
        "deliveryAddress": {
          "country": "BR",
          "state": "SP",
          "city": "São Paulo",
          "postalCode": "01218-000",
          "street": "Alameda Cleveland",
          "number": "31",
          "neighborhood": "Campos Elíseos",
          "receiverName": "John Doe"
        },
        "deliveries": [
          {
            "name": "Normal",
            "company": "Company",
            "clearance": "Postal",
            "lastMileTrackingNumber": "NL970165916BR",
            "leadTime": 7,
            "listPrice": 0,
            "salePrice": 0,
            "deliveryTime": 7,
            "deliveryEstimateDate": "2023-11-07T19:10:00Z",
            "items": [
              "c62c9ca2-de02-4580-94e5-e1fef5cb8e7c"
            ],
            "parcels": [
              {
                "name": "Cardboard Small",
                "code": "CARD_SMALL",
                "parcelId": "ACME800413194788BR",
                "length": 15,
                "width": 10,
                "height": 8,
                "weight": 0.04,
                "netWeight": 0.16,
                "grossWeight": 0.2,
                "items": [
                  {
                    "salesChannelSkuId": "1",
                    "quantity": 1
                  }
                ],
                "documents": [
                  {
                    "name": "Label",
                    "url": "https://pdfobject.com/pdf/sample.pdf"
                  }
                ],
                "events": [
                  {
                    "eventId": "evt_20231027_01",
                    "eventDate": "2023-10-27T19:20:00Z",
                    "code": "AWAITING_PICK_UP",
                    "macroStep": "SHIPMENT_CREATED",
                    "carrierId": "ACME_FULFILLMENT",
                    "externalCode": "AWAITING_PICK_UP",
                    "description": "Order packed and ready for first mile pickup",
                    "location": "Sao Paulo, SP, BR"
                  }
                ]
              }
            ]
          }
        ]
      },
      "payments": [
        {
          "type": "BILL",
          "value": 234
        }
      ]
    }
  ],
  "nextPageToken": "eyJjcmVhdGlvbkRhdGUiOiIyMDIzLTA5LTE2VDIyOjI1OjM5LjkzNloiLCJvcmRlcklkIjoiTVZQLVRFU1QtRUNPTS0wMDEiLCJ0eXBlIjoib3JkZXIifQ=="
}

curl -X GET 'https://order.api.e-cross.tech/ext/orders?status=READY_TO_SHIP&nextPageToken=' \
  -H 'Authorization: Bearer YOUR_TOKEN'

{
  "orders": [
    {
      "orderId": "ACME-ECOM-TEST-003",
      "merchantId": "ACME",
      "salesChannelOrderId": "TEST-003",
      "salesChannel": "ECOM",
      "status": "READY_TO_SHIP",
      "fulfillmentWarehouseType": "MERCHANT",
      "value": 234,
      "taxType": "DDU",
      "currency": "BRL",
      "foreignCurrency": "USD",
      "customerDocument": "1234567890",
      "creationDate": "2023-10-27T19:10:00Z",
      "lastUpdateDate": "2023-10-27T19:18:54.301Z",
      "totals": {
        "orderValue": 234,
        "itemsGross": 234,
        "itemsDiscount": 0,
        "shippingGross": 0,
        "shippingDiscount": 0,
        "taxes": 0,
        "grossInboundValue": 234,
        "fees": 0,
        "netInboundValue": 234
      },
      "totalsForeignCurrency": {
        "orderValue": 45,
        "itemsGross": 45,
        "itemsDiscount": 0,
        "shippingGross": 0,
        "shippingDiscount": 0,
        "taxes": 0,
        "grossOutboundValue": 45,
        "fees": 0,
        "netOutboundValue": 45
      },
      "items": [
        {
          "id": "c62c9ca2-de02-4580-94e5-e1fef5cb8e7c",
          "skuId": "ACME-1",
          "salesChannelSkuId": "1",
          "ean": "0799439112766",
          "quantity": 1,
          "name": "Awesome Toy",
          "countryOfOrigin": "CN",
          "listPrice": 234,
          "salePrice": 234,
          "foreignListPrice": 45,
          "foreignSalePrice": 45,
          "invoicedPrice": 45,
          "weight": 0.16,
          "hsCode": "29362900"
        }
      ],
      "customer": {
        "type": "PERSON",
        "firstName": "John",
        "lastName": "Doe",
        "document": "1234567890",
        "email": "john.doe@e-cross.tech",
        "phone": {
          "countryCode": "55",
          "areaCode": "11",
          "number": "999999994"
        },
        "billingAddress": {
          "country": "BR",
          "state": "SP",
          "city": "São Paulo",
          "postalCode": "01218-000",
          "street": "Alameda Cleveland",
          "number": "31",
          "neighborhood": "Campos Elíseos",
          "receiverName": "John Doe"
        }
      },
      "shipping": {
        "outboundCountry": "CN",
        "deliveryAddress": {
          "country": "BR",
          "state": "SP",
          "city": "São Paulo",
          "postalCode": "01218-000",
          "street": "Alameda Cleveland",
          "number": "31",
          "neighborhood": "Campos Elíseos",
          "receiverName": "John Doe"
        },
        "deliveries": [
          {
            "name": "Normal",
            "company": "Company",
            "clearance": "Postal",
            "lastMileTrackingNumber": "NL970165916BR",
            "leadTime": 7,
            "listPrice": 0,
            "salePrice": 0,
            "deliveryTime": 7,
            "deliveryEstimateDate": "2023-11-07T19:10:00Z",
            "items": [
              "c62c9ca2-de02-4580-94e5-e1fef5cb8e7c"
            ],
            "parcels": [
              {
                "name": "Cardboard Small",
                "code": "CARD_SMALL",
                "parcelId": "ACME800413194788BR",
                "length": 15,
                "width": 10,
                "height": 8,
                "weight": 0.04,
                "netWeight": 0.16,
                "grossWeight": 0.2,
                "items": [
                  {
                    "salesChannelSkuId": "1",
                    "quantity": 1
                  }
                ],
                "documents": [
                  {
                    "name": "Label",
                    "url": "https://pdfobject.com/pdf/sample.pdf"
                  }
                ],
                "events": [
                  {
                    "eventId": "evt_20231027_01",
                    "eventDate": "2023-10-27T19:20:00Z",
                    "code": "AWAITING_PICK_UP",
                    "macroStep": "SHIPMENT_CREATED",
                    "carrierId": "ACME_FULFILLMENT",
                    "externalCode": "AWAITING_PICK_UP",
                    "description": "Order packed and ready for first mile pickup",
                    "location": "Sao Paulo, SP, BR"
                  }
                ]
              }
            ]
          }
        ]
      },
      "payments": [
        {
          "type": "BILL",
          "value": 234
        }
      ]
    }
  ],
  "nextPageToken": "eyJjcmVhdGlvbkRhdGUiOiIyMDIzLTA5LTE2VDIyOjI1OjM5LjkzNloiLCJvcmRlcklkIjoiTVZQLVRFU1QtRUNPTS0wMDEiLCJ0eXBlIjoib3JkZXIifQ=="
}

Query Parameters

string

A single or comma-separated list of order statuses to filter. Refer to the Order Statuses page for the list of available order statuses.

string

Filter orders by fulfillment warehouse type. Accepts MERCHANT, RETURNS, or a comma-separated list such as MERCHANT,RETURNS. If omitted, only MERCHANT orders are returned by default.

string

Filter only orders created after the specified date and time, in ISO 8601 format, inclusive. Example: 2025-03-06T17:14:53Z.

string

Filter only orders created before the specified date and time, in ISO 8601 format, inclusive. Example: 2025-03-06T17:14:53Z.

string

Filter only orders last updated on or after the specified date and time, in ISO 8601 format, inclusive. Example: 2025-03-06T17:14:53Z.

string

Filter only orders last updated on or before the specified date and time, in ISO 8601 format, inclusive. Example: 2025-03-06T17:14:53Z.

string

The token to fetch the next page of results. Use the value returned in the nextPageToken field of the previous request.

Response Fields

array

Array containing Orders that match the specified filters.

string

The token to be used in the query parameter to retrieve the next page of results. If there are no more results, this field won’t be returned.

Order object fields

string

The unique identifier of the order within e-CROSS. Use this in subsequent API calls.

string

The unique identifier of the merchant in the e-CROSS platform.

string

The order identifier in the sales channel.

string

The sales channel where the order was placed. Refer to the Sales Channels page for the list of available sales channels.

string

The current status of the order. Refer to the Order Statuses page for the list of available order statuses.

string

The warehouse type responsible for fulfilling the order: MERCHANT for the regular international flow or RETURNS for orders fulfilled locally by the returns partner.

number

The total value of the order.

string

DDP if taxes are already included in prices. DDU if prices do not have taxes.

string

The currency used by the buyer to place the order.

string

The currency used by the merchant to price the products, a.k.a. “merchant foreign currency”.

string

The document of the customer who placed the order.

string

The date when the order was created.

string

The date when the order was approved. If the order is not approved, this field won’t be returned.

string

The date when the order was canceled. If the order is not canceled, this field won’t be returned.

string

The date when the order started to be handled. If the order is not being handled, this field won’t be returned.

string

The date when the order was put on hold. If the order is not on hold, this field won’t be returned.

string

The date when the order was packed. If the order is not packed, this field won’t be returned.

string

The date when the order was invoiced. If the order is not invoiced, this field won’t be returned.

string

The date when the order was shipped. If the order is not shipped, this field won’t be returned.

string

The date when the order was delivered. If the order is not delivered, this field won’t be returned.

string

The date when the order was last updated. Every time a status changes, this field is updated.

object

Order amounts summary in the buyer’s local currency.

Show totals fields

number

Total order value.

number

Total items gross amount (sum of item.listPrice × item.quantity).

number

Total items discount amount.

number

Total shipping gross amount.

number

Shipping discounts total amount.

number

Total of taxes (import duty and sales taxes).

number

Fees that will be discounted from the order.

number

Gross amount that will be sent for settlement in local currency.

number

Net amount that will be sent for settlement in local currency.

object

Order amounts summary in the merchant currency. Same structure as totals but in the merchant’s foreign currency.

array

Array with one line for each order item.

Show order item fields

string

Unique identifier for this line within the order. Used to define which delivery this line belongs to.

string

SKU ID within the e-CROSS platform.

string

SKU ID of this item in the sales channel.

string

SKU EAN-13 code.

integer

How many pieces of this SKU are being bought.

string

The name of the SKU.

string

required

Country where the SKU was manufactured, as an ISO 3166-1 alpha-2 code. e-CROSS resolves this from the SKU and falls back to the merchant’s country of origin.

number

Unit price, in local currency, with no discounts applied.

number

Unit price, in local currency, with all discounts applied.

number

Unit price converted to foreign currency.

number

Unit price with discounts, converted to foreign currency.

number

Unit price of the item in the commercial invoice.

string

URL to the SKU image.

number

Product weight in kilograms (kg).

string

SKU Harmonized System (HS) code.

object

Array of documents related to the item shipping. If there is no document, this field won’t be returned.

Show shippingDocuments fields

string

Document name

string

Document URL

object

Information about the customer who placed the order.

Show customer fields

string

Type of customer: PERSON (individual) or COMPANY (company).

string

Customer first name.

string

Customer last name.

string

Customer identification document.

string

Customer’s email address.

object

Customer contact phone number.

object

Customer billing address.

Show billingAddress fields

string

Name of the address.

string

Name of the person who will receive the order.

string

Street name.

string

Building number.

string

Any relevant address complement.

string

Neighborhood name.

string

City name.

string

State or province name.

string

Country code, in the ISO-3166 3-digit format.

string

Postal code.

string

Any relevant reference text.

object

Shipping information including delivery address and deliveries (packages).

Show Shipping Fields

string

The 2-digit country code where this order will be shipped from.

object

The buyer’s delivery address in the destination country.

Show deliveryAddress fields

string

Name of the address.

string

Name of the person who will receive the order.

string

Street name.

string

Building number.

string

Any relevant address complement.

string

Neighborhood name.

string

City name.

string

State or province name.

string

Country code, in the ISO-3166 3-digit format.

string

Postal code.

string

Any relevant reference text.

object

The address of the consolidation hub, where the order should be dispatched to in the first mile.

This field is only available for orders that must be shipped to a consolidation hub. In routes configured for the pickup directly in the Merchant warehouse this field doesn’t appear.

Show freightForwarderAddress fields

string

The full address (receiver, street, number, complement).

string

The city name.

string

The state or province name.

string

The address postal code.

string

The country code, ISO-3166 3-digit format.

array

Array of deliveries. Each delivery is composed by one or more packages that must be shipped to the customer.

Show delivery fields

string

The name of this shipping type. This is the text that the customer saw in the website when placing the order.

string

The name or ID of the company that will be in charge of transporting and delivering this order.

string

Type of customs clearance in the destination country: POSTAL or COURIER.

string

The tracking number of the last mile carrier.

number

The price of this shipping, in the local currency, without discounts.

number

The price of this shipping, in the local currency, with all discounts applied.

integer

The number of business days from order pick-up / receival in the consolidation hub until final delivery.

string

The estimated delivery date and time.

array

Array containing the order item IDs that are in this delivery.

array

The information about all the parcels (packages) within this delivery.

Show parcel fields

array

Array containing a list of items that are in this parcel.

Show parcel item fields

string

The SKU ID which are in this parcel.

integer

How many pieces of the SKU are in this parcel.

number

The total parcel height.

number

The total parcel length.

number

The total parcel width.

number

The total parcel weight (items + packaging).

number

Parcel’s packaging weight.

number

Parcel’s net weight (items only).

string

The name of this parcel size.

string

The code of this parcel size.

string

The e-CROSS parcel identifier. This field becomes available once the order reaches READY_TO_SHIP.

array

The documents that are in this parcel. If there’s no document, this field won’t be returned.

Show document fields

string

Document name.

string

URL to the document.

array

The current parcel tracking events available directly on the order. Use this field as the primary source to monitor tracking for a known order. Events are sorted by eventDate. If no tracking updates were received yet, this field won’t be returned.

Show parcel event fields

string

Unique identifier of the tracking event.

string

Date and time when the event happened, in ISO 8601 format.

string

Normalized e-CROSS tracking code for the event.

string

Macro step of the logistics route associated with the event.

string

Identifier of the carrier or fulfillment partner that sent the event.

string

Tracking code used by the external carrier or fulfillment system.

string

Human-readable description of the event, when available.

string

Location associated with the event, when available.

array

Array of payments made for the order.

Show payment fields

string

Type of payment: CREDIT_CARD, DEBIT_CARD, PIX, BILL, GIFT_CARD or OTHER.

number

Total amount paid using this payment method.

number

Number of installments if the payment was made using installments. (only available for credit card payments)

string

ID of the gift card if the payment was made using a gift card. (only available for gift card payments)

Overview

Authentication APIs

Sales Channel APIs

Merchant Catalog APIs

Order APIs

Shipment APIs

Parcel APIs

Sandbox APIs

Query Parameters

Response Fields

Order object fields

​Query Parameters

​Response Fields

​Order object fields

Query Parameters

Response Fields

Order object fields