Update an order

Setting status to most values requires _policies.allow_status: true in the request body.

Recommended pattern for retry-safe order creation

POST /v2/orders has no idempotency mechanism (see its description). The recommended way to create an order safely under retry is PUT /v2/orders/{id} with _upsert: true and an external_id in the body:

If no order exists yet with that external_id (scoped to the seller resolved via shop_id), one is created (response status 201) using the same request body fields as POST /v2/orders (shop_id, contact, line_items, etc). The order gets a normal system-generated code — the URL :id is not used as, or turned into, the order’s code; a client cannot pick the public order code this way. :id can be any placeholder (e.g. the same external_id value, for readability), since matching is done by external_id, not by the URL.
If an order already exists with that external_id, it’s updated in place (response status 200) — a retried request converges on the same order instead of creating a duplicate.
Without _upsert: true, PUT to a nonexistent :id returns 404 as usual.
_upsert: true without an external_id in the body returns 422 — the flag requires external_id so a typo in the URL :id alone can’t silently create an unintended order.

This is the same external_id field documented on Order and on POST /v2/orders — a collision there is rejected with 422; here, under _upsert, a “collision” is the intended match and updates the existing order instead.

Stock restoration on cancellation

Setting status to cancelled automatically restores/releases reserved stock, but only when both of these hold:

the order’s fulfillment_status is still unsent (queued, preparing, or ready — not yet shipped/delivered), and
stock was actually reserved for the order in the first place (line items on non-stock-tracked products, or without a variant_id at all, never reserved anything, so there’s nothing to restore for them).

Cancelling an order that has already shipped does not auto-restore stock. Restoration is independent of payment state — it isn’t affected by whether the order was paid or refunded.

PUT/orders/{id}

Authorization

AuthorizationBearer token (JWT) · headerrequired

Path parameters

idstringrequired

Order ID or permalink

Request body

requiredapplication/json

_upsertboolean

If true, requires external_id in this same request body. Finds an order by external_id (scoped to the seller); if none exists, creates one instead of returning 404 (with a system-generated code, not the URL :id). See "Recommended pattern for retry-safe order creation" above.

default: false

statusstring

Allowed:draftcheckoutin_reviewpendingcancelledclosedcompleted

fulfillment_statusstring

Allowed:nonequeuedpreparingreadyshippeddeliveredreturned

archivedboolean

external_idstring

Optional client-supplied reference, unique per seller. Can be set here if it wasn't given at create time; a colliding value is rejected with a 422.

tracking_codestring

courier_namestring

fulfillment_methodstring

Allowed:shippingmailbox_pickuplocal_pickupnone

shipping_amountinteger

shipping_discountinteger

shipping_descriptionstring

tagsstring[]

notify_status_changeboolean

default: false

notification_messagestring

_policiesobject

Show properties

allow_statusboolean

Required to change status to most values

append_tagsboolean

Responses

200

Order updated

_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

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

idpath*Order ID or permalink

Bodyapplication/json

Request body

Request

curl -s -X PUT \
  -H "Authorization: Bearer $BOLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tracking_code":"1Z9999W99999999999","courier_name":"UPS"}' \
  "https://api.onbolder.com/v2/orders/ORD-5001"

curl -X PUT 'https://api.onbolder.com/v2/orders/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "tracking_code": "1Z9999W99999999999",
  "courier_name": "UPS",
  "fulfillment_status": "shipped"
}'

const response = await fetch("https://api.onbolder.com/v2/orders/string", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"tracking_code\": \"1Z9999W99999999999\",\n  \"courier_name\": \"UPS\",\n  \"fulfillment_status\": \"shipped\"\n}"
});

import requests

response = requests.put(
    "https://api.onbolder.com/v2/orders/string",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"tracking_code\": \"1Z9999W99999999999\",\n  \"courier_name\": \"UPS\",\n  \"fulfillment_status\": \"shipped\"\n}",
)

Response

{
  "id": 5001,
  "code": "ORD-5001",
  "status": "pending",
  "fulfillment_status": "shipped",
  "tracking_code": "1Z9999W99999999999",
  "courier_name": "UPS",
  "_links": {
    "self": {
      "href": "https://api.onbolder.com/v2/orders/ORD-5001"
    }
  }
}