Orders Core

Overview

The Orders Core API provides fundamental operations for managing orders in SellerCenter. Orders represent customer purchases and contain order items, customer information, shipping details, and payment information.

Core order operations include:

Order listing: Retrieve collections of orders with extensive filtering options
Order anonymization: Anonymize customer information in orders for GDPR/LGPD compliance
Order retrieval: Get detailed information about specific orders
Order search: Search orders and get autocomplete suggestions
Order counters: Get approximate counts of orders by status

Important: Orders can be filtered by many criteria including status, dates, customer information, shipment details, and more. The counters endpoint provides eventually consistent data suitable for UI hints and dashboards.

Get List of Orders

GET /v2/orders

Summary: Get list of orders with filters

Description: Retrieve a paginated collection of orders with extensive filtering capabilities. This endpoint supports filtering by status, dates, order numbers, customers, shipment types, payment methods, and many other criteria.

Parameters:

X-Context (header, optional): Context header (admin or seller)
limit (query, required): Maximum number of items to return
offset (query, required): Number of items to skip
section (query, optional): Search section (e.g., status_shipped, status_delivered, status_pending, group_economy, etc.)
packed (query, optional): Search by packed status (fully_packed, partially_packed, not_packed)
customers[] (query, optional): Search by customer name (first name and last name)
printedStatus (query, optional): Search by printed status
tags[] (query, optional): Search by tag's numeric id
productSku[] (query, optional): Search by product sku
delivery (query, optional): Search by delivery (shippedUnder24h, notShippedUnder24h, notShippedUnder24BusinessHours)
shipmentType (query, optional, deprecated): Search by shipment type (warehouse, dropshipping, crossdocking). Use shipmentTypes[] instead.
shipmentTypes[] (query, optional): Search by shipment types (array; warehouse, dropshipping, crossdocking)
shipmentProviders[] (query, optional): Search by shipment provider id
paymentMethods[] (query, optional): Search by payment methods
outlet (query, optional): Search orders from outlet only
invoiceRequired (query, optional): If set to "1", only orders requiring invoice will be returned
cancelationReasons[] (query, optional, deprecated): Search by cancelation reason id
cancelationReasonIds[] (query, optional): Search by cancelation reason id
fulfilmentType[] (query, optional): Search by fulfilment type (merchant, venture)
orderSources[] (query, optional): Search by order sources
sellerNames[] (query, optional): Search by seller names
sellerIds[] (query, optional): Search by seller IDs
updateDateStart (query, optional): Filter orders updated after this date
updateDateEnd (query, optional): Filter orders updated before this date
warehouses[] (query, optional): Search by warehouse IDs
includeVoucherDetails (query, optional): Include voucher details in response
includeProductSet (query, optional): Include product set information
dateStart (query, optional): Search by order creation date or date time
dateEnd (query, optional): Search by order creation date or date time
orderNumbers[] (query, optional): Filter by order numbers (array)
orderIds[] (query, optional): Search by order IDs
sort (query, optional): Sort field (createdAt or updatedAt)
sortDir (query, optional): Sort direction (asc or desc)

Note:

Supports extensive filtering by status, dates, customers, shipment types, payment methods, and many other criteria
Returns paginated results with limit, offset, total, and hasNext fields
Use X-Context header to specify admin or seller context
Multiple filters can be combined for precise order retrieval

Authorization

BearerAuth

AuthorizationBearer <token>

OAuth 2.0 Bearer token authentication

In: header

Query Parameters

limit*integer

The maximum number of items to return

offset*integer

The number of items to skip before starting to return results

dateStart?|

Search by order creation or date time. Time information is optional. By default start time will be at 00:00:00.

dateEnd?|

Search by order creation date or date time. Time information is optional. By default end time will be at 23:59:59.

orderNumbers[]?array<string>

Filter by order numbers

orderIds[]?array<integer>

Search by order IDs

section?string

Search section

status_shipped - returns orders with order items status shipped - status_delivered - returns orders with order items status delivered - status_failed - returns orders with order items status failed - status_canceled - returns orders with order items status canceled - status_pending_all - returns orders with order items status pending and shipment_information_pending - status_pending - returns orders with order items status pending - status_ready_to_ship - returns orders with order items status ready_to_ship - status_payment_pending - returns orders with order items status payment_pending - status_shipment_information_pending - returns orders with order items status shipment_information_pending - status_returned - returns orders with order items status returned - status_return_shipped_by_customer - returns orders with order items status return_shipped_by_customer - status_return_rejected - returns orders with order items status return_rejected - status_return_waiting_for_approval - returns orders with order items status return_waiting_for_approval - status_return_delivered - returns orders with order items status return_delivered - group_economy - returns orders with pending status and economy shipment provider type - group_express - returns orders with pending status and express shipment provider type - group_standard - returns orders with pending status and standard shipment provider type - group_digital - returns orders with pending status and digital shipment provider type - group_sameday - returns orders with pending status and sameday shipment provider type - group_air - returns orders with pending status and air shipment provider type - group_surface - returns orders with pending status and surface shipment provider type - group_missing_external_invoice_access_key - returns orders with pending or canceled status and invoice key is empty - group_ready_to_ship_manifested - returns orders with ready to ship status and manifest is exists - group_ready_to_ship_nonmanifested - returns orders with ready to ship status and manifest is not exists

Value in

"status_shipped" | "status_delivered" | "status_failed" | "status_canceled" | "status_pending_all" | "status_pending" | "status_ready_to_ship" | "status_payment_pending" | "status_shipment_information_pending" | "status_returned" | "status_return_shipped_by_customer" | "status_return_rejected" | "status_return_waiting_for_approval" | "status_return_delivered" | "group_economy" | "group_express" | "group_standard" | "group_digital" | "group_sameday" | "group_air" | "group_surface" | "group_missing_external_invoice_access_key" | "group_kpi_rejection_rate" | "group_kpi_return_rate" | "group_ready_to_ship_manifested" | "group_ready_to_ship_nonmanifested"

packed?string

Search by packed status - fully_packed - all of order items packed - partially_packed - part of order items packed - not_packed - no order items packed

Value in"fully_packed" | "partially_packed" | "not_packed"

customers[]?array<string>

Search by customer name (first name and last name)

printedStatus?boolean

Search by printed status

tags[]?array<string>

Search by tag's numeric id

productSku[]?array<string>

Search by product sku

delivery?string

Search by delivery: - shippedUnder24h - Orders with the status of the Order Item was set to shipped less or equal than 24 hours ago - notShippedUnder24h - Orders with the status of the Order Item was set to shipped more than 24 hours ago - notShippedUnder24BusinessHours - Orders with the status of the Order Item was set to shipped more than 24 business hours ago

Value in"shippedUnder24h" | "notShippedUnder24h" | "notShippedUnder24BusinessHours"

shipmentType?stringDeprecated

Search by shipment type (single value). Deprecated in favor of shipmentTypes[].

Value in"warehouse" | "dropshipping" | "crossdocking"

shipmentTypes[]?array<>

Search by shipment types (multiple values allowed)

shipmentProviders[]?array<string>

Search by shipment provider id (or -1 for orders have no shipment provider)

paymentMethods[]?array<string>

Search by payment methods

outlet?boolean

Search orders from outlet only

invoiceRequired?boolean

If this field is set to "1" then only orders for which an invoice is required will be returned

cancelationReasons[]?array<string>Deprecated

Search by cancelation reason id (this field name is marked deprecated and will be replaced by cancelationReasonIds)

cancelationReasonIds[]?array<integer>

Search by cancelation reason id

fulfilmentType[]?array<>

Search by fulfilment type - merchant - means the type of shipment from the seller's warehouse - venture - means the type of shipment from the venture's warehouse

orderSources[]?array<string>

Search by order sources

sellerNames[]?array<string>

Search by seller names

sellerIds[]?array<integer>

Search by seller IDs

updateDateStart?string

Filter orders updated after this date

Formatdate-time

updateDateEnd?string

Filter orders updated before this date

Formatdate-time

warehouses[]?array<string>

Search by warehouse IDs

includeVoucherDetails?boolean

Include voucher details in response

includeProductSet?boolean

Include product set information

sort?string

Sort field

Value in"createdAt" | "updatedAt"

sortDir?string

Sort direction

Value in"asc" | "desc"

Header Parameters

X-Context?string

Define if the request is done by an admin or by a seller

Value in"admin" | "seller"

Response Body

`application/json`

{
  "items": [
    {
      "id": 1111,
      "number": "MY-111143",
      "status": "pending"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "hasNext": true
  }
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication credentials were not provided or are invalid"
}

{
  "title": "Access Denied",
  "status": 403,
  "detail": "You do not have permission to access this resource"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "The requested resource was not found"
}

{
  "title": "Service Unavailable",
  "status": 500,
  "detail": "The service is temporarily unavailable. Please try again later."
}

{
  "title": "Service Unavailable Due to Maintenance Mode",
  "status": 503,
  "detail": "The service is currently under maintenance. Please try again later."
}

Anonymize Order Information

POST /v2/orders/anonymize

Summary: Anonymize order information

Description: Anonymize customer information in one or more orders for GDPR/LGPD compliance. This endpoint supports two modes:

Default Mask Mode: When default_mask is provided, all customer data fields (names, addresses, etc.) will be replaced with the mask value.
Selective Update Mode: When specific fields are provided without default_mask, only those fields will be updated.

The operation processes orders in batch and returns detailed results for each order.

Request Body:

order_numbers (array, required): Array of order numbers to anonymize (minimum 1 item)
default_mask (string, optional): Default mask to apply to all fields if provided
address_billing (object, optional): Billing address fields to update
- first_name, last_name: Customer names for billing
- phone, phone2: Primary and secondary phone numbers
- address1 to address5: Address lines
- city, postcode, country: Location details
- customer_email: Email address for billing
address_shipping (object, optional): Shipping address fields to update (same structure as billing)
customer_first_name (string, optional): Customer's first name
customer_last_name (string, optional): Customer's last name
national_registration_number (string, optional): National registration number

Examples:

Default mask: Apply "LGPD-1212" to all customer data fields
Selective update: Update only specific fields like customer names and billing address
Batch processing: Process multiple orders in a single request

Response Codes:

200: All orders processed successfully
206: Partial success - some orders processed, others failed
400: Bad request - validation errors or all orders failed

Note:

Supports batch processing of multiple orders
Returns detailed success/failure information for each order
Useful for GDPR/LGPD compliance requirements
When using default_mask, all customer fields are replaced with the mask value

Authorization

BearerAuth

AuthorizationBearer <token>

OAuth 2.0 Bearer token authentication

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

{
  "message": "Order update completed",
  "successful_updates": [
    "ORDER123456",
    "ORDER789012"
  ],
  "failed_updates": [],
  "total_processed": 2,
  "successful_count": 2,
  "failed_count": 0
}

{
  "message": "Order update completed",
  "successful_updates": [
    "ORDER123456"
  ],
  "failed_updates": [
    {
      "order_number": "ORDER789012",
      "error": "Order not found"
    }
  ],
  "total_processed": 2,
  "successful_count": 1,
  "failed_count": 1
}

{
  "error": "Invalid input data or validation errors"
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication credentials were not provided or are invalid"
}

{
  "title": "Access Denied",
  "status": 403,
  "detail": "You do not have permission to access this resource"
}

{
  "error": "Internal server error"
}

Get Order by ID

GET /v2/orders/{orderId}

Summary: Get a specific order by ID

Description: Retrieve detailed information about a specific order by its numeric ID. Returns complete order information including order items, customer details, shipping information, and payment details.

Parameters:

orderId (path, required): Numeric ID of the order
shipmentType (query, optional): Filter by shipment type
includeProductSet (query, optional): Include product set information

Note:

Returns complete order details including all order items
Use includeProductSet to get additional product set information
Order status and history information is included in the response

Authorization

BearerAuth

AuthorizationBearer <token>

OAuth 2.0 Bearer token authentication

In: header

Path Parameters

orderId*integer

Numeric ID of the order

Query Parameters

shipmentType?string

Filter by shipment type

includeProductSet?boolean

Include product set information

Response Body

`application/json`

{
  "id": 1111,
  "uuid": "9d6ca7ce-4b71-46bf-aa5e-a0727eca880z",
  "number": "MY-111143",
  "status": "pending",
  "sellerId": 222
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication credentials were not provided or are invalid"
}

{
  "title": "Access Denied",
  "status": 403,
  "detail": "You do not have permission to access this resource"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "The requested resource was not found"
}

{
  "title": "Service Unavailable",
  "status": 500,
  "detail": "The service is temporarily unavailable. Please try again later."
}

{
  "title": "Service Unavailable Due to Maintenance Mode",
  "status": 503,
  "detail": "The service is currently under maintenance. Please try again later."
}

Search Orders

GET /v2/orders/search

Summary: Search orders for autocomplete suggestions

Description: Search orders and get autocomplete suggestions for order numbers, order sources, customers, and products. Useful for building search interfaces and autocomplete functionality.

Parameters:

key (query, required): Search key type (order_number, order_nr, order_source, customer, product, cancelation-reason)
query (query, required): Search query string
filteredStatus (query, optional): Filter by status (various status options available)

Note:

Returns autocomplete suggestions based on the search key type
Supports searching by order number, order source, customer, or product
Useful for building search interfaces with autocomplete

Authorization

BearerAuth

AuthorizationBearer <token>

OAuth 2.0 Bearer token authentication

In: header

Query Parameters

key*string

Search key type

query*string

Search query string

filteredStatus?string

Filter by status

Value in

"status_shipped" | "status_delivered" | "status_failed" | "status_canceled" | "status_pending_all" | "status_pending" | "status_ready_to_ship" | "status_payment_pending" | "status_shipment_information_pending" | "status_returned" | "status_return_shipped_by_customer" | "status_return_rejected" | "status_return_waiting_for_approval" | "status_return_delivered" | "group_economy" | "group_express" | "group_standard" | "group_digital" | "group_sameday" | "group_air" | "group_surface" | "group_missing_external_invoice_access_key" | "group_kpi_rejection_rate" | "group_kpi_return_rate" | "group_ready_to_ship_manifested" | "group_ready_to_ship_nonmanifested"

Response Body

`application/json`

{
  "results": [
    {
      "label": "Order #12345",
      "value": "12345",
      "sublabel": "Customer: John Doe | Status: Pending"
    },
    {
      "label": "Order #12346",
      "value": "12346",
      "sublabel": "Customer: Jane Smith | Status: Shipped"
    }
  ]
}

{
  "title": "Bad Request",
  "status": 400,
  "detail": "The request parameters are invalid"
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication credentials were not provided or are invalid"
}

{
  "title": "Access Denied",
  "status": 403,
  "detail": "You do not have permission to access this resource"
}

{
  "title": "Service Unavailable",
  "status": 500,
  "detail": "The service is temporarily unavailable. Please try again later."
}

{
  "title": "Service Unavailable Due to Maintenance Mode",
  "status": 503,
  "detail": "The service is currently under maintenance. Please try again later."
}

Get Order Counters

GET /v2/orders-counters

Summary: Get order counter values for each order state

Description: Get approximate counters for orders grouped by filters. This endpoint is suitable for getting quick information about count of orders, for example, when developing your own UI and want to display hints with count of pending orders. Data is eventually consistent, however there can be some delay in updating those counters.

Parameters:

includeOrderCounters (query, optional): When set to false, excludes order counters from response (default: true)
includeReturnCounters (query, optional): When set to true, includes return counters (default: false)

Note:

Returns counters for pending, ready_to_ship, shipped, delivered, cancelled orders
Data is eventually consistent - may have slight delays
Use includeReturnCounters to get return-related counters
Suitable for dashboard displays and UI hints

Authorization

BearerAuth

AuthorizationBearer <token>

OAuth 2.0 Bearer token authentication

In: header

Query Parameters

includeOrderCounters?boolean

When set to false, excludes order counters (pending, ready to ship, shipped, etc.) from the response to improve performance

includeReturnCounters?boolean

When set to true, includes return counters in the response

Response Body

`application/json`

{
  "pending": {
    "pending": 10,
    "notPrintedPendingCount": 5,
    "pendingExpressCount": 2,
    "pendingEconomyCount": 3,
    "pendingStandardCount": 4
  },
  "readyToShipCount": 15,
  "paymentPendingCount": 2,
  "notPrintedReadyToShipCount": 8,
  "shippedCount": 25,
  "return": {
    "returnedCount": 5,
    "returnShippedByCustomerCount": 2,
    "returnDeliveredCount": 1,
    "returnWaitingForApprovalCount": 3,
    "returnRejectedCount": 1
  }
}

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication credentials were not provided or are invalid"
}

{
  "title": "Service Unavailable",
  "status": 500,
  "detail": "The service is temporarily unavailable. Please try again later."
}

{
  "title": "Service Unavailable Due to Maintenance Mode",
  "status": 503,
  "detail": "The service is currently under maintenance. Please try again later."
}

Orders Core

200application/json

401application/json

403application/json

404application/json

500application/json

503application/json

200application/json

206application/json

400application/json

401application/json

403application/json

500application/json

Validation error

All orders failed

200application/json

401application/json

403application/json

404application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

500application/json

503application/json

On this page

200application/json

401application/json

403application/json

404application/json

500application/json

503application/json

200application/json

206application/json

400application/json

401application/json

403application/json

500application/json

Validation error

All orders failed

200application/json

401application/json

403application/json

404application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

500application/json

503application/json

200application/json

401application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`