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",
      "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",
          "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",
                "length": 15,
                "width": 10,
                "height": 8,
                "weight": 0.04,
                "netWeight": 0.16,
                "grossWeight": 0.2,
                "items": [
                  {
                    "salesChannelSkuId": "1",
                    "quantity": 1
                  }
                ]
              }
            ]
          }
        ]
      },
      "payments": [
        {
          "type": "BILL",
          "value": 234
        }
      ]
    }
  ],
  "nextPageToken": "eyJjcmVhdGlvbkRhdGUiOiIyMDIzLTA5LTE2VDIyOjI1OjM5LjkzNloiLCJvcmRlcklkIjoiTVZQLVRFU1QtRUNPTS0wMDEiLCJ0eXBlIjoib3JkZXIifQ=="
}

Query Parameters

status

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.

creationDateFrom

string

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

creationDateUntil

string

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

lastUpdateDateFrom

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.

lastUpdateDateUntil

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.

nextPageToken

string

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

Response Fields

orders

array

Array containing Orders that match the specified filters.

nextPageToken

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

orderId

string

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

merchantId

string

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

salesChannelOrderId

string

The order identifier in the sales channel.

salesChannel

string

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

status

string

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

value

number

The total value of the order.

taxType

string

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

currency

string

The currency used by the buyer to place the order.

foreignCurrency

string

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

customerDocument

string

The document of the customer who placed the order.

creationDate

string

The date when the order was created.

approvalDate

string

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

cancelDate

string

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

startHandlingDate

string

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

onHoldDate

string

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

packedDate

string

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

invoicedDate

string

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

shipmentDate

string

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

deliveredDate

string

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

lastUpdateDate

string

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

totals

object

Order amounts summary in the buyer’s local currency.

Show totals fields

orderValue

number

Total order value.

itemsGross

number

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

itemsDiscount

number

Total items discount amount.

shippingGross

number

Total shipping gross amount.

shippingDiscount

number

Shipping discounts total amount.

taxes

number

Total of taxes (import duty and sales taxes).

fees

number

Fees that will be discounted from the order.

grossInboundValue

number

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

netInboundValue

number

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

totalsForeignCurrency

object

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

items

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.

skuId

string

SKU ID within the e-CROSS platform.

salesChannelSkuId

string

SKU ID of this item in the sales channel.

ean

string

SKU EAN-13 code.

quantity

integer

How many pieces of this SKU are being bought.

name

string

The name of the SKU.

listPrice

number

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

salePrice

number

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

foreignListPrice

number

Unit price converted to foreign currency.

foreignSalePrice

number

Unit price with discounts, converted to foreign currency.

invoicedPrice

number

Unit price of the item in the commercial invoice.

imageUrl

string

URL to the SKU image.

weight

number

Product weight in kilograms (kg).

hsCode

string

SKU Harmonized System (HS) code.

shippingDocuments

object

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

Show shippingDocuments fields

name

string

Document name

url

string

Document URL

customer

object

Information about the customer who placed the order.

Show customer fields

type

string

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

firstName

string

Customer first name.

lastName

string

Customer last name.

document

string

Customer identification document.

string

Customer’s email address.

phone

object

Customer contact phone number.

billingAddress

object

Customer billing address.

Show billingAddress fields

addressName

string

Name of the address.

receiverName

string

Name of the person who will receive the order.

street

string

Street name.

number

string

Building number.

complement

string

Any relevant address complement.

neighborhood

string

Neighborhood name.

city

string

City name.

state

string

State or province name.

country

string

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

postalCode

string

Postal code.

reference

string

Any relevant reference text.

shipping

object

Shipping information including delivery address and deliveries (packages).

Show Shipping Fields

outboundCountry

string

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

deliveryAddress

object

The buyer’s delivery address in the destination country.

Show deliveryAddress fields

addressName

string

Name of the address.

receiverName

string

Name of the person who will receive the order.

street

string

Street name.

number

string

Building number.

complement

string

Any relevant address complement.

neighborhood

string

Neighborhood name.

city

string

City name.

state

string

State or province name.

country

string

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

postalCode

string

Postal code.

reference

string

Any relevant reference text.

freightForwarderAddress

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

address

string

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

city

string

The city name.

state

string

The state or province name.

postalCode

string

The address postal code.

country

string

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

deliveries

array

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

Show delivery fields

name

string

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

company

string

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

clearance

string

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

lastMileTrackingNumber

string

The tracking number of the last mile carrier.

listPrice

number

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

salePrice

number

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

deliveryTime

integer

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

deliveryEstimateDate

string

The estimated delivery date and time.

items

array

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

parcels

array

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

Show parcel fields

items

array

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

Show parcel item fields

salesChannelSkuId

string

The SKU ID which are in this parcel.

quantity

integer

How many pieces of the SKU are in this parcel.

height

number

The total parcel height.

length

number

The total parcel length.

width

number

The total parcel width.

grossWeight

number

The total parcel weight (items + packaging).

weight

number

Parcel’s packaging weight.

netWeight

number

Parcel’s net weight (items only).

name

string

The name of this parcel size.

code

string

The code of this parcel size.

documents

array

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

Show document fields

name

string

Document name.

url

string

URL to the document.

payments

array

Array of payments made for the order.

Show payment fields

type

string

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

value

number

Total amount paid using this payment method.

installments

number

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

giftCardId

string

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

Overview

Authentication APIs

Merchant Catalog APIs

Order APIs

Shipment APIs

Parcel APIs

Sandbox APIs

Query Parameters

Response Fields

Order object fields

Overview

Authentication 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