Add a line item to an order

Adds a single item to the order. Accepts the same fields as one element of the line_items array on order create/update. If the variant is already in the order, units are updated instead (upsert by variant).

POST/orders/{order_id}/items

Authorization

AuthorizationBearer token (JWT) · headerrequired

Path parameters

order_idstringrequired

Request body

requiredapplication/json

variant_idstring

variant_skustring

Alternative to variant_id, for linked items

unitsinteger

default: 1

priceinteger

Overrides the product's price, in cents

product_namestring

Required for detached items (no product record)

Examples

{
  "variant_id": "123",
  "units": 2
}

{
  "product_name": "Custom Engraving",
  "variant_sku": "ENG-01",
  "price": 1500,
  "units": 1
}

Responses

200

Updated order (with the new line item)

_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

order_idpath*

Bodyapplication/json

variant_idstringvariant_skustringAlternative to variant_id, for linked itemsunitsintegerpriceintegerOverrides the product's price, in centsproduct_namestringRequired for detached items (no product record)

Request

curl -X POST 'https://api.onbolder.com/v2/orders/string/items' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "variant_id": "123",
  "units": 2
}'

const response = await fetch("https://api.onbolder.com/v2/orders/string/items", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"variant_id\": \"123\",\n  \"units\": 2\n}"
});

import requests

response = requests.post(
    "https://api.onbolder.com/v2/orders/string/items",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"variant_id\": \"123\",\n  \"units\": 2\n}",
)

Response

{
  "_links": {
    "property1": {
      "href": "string",
      "templated": true,
      "method": "get",
      "title": "string",
      "type": "string"
    },
    "property2": {
      "href": "string",
      "templated": true,
      "method": "get",
      "title": "string",
      "type": "string"
    }
  },
  "id": 0,
  "shop_id": 0,
  "code": "string",
  "external_id": "string",
  "status": "draft",
  "fulfillment_status": "none",
  "checkout_url": "string",
  "archived": true,
  "currency_code": "string",
  "prices_include_tax": true,
  "items_net_total": 0,
  "items_discount_total": 0,
  "items_total": 0,
  "net_total": 0,
  "discount_total": 0,
  "cart_total": 0,
  "surcharge_total": 0,
  "shipping_total": 0,
  "shipping_discount": 0,
  "shipping_minus_discount": 0,
  "tax_rate": 0,
  "tax_total": 0,
  "total": 0,
  "total_paid": 0,
  "total_refunded": 0,
  "max_refundable_amount": 0,
  "partial_payment_offered": true,
  "paying_partially": true,
  "partial_payment_percentage": 0,
  "partial_payment_amount": 0,
  "partial_payment_due_on": "2019-08-24",
  "shipping_description": "string",
  "tracking_code": "string",
  "courier_name": "string",
  "payment_info": {
    "id": 0,
    "name": "string",
    "type": "string",
    "data": {}
  },
  "requested_document_type": "string",
  "tags": [
    "string"
  ],
  "tag_ids": [
    0
  ],
  "allowed_statuses": [
    "string"
  ],
  "allowed_fulfillment_statuses": [
    "string"
  ],
  "created_on": "2019-08-24T14:15:22Z",
  "updated_on": "2019-08-24T14:15:22Z",
  "checkout_on": "2019-08-24T14:15:22Z",
  "pending_on": "2019-08-24T14:15:22Z",
  "closed_on": "2019-08-24T14:15:22Z",
  "shipped_on": "2019-08-24T14:15:22Z",
  "_embedded": {
    "contact": {
      "id": 0,
      "name": "string",
      "email": "string",
      "phone_number": "string"
    },
    "company": {
      "id": 0,
      "name": "string",
      "id_number": "string",
      "activity_code": "string",
      "address": {
        "street": "string",
        "street_2": "string",
        "locality_name": "string",
        "region_name": "string",
        "country_name": "string",
        "postal_code": "string"
      }
    },
    "address": {
      "street": "string",
      "street_2": "string",
      "locality_name": "string",
      "region_name": "string",
      "country_name": "string",
      "postal_code": "string"
    },
    "billing_address": {
      "street": "string",
      "street_2": "string",
      "locality_name": "string",
      "region_name": "string",
      "country_name": "string",
      "postal_code": "string"
    },
    "line_items": [
      {
        "id": 0,
        "product_id": 0,
        "product_name": "string",
        "variant_id": 0,
        "variant_name": "string",
        "variant_sku": "string",
        "units": 0,
        "unit_price": 0,
        "net_total": 0,
        "total": 0
      }
    ],
    "payments": [
      {
        "id": 0,
        "order_id": 0,
        "amount": 0,
        "absolute_amount": 0,
        "successful": true,
        "card_token_id": 0,
        "payment_method_type": "string",
        "transaction_id": "string",
        "authorization_code": "string",
        "description": "string",
        "created_at": "2019-08-24T14:15:22Z"
      }
    ],
    "refunds": [
      {
        "id": 0,
        "order_id": 0,
        "amount": 0,
        "absolute_amount": 0,
        "successful": true,
        "card_token_id": 0,
        "payment_method_type": "string",
        "transaction_id": "string",
        "authorization_code": "string",
        "description": "string",
        "created_at": "2019-08-24T14:15:22Z"
      }
    ],
    "documents": [
      {
        "id": 0,
        "document_type": "invoice",
        "document_number": "string",
        "file_url": "string"
      }
    ]
  }
}