Create an order

Creates an order. There is no Idempotency-Key-header-style replay mechanism — a retried request always executes again server-side, it never returns a cached copy of the original response. If a create request times out or the response is otherwise lost, pass an external_id and check GET /v2/orders?external_id={value} before retrying: the first successful create claims that external_id, and a second create attempt with the same value is rejected with a 422 instead of producing a duplicate order. (The id/code field does not give you this protection via POST — see below.)

Alternatively, PUT /v2/orders/{id} with _upsert: true and an external_id in the body finds-or-creates by external_id directly — it creates the order (with a system-generated code, not the URL :id) if no order with that external_id exists yet, or updates it in place if one does, so a retried request converges instead of duplicating. See that operation’s description for details.

POST/orders

Authorization

AuthorizationBearer token (JWT) · headerrequired

Request body

requiredapplication/json

shop_idintegerrequired

Required — ID of the shop this order belongs to

idstring

Optional client-supplied order code (returned/queryable as code). Not a reliable idempotency key: if the code collides with an existing order, the collision is resolved silently by generating a new random code instead of rejecting the request — a retried create with the same id does not return the original order, it creates a new one with a different code. Use external_id instead if you need safe dedup.

external_idstring

Optional client-supplied reference, unique per seller. A colliding value is rejected with a 422 (unlike id), so this is the field to use for retry-safe order creation: check GET /v2/orders?external_id={value} before retrying a create that may have already succeeded.

sourcestring

default: "api"

contactobject

Show properties

idstring

Existing contact ID, if known

namestring

emailstring

phone_numberstring

addressAddress

Show properties

streetstring

street_2string

locality_namestring

region_namestring

country_namestring

postal_codestring

line_itemsobject[]

Show properties

Array of object

variant_idstring

unitsinteger

default: 1

priceinteger

Overrides the product's price, in cents

variant_skustring

Alternative to variant_id

tagsstring[]

courier_namestring

tracking_codestring

fulfillment_methodstring

Allowed:shippingmailbox_pickuplocal_pickupnone

_policiesobject

Flags controlling order processing behavior

Show properties

allow_no_stockboolean

allow_statusboolean

force_item_pricesboolean

allow_promotionsboolean

default: true

Responses

201

Order created

403

Access denied to the given shop

422

Validation error

_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

Bodyapplication/json

Request body

Request

curl -s -X POST \
  -H "Authorization: Bearer $BOLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"shop_id":1,"contact":{"name":"Jane Doe","email":"customer@example.com"},"line_items":[{"variant_id":101,"units":2}]}' \
  "https://api.onbolder.com/v2/orders"

curl -X POST 'https://api.onbolder.com/v2/orders' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "shop_id": 1,
  "contact": {
    "name": "Jane Doe",
    "email": "customer@example.com"
  },
  "line_items": [
    {
      "variant_id": "101",
      "units": 2
    },
    {
      "variant_id": "205",
      "units": 1
    }
  ]
}'

const response = await fetch("https://api.onbolder.com/v2/orders", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"shop_id\": 1,\n  \"contact\": {\n    \"name\": \"Jane Doe\",\n    \"email\": \"customer@example.com\"\n  },\n  \"line_items\": [\n    {\n      \"variant_id\": \"101\",\n      \"units\": 2\n    },\n    {\n      \"variant_id\": \"205\",\n      \"units\": 1\n    }\n  ]\n}"
});

import requests

response = requests.post(
    "https://api.onbolder.com/v2/orders",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"shop_id\": 1,\n  \"contact\": {\n    \"name\": \"Jane Doe\",\n    \"email\": \"customer@example.com\"\n  },\n  \"line_items\": [\n    {\n      \"variant_id\": \"101\",\n      \"units\": 2\n    },\n    {\n      \"variant_id\": \"205\",\n      \"units\": 1\n    }\n  ]\n}",
)

Response

Order created

{
  "id": 5002,
  "shop_id": 1,
  "code": "ORD-5002",
  "status": "checkout",
  "currency_code": "USD",
  "total": 17997,
  "created_on": "2024-06-20T14:30:00Z",
  "_links": {
    "self": {
      "href": "https://api.onbolder.com/v2/orders/ORD-5002"
    },
    "orders:update": {
      "href": "https://api.onbolder.com/v2/orders/ORD-5002",
      "method": "put"
    }
  }
}