Bulk orders and exports
Status changes across many orders at once, the order export, and the saved column sets.
One status change or one export across a selection of orders, run as a background job, plus the column sets a merchant saves for the export. See Orders and the admin.
Change many order statuses
/api/v1/kahunacart/orders/bulk/status
Move a selection of orders onto one status, as a single background job. Every order is its own transaction, so a failure on one does not half-apply the rest, and every change writes a history entry naming whoever asked for it and the shared message. The answer is a job id; read the per-order report back with get_bulk_run. Carts are refused — a cart is not a placed order — and so is a selection over orders.bulk.max_orders.
Parameters
| Name | Type | Description |
|---|---|---|
| order_ids required | array of integer | The orders to change |
| status required | string |
The status to move them all onto
One of:
completed, canceled, archived |
| message optional | string | One shared note, recorded on every history entry the run writes |
| notify optional | boolean |
Whether to tell anybody. False changes the statuses quietly and the history entries record that the silence was deliberate.
Default:
true |
Read a bulk run
/api/v1/kahunacart/orders/bulk/{jobId}
What a bulk status change did, order by order: which changed, which were already in that status, and which failed and why. finished is false until the worker has completed the job.
Parameters
| Name | Type | Description |
|---|---|---|
| jobId required | integer | The job id bulk_order_status returned |
Export orders
/api/v1/kahunacart/orders/bulk/export
Orders out in the columns you choose, as CSV text or as JSON rows. Two scopes: orders is one row per order and line_items is one row per line, which are two different files and not one with a flag. Money is a decimal string in each order's own currency and every row carries currency. Refunded orders are included — an export is a ledger. Nothing is written, despite the POST: a column list, a date range and a selection of ids need a body. Over orders.export.max_rows it is refused rather than truncated. Multi-currency exports always include currency and fx_to_base, even with custom columns. Missing rates are empty strings; amounts stay native. They also always include settlement_currency, settlement_amount and settlement_rate, what the payment provider paid out for the order's first charge that has a settlement, with settlement_amount in settlement_currency; empty when there is none.
Parameters
| Name | Type | Description |
|---|---|---|
| scope optional | string |
One row per order, or one row per line
One of:
orders, line_itemsDefault:
orders |
| format optional | string |
CSV comes back as text in `body`; JSON as rows in `data`
One of:
csv, jsonDefault:
csv |
| column_set_id optional | integer | A saved column set to use; wins over `columns` and sets the scope |
| columns optional | array of string | Column names, in the order you want them. Ask list_export_column_sets for the vocabulary. |
| from optional | integer | Earliest completion time, unix epoch |
| to optional | integer | Latest completion time, unix epoch |
| statuses optional | array of string | Only these order statuses; every status but cart by default |
| order_ids optional | array of integer | Only these orders, which is how a selection in the admin is exported |
| filter optional | object | The order list's filters, with list_orders' keys: product, variant, from and to (YYYY-MM-DD days), customer, status, payment, fulfillment, channel and location. Only those orders, and in a line_items export with a product only that product's lines. Keys: `product`, `variant`, `from`, `to`, `customer`, `status`, `payment`, `fulfillment`, `channel`, `location` |
List export column sets
/api/v1/kahunacart/export-column-sets
The saved column choices, plus the whole column vocabulary for both scopes and the defaults a merchant gets when they have saved none. An unknown column is refused by name rather than silently dropped, which is why the vocabulary is published.
Save an export column set
/api/v1/kahunacart/export-column-sets
Save a named column choice so the same export comes out the same way next month. The column order is the merchant's and is preserved exactly — a set that came back in a different order would break every spreadsheet formula pointing at column F.
Parameters
| Name | Type | Description |
|---|---|---|
| name required | string | What the merchant calls it |
| scope optional | string |
One of:
orders, line_itemsDefault:
orders |
| columns required | array of string | Column names, in the order they should appear in the file |
Update an export column set
/api/v1/kahunacart/export-column-sets/{id}
Rename a set, move it to the other scope, or replace its columns. Sending columns replaces the whole list, which is how a column is removed; omitting it leaves the list standing.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Column set id |
| name optional | string | |
| scope optional | string |
One of:
orders, line_items |
| columns optional | array of string |
Delete an export column set
/api/v1/kahunacart/export-column-sets/{id}
Remove a saved column choice. Nothing else changes; exports keep working from their defaults.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Column set id |
Export invoices as PDF
/api/v1/kahunacart/orders/bulk/pdf
Invoices for many orders, as a ZIP of PDFs or one collated document. Writes nothing, and is a POST only because the selection travels in a body.
Both bulk routes answer with a job id. Poll GET /kahunacart/orders/bulk/{jobId} for progress and for the finished file.