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
/ordersAuthorization
AuthorizationBearer token (JWT) · headerrequiredQuery parameters
shop_idintegerID of the shop whose orders to list. Optional if the token covers exactly one shop, or if `seller_id` is given instead.
seller_idintegerID 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.
statusstringFilter 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_reviewpendingcancelledclosedcompletedallsuccessfulabandonedarchivedbooleanFilter archived orders.
fulfillment_statusstringAllowed:
nonequeuedpreparingreadyshippeddeliveredreturnedcontact_idintegerproduct_idintegervariant_idintegerpageintegermin 1 · default: 1
per_pageintegermin 1 · max 200 · default: 20
contact_emailstringFilter orders by customer email address.
codestringFilter by exact order code (e.g. `ORD-00042`).
external_idstringFilter 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.
sortstringSort order for results.
default: "created_on_desc"
Allowed:
created_on_asccreated_on_descupdated_on_ascupdated_on_desctotal_asctotal_descResponses
200Paginated list of orders
total_itemsintegerper_pageintegerpageinteger_linksHalLinks_classstring[]_embeddedobjectShow propertiesHide properties
ordersOrder[]Show propertiesHide properties
Array of
Order_linksHalLinksidintegershop_idintegercodestringOrder code, used as the path identifier (e.g. `/v2/orders/{code}`)
external_idstring | nullOptional 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.
statusstringAllowed:
draftcheckoutin_reviewpendingcancelledclosedcompletedfulfillment_statusstringAllowed:
nonequeuedpreparingreadyshippeddeliveredreturnedcheckout_urlstringPresent only when the order is in `checkout` or `pending` status
archivedbooleancurrency_codestringprices_include_taxbooleanitems_net_totalintegerLine items subtotal in cents, before discounts
items_discount_totalintegeritems_totalintegerLine items subtotal in cents, after discounts
net_totalintegerOrder total in cents before tax
discount_totalintegercart_totalintegersurcharge_totalintegershipping_totalintegershipping_discountintegershipping_minus_discountintegertax_ratenumberPresent only when `prices_include_tax` is false
tax_totalintegerPresent only when `prices_include_tax` is false
totalintegerGrand total in cents, including shipping, discounts and tax
total_paidintegertotal_refundedintegermax_refundable_amountintegerpartial_payment_offeredbooleanWhether 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_partiallybooleanWhether the buyer opted into a partial payment for this order.
partial_payment_percentageintegerPercentage of the total charged upfront. Only present when `paying_partially` is true.
partial_payment_amountnumberAmount 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_descriptionstringtracking_codestringcourier_namestringpayment_infoobjectPresent only when the order has an associated payment method.
Show propertiesHide properties
idintegernamestringtypestringPayment method type/gateway identifier (e.g. `webpay_rest`, `mercado_pago`).
dataobjectGateway-specific transaction data, shape varies by `type`.
requested_document_typestringTax 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> | nullpending_onstring<date-time> | nullclosed_onstring<date-time> | nullshipped_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 propertiesHide properties
contactobjectShow propertiesHide properties
idintegernamestringemailstringphone_numberstringcompanyobjectShow propertiesHide properties
idintegernamestringid_numberstringFormatted tax/ID number (RUT, DNI, etc.)
activity_codestringaddressAddressShow propertiesHide properties
streetstringstreet_2stringlocality_namestringregion_namestringcountry_namestringpostal_codestringaddressAddressShow propertiesHide properties
streetstringstreet_2stringlocality_namestringregion_namestringcountry_namestringpostal_codestringbilling_addressAddressShow propertiesHide properties
streetstringstreet_2stringlocality_namestringregion_namestringcountry_namestringpostal_codestringline_itemsobject[]Show propertiesHide properties
Array of
objectidintegerproduct_idintegerproduct_namestringvariant_idintegervariant_namestringvariant_skustringunitsintegerunit_priceintegerUnit price in cents
net_totalintegerLine total in cents before discounts
totalintegerLine total in cents after discounts/surcharges
paymentsOrderTransaction[]Show propertiesHide properties
Array of
OrderTransactionidintegerorder_idintegeramountintegerAmount in cents (negative for refunds)
absolute_amountintegerAbsolute value of `amount` in cents
successfulbooleancard_token_idintegerpayment_method_typestringtransaction_idstringGateway transaction ID
authorization_codestringdescriptionstringcreated_atstring<date-time>refundsOrderTransaction[]Show propertiesHide properties
Array of
OrderTransactionidintegerorder_idintegeramountintegerAmount in cents (negative for refunds)
absolute_amountintegerAbsolute value of `amount` in cents
successfulbooleancard_token_idintegerpayment_method_typestringtransaction_idstringGateway transaction ID
authorization_codestringdescriptionstringcreated_atstring<date-time>documentsOrderDocument[]Show propertiesHide properties
Array of
OrderDocumentidintegerdocument_typestringAllowed:
invoicereceiptdocument_numberstringfile_urlstring403Access 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.
Request
curl -X GET "https://api.onbolder.com/v2/orders" \
-H "Authorization: Bearer YOUR_TOKEN"const response = await fetch("https://api.onbolder.com/v2/orders", {
method: "GET",
headers: {
"Authorization": "Bearer YOUR_TOKEN"
}
});import requests
response = requests.get(
"https://api.onbolder.com/v2/orders",
headers={
"Authorization": "Bearer YOUR_TOKEN"
},
)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"
}
}
}
]
}
}Access denied to the given shop or seller
`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.