List orders

Returns orders for a shop, or for a whole seller across all of its shops.

shop_id and seller_id are both optional. If the token covers exactly one shop, that shop is auto-resolved and results are scoped to it. If the token covers multiple shops belonging to a single seller, omitting both params returns orders across all of that seller’s shops. A token covering multiple sellers (or a god token) must pass shop_id or seller_id explicitly — there is no “all sellers” search.

GET/orders

Authorization

AuthorizationBearer token (JWT) · headerrequired

Query parameters

shop_idinteger

ID of the shop whose orders to list. Optional if the token covers exactly one shop, or if seller_id is given instead.

seller_idinteger

ID of the seller whose orders to list, across all of its shops. Only needed when shop_id is omitted and the token covers more than one shop or seller.

statusstring

Filter by order status. Also accepts comma-separated values and not_<status> negations (e.g. not_cancelled), plus fulfillment statuses (queued, preparing, ready, shipped, delivered, returned, unsent).

default: "all"

Allowed:draftcheckoutin_reviewpendingcancelledclosedcompletedallsuccessfulabandoned

archivedboolean

Filter archived orders.

fulfillment_statusstring

Allowed:nonequeuedpreparingreadyshippeddeliveredreturned

contact_idinteger

product_idinteger

variant_idinteger

pageinteger

min 1 · default: 1

per_pageinteger

min 1 · max 200 · default: 20

contact_emailstring

Filter orders by customer email address.

codestring

Filter by exact order code (e.g. ORD-00042).

external_idstring

Filter by exact client-supplied external_id. Useful for checking whether a previous create already succeeded before retrying it.

created_on_gtestring<date-time>

Orders placed on or after this ISO 8601 timestamp.

created_on_ltestring<date-time>

Orders placed on or before this ISO 8601 timestamp.

updated_on_gtestring<date-time>

Orders last updated on or after this ISO 8601 timestamp.

sortstring

Sort order for results.

default: "created_on_desc"

Allowed:created_on_asccreated_on_descupdated_on_ascupdated_on_desctotal_asctotal_desc

Responses

200

Paginated list of orders

total_itemsinteger

per_pageinteger

pageinteger

_linksHalLinks

_classstring[]

_embeddedobject

Show properties

ordersOrder[]

Show properties

Array of Order

_linksHalLinks

idinteger

shop_idinteger

codestring

Order code, used as the path identifier (e.g. /v2/orders/{code})

external_idstring | null

Optional client-supplied reference, unique per seller. Set it at create time (or via update) to look the order back up later with GET /v2/orders?external_id={value} — unlike id/code, a colliding external_id is rejected with a 422 instead of being silently reassigned, so it's safe to use for dedup checks before retrying a create.

statusstring

Allowed:draftcheckoutin_reviewpendingcancelledclosedcompleted

fulfillment_statusstring

Allowed:nonequeuedpreparingreadyshippeddeliveredreturned

checkout_urlstring

Present only when the order is in checkout or pending status

archivedboolean

currency_codestring

prices_include_taxboolean

items_net_totalinteger

Line items subtotal in cents, before discounts

items_discount_totalinteger

items_totalinteger

Line items subtotal in cents, after discounts

net_totalinteger

Order total in cents before tax

discount_totalinteger

cart_totalinteger

surcharge_totalinteger

shipping_totalinteger

shipping_discountinteger

shipping_minus_discountinteger

tax_ratenumber

Present only when prices_include_tax is false

tax_totalinteger

Present only when prices_include_tax is false

totalinteger

Grand total in cents, including shipping, discounts and tax

total_paidinteger

total_refundedinteger

max_refundable_amountinteger

partial_payment_offeredboolean

Whether this order is eligible for buyer-chosen partial payment: either the shop has it enabled for everyone, or this specific order was offered it via the API (partial_payment_offered: true on create/update). Either way, the order must not require review and any configured cart requirements must be met. Normally also requires a token-based payment method to exist, so the balance can be auto-charged later - unless the shop allows manual (non-token) payment methods for this, in which case the balance is instead collected via a reminder email. Only present when fetching a single order, not in list results.

paying_partiallyboolean

Whether the buyer opted into a partial payment for this order.

partial_payment_percentageinteger

Percentage of the total charged upfront. Only present when paying_partially is true.

partial_payment_amountnumber

Amount charged upfront, in cents. Only present when fetching a single order, and only when partial payment is offered or active.

partial_payment_due_onstring<date>

Date the remaining balance is due. Only present when paying_partially is true.

shipping_descriptionstring

tracking_codestring

courier_namestring

payment_infoobject

Present only when the order has an associated payment method.

Show properties

idinteger

namestring

typestring

Payment method type/gateway identifier (e.g. webpay_rest, mercado_pago).

dataobject

Gateway-specific transaction data, shape varies by type.

requested_document_typestring

Tax document type requested by the buyer at checkout (e.g. invoice, receipt), if any. Derived from custom order data, not a plain column.

tagsstring[]

tag_idsinteger[]

allowed_statusesstring[]

allowed_fulfillment_statusesstring[]

created_onstring<date-time>

updated_onstring<date-time>

checkout_onstring<date-time> | null

pending_onstring<date-time> | null

closed_onstring<date-time> | null

shipped_onstring<date-time> | null

_embeddedobject

contact is present when the order has a customer attached. company is present when a company/tax entity is attached (e.g. via company_name on create/update). address/billing_address are present when set. line_items is always present. payments/refunds/documents are present only when non-empty.

Show properties

contactobject

Show properties

idinteger

namestring

emailstring

phone_numberstring

companyobject

Show properties

idinteger

namestring

id_numberstring

Formatted tax/ID number (RUT, DNI, etc.)

activity_codestring

addressAddress

Show properties

streetstring

street_2string

locality_namestring

region_namestring

country_namestring

postal_codestring

addressAddress

Show properties

streetstring

street_2string

locality_namestring

region_namestring

country_namestring

postal_codestring

billing_addressAddress

Show properties

streetstring

street_2string

locality_namestring

region_namestring

country_namestring

postal_codestring

line_itemsobject[]

Show properties

Array of object

idinteger

product_idinteger

product_namestring

variant_idinteger

variant_namestring

variant_skustring

unitsinteger

unit_priceinteger

Unit price in cents

net_totalinteger

Line total in cents before discounts

totalinteger

Line total in cents after discounts/surcharges

paymentsOrderTransaction[]

Show properties

Array of OrderTransaction

idinteger

order_idinteger

amountinteger

Amount in cents (negative for refunds)

absolute_amountinteger

Absolute value of amount in cents

successfulboolean

card_token_idinteger

payment_method_typestring

transaction_idstring

Gateway transaction ID

authorization_codestring

descriptionstring

created_atstring<date-time>

refundsOrderTransaction[]

Show properties

Array of OrderTransaction

idinteger

order_idinteger

amountinteger

Amount in cents (negative for refunds)

absolute_amountinteger

Absolute value of amount in cents

successfulboolean

card_token_idinteger

payment_method_typestring

transaction_idstring

Gateway transaction ID

authorization_codestring

descriptionstring

created_atstring<date-time>

documentsOrderDocument[]

Show properties

Array of OrderDocument

idinteger | null

null for legacy documents stored in the order's contact_data (_document_pdf_url/_document_type/_document_number) instead of as a real document record. These have no self/delete links and can't be fetched or deleted via /orders/{order_id}/documents/{id}.

document_typestring

Allowed:invoicereceipt

document_numberstring

file_urlstring

403

Access denied to the given shop or seller

422

shop_id or seller_id required — the token covers more than one shop and more than one seller (or is a god token), so neither can be auto-resolved.

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (JWT)Remember on this deviceInclude my values in samples

Parameters

shop_idqueryID of the shop whose orders to list. Optional if the token covers exactly one shop, or if `seller_id` is given instead. seller_idqueryID of the seller whose orders to list, across all of its shops. Only needed when `shop_id` is omitted and the token covers more than one shop or seller. statusqueryFilter by order status. Also accepts comma-separated values and `not_<status>` negations (e.g. `not_cancelled`), plus fulfillment statuses (`queued`, `preparing`, `ready`, `shipped`, `delivered`, `returned`, `unsent`). archivedqueryFilter archived orders.fulfillment_statusquerycontact_idqueryproduct_idqueryvariant_idquerypagequeryper_pagequerycontact_emailqueryFilter orders by customer email address.codequeryFilter by exact order code (e.g. `ORD-00042`).external_idqueryFilter by exact client-supplied `external_id`. Useful for checking whether a previous create already succeeded before retrying it. created_on_gtequeryOrders placed on or after this ISO 8601 timestamp.created_on_ltequeryOrders placed on or before this ISO 8601 timestamp.updated_on_gtequeryOrders last updated on or after this ISO 8601 timestamp.sortquerySort order for results.

Request

# List all orders for a shop
curl -s -H "Authorization: Bearer $BOLDER_TOKEN" \
  "https://api.onbolder.com/v2/orders?shop_id=1"

# List orders across all of a seller's shops
curl -s -H "Authorization: Bearer $BOLDER_TOKEN" \
  "https://api.onbolder.com/v2/orders?seller_id=1"

# Filter by status
curl -s -H "Authorization: Bearer $BOLDER_TOKEN" \
  "https://api.onbolder.com/v2/orders?shop_id=1&status=open"

curl -X GET 'https://api.onbolder.com/v2/orders' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

const response = await fetch("https://api.onbolder.com/v2/orders", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json"
  }
});

import requests

response = requests.get(
    "https://api.onbolder.com/v2/orders",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json"
    },
)

Response

{
  "_class": [
    "results",
    "orders"
  ],
  "total_items": 1,
  "per_page": 20,
  "page": 1,
  "_links": {
    "self": {
      "href": "https://api.onbolder.com/v2/orders?shop_id=1"
    },
    "shops:show": {
      "href": "https://api.onbolder.com/v2/shops/1"
    }
  },
  "_embedded": {
    "orders": [
      {
        "id": 5001,
        "shop_id": 1,
        "code": "ORD-5001",
        "status": "pending",
        "fulfillment_status": "none",
        "currency_code": "USD",
        "total": 8499,
        "total_paid": 8499,
        "created_on": "2024-06-15T09:45:00Z",
        "_embedded": {
          "contact": {
            "id": 42,
            "name": "Jane Doe",
            "email": "customer@example.com",
            "phone_number": "+15551234567"
          }
        },
        "_links": {
          "self": {
            "href": "https://api.onbolder.com/v2/orders/ORD-5001"
          },
          "orders:update": {
            "href": "https://api.onbolder.com/v2/orders/ORD-5001",
            "method": "put"
          }
        }
      }
    ]
  }
}