Shipping labels (add-on)
Quoting an order, buying a label, voiding one, and the label file itself.
Buying, voiding and quoting take kahunacart.shipping.labels, because they spend the store's money. Reading a label takes kahunacart.orders.view. See Labels.
List labels
/api/v1/kahunacart/shipping/labels
Every label this store has bought, tried to buy, or asked to have refunded, newest first. A label's status is one of six words — pending, bought, failed, void_requested, voided or void_refused — and every one of them means something different about whether money was spent.
Parameters
| Name | Type | Description |
|---|---|---|
| status optional | string |
Only labels in this state.
One of:
pending, bought, failed, void_requested, voided, void_refused |
| order_id optional | integer | Only labels for this order. |
| sort optional | string |
A column to sort every matching label by before the page is cut. Leave it out for newest first, and any other value is ignored.
One of:
order, carrier, service, tracking, paid, status, bought |
| dir optional | string |
One of:
asc, desc |
| q optional | string | Words to search for in the carrier, the service, the tracking number and the order number; every word has to be there, in any order. Applied before the sort and the page, and total counts what it found. |
| page optional | integer | |
| per_page optional | integer |
Quote a label for an order
/api/v1/kahunacart/orders/{id}/shipping/quote
Everything needed before buying a label for an order, in one call: the parcels the packer made, the box each one is in, the actual and billable weights, the services the carrier quoted with their prices and transit estimates, what the carrier makes of the delivery address, and which customs facts are missing per line. Asks the carrier for live prices, so it takes the labels permission rather than the view one.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | The order's id. |
Buy a label for an order
/api/v1/kahunacart/orders/{id}/shipping/labels
Buy a label for what is still owed on an order, and record the parcel on it. This spends the store's money. The same request twice buys one label: the purchase is keyed on the order, the service and the parcels' contents, and a second attempt is refused by a unique index rather than charged for. An outcome of unknown means the carrier did not answer in time and the purchase is being chased — it does not mean nothing was bought, and it is not a reason to try again.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | The order's id. |
| service optional | string | The service code, such as `usps_priority`. Left out, the service the customer's own shipping method names is used. |
| notify optional | boolean | Whether to email the customer that it has shipped. True unless you say otherwise. |
Void a label
/api/v1/kahunacart/shipping/labels/{id}/void
Ask the carrier to refund a label. Slow and honest about it: Shippo takes up to fourteen business days to settle, and Sendcloud queues a label that is ready to send and cancels it within fourteen days if nothing happens to it, so a status of void_requested means it has been accepted and not settled — that is not a failure. A request more than ninety days after the label was bought is refused before any call is made, and the postage is spent; Sendcloud itself refuses one after forty-two days.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | The label's id. |
Record the parcel for a label
/api/v1/kahunacart/shipping/labels/{id}/record
Write the shipment for a label that was bought and never recorded on its order — the state where the money is spent and the order does not know. Does nothing to a label that already has a shipment.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | The label's id. |
| notify optional | boolean | Whether to email the customer. True unless you say otherwise. |
Download a label file
/api/v1/kahunacart/shipping/labels/{id}/file
The label itself, streamed as the PDF, PNG or ZPL file the store's label format asked for. No tool: it answers a file rather than JSON, and list_shipping_labels already says whether a label has one.
Every purchase carries an idempotency key held by a unique index, so two presses of Buy label buy one label and the second answers 409. A label whose shipment failed to write is left bought rather than thrown away, and record writes the shipment afterwards.