Orders

List ordersCopy Anchor Link

GET /api/v1/stores/{storeId}/orders

A page of orders, newest first unless sort says otherwise. meta.units says, for each order on the page, how many units were ordered and how many have been sent; meta.labelled names the ones with a postage label bought.

Needs orders:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders" \
  -H "Authorization: Bearer $TOKEN"

Get an orderCopy Anchor Link

GET /api/v1/stores/{storeId}/orders/{orderId}

The order with its lines and its adjustments. With format=acp, the same order in the Agentic Commerce Protocol’s shape instead.

Needs orders:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID" \
  -H "Authorization: Bearer $TOKEN"

Cancel an orderCopy Anchor Link

DELETE /api/v1/stores/{storeId}/orders/{orderId}

Cancels the order and puts back the stock not yet sent. It refunds nothing: refund it separately. Cancelling an order already cancelled changes nothing. Emits order.canceled.v1.

Needs orders:write.

Parameters

Body, which may be left out: it is then read as {}.

Answers 200

curl -X DELETE "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Correct an order’s contact details or addressCopy Anchor Link

PATCH /api/v1/stores/{storeId}/orders/{orderId}

Corrects the buyer’s email, name or phone, or the delivery address. Never moves money: tax stays as charged, and a difference in delivery is settled by editing the order. Refused for an order wholly sent, one with a live label or a supplier, and for a paid order moving to another country. Changing the email does not change whose order it is, and the old address is told.

Needs orders:write.

Parameters

Body

Answers 200

curl -X PATCH "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

List orders waiting on a card checkCopy Anchor Link

GET /api/v1/stores/{storeId}/orders/authentications

Orders whose payment is held for a card issuer’s check (such as 3D Secure) that the buyer has not finished, the link soonest to expire first. The links themselves are never listed.

Needs orders:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/authentications" \
  -H "Authorization: Bearer $TOKEN"

Renew a card check linkCopy Anchor Link

POST /api/v1/stores/{storeId}/orders/authentications/{sessionId}

Makes a new link for a buyer to finish their card check, and answers with it. The new link replaces the old one, which stops working. Whoever holds the link can pay for and then read the order, so send it only to the buyer and do not store it. Refused for a checkout that is not waiting on a check.

Needs orders:write.

Parameters

Answers 200

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/authentications/$SESSION_ID" \
  -H "Authorization: Bearer $TOKEN"

Approve or reject a held orderCopy Anchor Link

POST /api/v1/stores/{storeId}/orders/{orderId}/approval

Answers an order an AI agent placed above the shop’s approval limit, which waits in manual_review. Approving takes the payment, which is the first time money moves, so it can fail as any payment can; it answers the order and anything the payment still needs. Rejecting cancels the order, puts its stock back and emits order.canceled.v1; it answers the order.

Needs orders:write.

Parameters

Body

Answers 200

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/approval" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

List an order’s changesCopy Anchor Link

GET /api/v1/stores/{storeId}/orders/{orderId}/changes

Every change proposed or made to the order since it was placed, oldest first.

Needs orders:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/changes" \
  -H "Authorization: Bearer $TOKEN"

Open an order changeCopy Anchor Link

POST /api/v1/stores/{storeId}/orders/{orderId}/changes

Opens an empty change to an order, to edit what it holds. Add lines to it, then confirm it. Nothing moves until it is confirmed.

Needs orders:write.

Parameters

Body, which may be left out: it is then read as {}.

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/changes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Get an order changeCopy Anchor Link

GET /api/v1/stores/{storeId}/orders/{orderId}/changes/{changeId}

The change, its lines, and in delta what it would cost if confirmed now.

Needs orders:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/changes/$CHANGE_ID" \
  -H "Authorization: Bearer $TOKEN"

Confirm, decline or cancel an order changeCopy Anchor Link

POST /api/v1/stores/{storeId}/orders/{orderId}/changes/{changeId}

Settles a pending change. Confirming moves the stock and the money and emits order.changed.v1: a change that gives money back refunds it to the card, and one that leaves the customer owing more is recorded as owed, not charged. A change that would refund an order paid in stablecoins, imported from another platform, or not yet paid for is refused. Declining or cancelling closes it with nothing moved.

Needs orders:write.

Parameters

Body

Answers 200

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/changes/$CHANGE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Add a line to an order changeCopy Anchor Link

POST /api/v1/stores/{storeId}/orders/{orderId}/changes/{changeId}/actions

Adds one action to a pending change: add a variant, change a line’s quantity, remove a line, or add or take off delivery. Checked against the order as it stands now. Amounts are in minor units.

Needs orders:write.

Parameters

Body

Any JSON.

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/changes/$CHANGE_ID/actions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Remove a line from an order changeCopy Anchor Link

DELETE /api/v1/stores/{storeId}/orders/{orderId}/changes/{changeId}/actions/{actionId}

Takes an action off a change nobody has confirmed yet.

Needs orders:write.

Parameters

Answers 200

curl -X DELETE "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/changes/$CHANGE_ID/actions/$ACTION_ID" \
  -H "Authorization: Bearer $TOKEN"

List an order’s downloadsCopy Anchor Link

GET /api/v1/stores/{storeId}/orders/{orderId}/downloads

Every file the order bought, with how many times it has been downloaded and how many more it may be. An unpaid, cancelled or refunded order is listed too, with available false and the reason.

Needs orders:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/downloads" \
  -H "Authorization: Bearer $TOKEN"

Set a download allowanceCopy Anchor Link

PATCH /api/v1/stores/{storeId}/orders/{orderId}/downloads

Sets how many times one line of the order may download one file. It cannot be set below the downloads already taken; set it to that count to stop further downloads.

Needs orders:write.

Parameters

Body

Answers 200

curl -X PATCH "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/downloads" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

List an order’s fulfillmentsCopy Anchor Link

GET /api/v1/stores/{storeId}/orders/{orderId}/fulfillments

Every despatch of the order, with its tracking events and the lines it carries.

Needs orders:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/fulfillments" \
  -H "Authorization: Bearer $TOKEN"

Create a fulfillmentCopy Anchor Link

POST /api/v1/stores/{storeId}/orders/{orderId}/fulfillments

Records a despatch of some or all of an order’s lines, and takes the stock off the shelf. A line cannot be sent more times than is left of it. Emits fulfillment.created.v1. Send an Idempotency-Key header to make a retry safe: a second request with the same key answers what the first did.

Needs orders:write.

Parameters

Body

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/fulfillments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Record a tracking eventCopy Anchor Link

POST /api/v1/stores/{storeId}/orders/{orderId}/fulfillments/{fulfillmentId}/events

Says where a despatch has got to, and moves its status and the order’s with it. failed_attempt leaves the status as it is; returned marks the despatch failed. Emits fulfillment.updated.v1, and delivered writes to the buyer. Send an Idempotency-Key header to make a retry safe: a second request with the same key answers what the first did.

Needs orders:write.

Parameters

Body

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/fulfillments/$FULFILLMENT_ID/events" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Get what a shipping label needsCopy Anchor Link

GET /api/v1/stores/{storeId}/orders/{orderId}/label-quotes

What a label for this order would start from: what is left to send and what it weighs, the shop’s boxes, and whether a card and a ship from address are in place. Asks no carrier.

Needs orders:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/label-quotes" \
  -H "Authorization: Bearer $TOKEN"

Quote a shipping labelCopy Anchor Link

POST /api/v1/stores/{storeId}/orders/{orderId}/label-quotes

Asks the carrier what it would cost to send a parcel for this order, by every service it offers, and checks the address. Name one of: the lines the parcel carries, a despatch with no label yet, or a return to bring back. Buys nothing.

Needs orders:read.

Parameters

Body

Answers 200

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/label-quotes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

List an order’s shipping labelsCopy Anchor Link

GET /api/v1/stores/{storeId}/orders/{orderId}/labels

Every label the order has had, bought or not, newest first. At most fifty.

Needs orders:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/labels" \
  -H "Authorization: Bearer $TOKEN"

Buy a shipping labelCopy Anchor Link

POST /api/v1/stores/{storeId}/orders/{orderId}/labels

Buys a label at a rate from a quote and charges the account’s postage card. For lines, it also records the despatch with its tracking number. Answers 201 once the label is bought, and 202 while it is not yet: the bank wants the cardholder (clientSecret is set), or the carrier has not answered. Send the same purchaseKey again, or resume the label, to carry on; it never buys twice.

Needs orders:write.

Parameters

Body

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/labels" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Resume a shipping label purchaseCopy Anchor Link

POST /api/v1/stores/{storeId}/orders/{orderId}/labels/{labelId}/resume

Carries an unfinished purchase on, once the bank’s check has been answered. Does nothing to a finished label, so it is safe to call any number of times. Answers 202 while the label is still not bought.

Needs orders:write.

Parameters

Answers 200

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/labels/$LABEL_ID/resume" \
  -H "Authorization: Bearer $TOKEN"

Void a shipping labelCopy Anchor Link

POST /api/v1/stores/{storeId}/orders/{orderId}/labels/{labelId}/void

Asks the carrier to refund a label that has not been used. Usually answers 202 with the label void_pending: a carrier takes days to agree, and the postage goes back to the card when it does. The card processing is not returned. The despatch stays, with its tracking number cleared, so a new label can be bought for it. Asking twice is safe.

Needs orders:write.

Parameters

Answers 200

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/labels/$LABEL_ID/void" \
  -H "Authorization: Bearer $TOKEN"

List an order’s metafieldsCopy Anchor Link

GET /api/v1/stores/{storeId}/orders/{orderId}/metafields

Every metafield value set on an order, each with its definition.

Needs orders:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/metafields" \
  -H "Authorization: Bearer $TOKEN"

Set an order’s metafieldsCopy Anchor Link

PUT /api/v1/stores/{storeId}/orders/{orderId}/metafields

Sets up to 25 values in one call. A null value clears its field; keys not named are left alone. An app may set only the fields its manifest declares.

Needs orders:write.

Parameters

Body

Answers 200

curl -X PUT "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/metafields" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Add a return reasonCopy Anchor Link

POST /api/v1/stores/{storeId}/return-reasons

A reason of the shop’s own, in its own words. It goes last and is offered from the next return. code is one of the platform’s, because review rules read that and not the words.

Needs orders:write.

Parameters

Body

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/return-reasons" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Take back a despatchCopy Anchor Link

DELETE /api/v1/stores/{storeId}/orders/{orderId}/fulfillments/{fulfillmentId}

For a parcel recorded and never really sent. Units go back to the shelves they came from, held for the order again, and the order steps back. Refused once a carrier has it, for a supplier’s or a digital despatch, for units refunded or returned, and while a label is live. The buyer is not emailed.

Needs orders:write.

Parameters

Answers 200

curl -X DELETE "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/fulfillments/$FULFILLMENT_ID" \
  -H "Authorization: Bearer $TOKEN"

Correct a despatch’s trackingCopy Anchor Link

PATCH /api/v1/stores/{storeId}/orders/{orderId}/fulfillments/{fulfillmentId}

Corrects a carrier or tracking number somebody typed. Refused for a label bought here, whose number belongs to the label, and for a cancelled despatch. No email is sent.

Needs orders:write.

Parameters

Body

Answers 200

curl -X PATCH "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/fulfillments/$FULFILLMENT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

See what correcting an order’s details would meanCopy Anchor Link

POST /api/v1/stores/{storeId}/orders/{orderId}/details/preview

Says which fields would change, and whether tax or delivery is affected. Changes nothing. When it has notices, hand its digest to updateOrderDetails as acknowledged.

Needs orders:write.

Parameters

Body

Answers 200

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/details/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Keep an order back from being sentCopy Anchor Link

POST /api/v1/stores/{storeId}/orders/{orderId}/hold

Stops a paid order being sent until it is released. Nothing else about it changes and the shopper is not told. An order already on hold keeps the reason it was first held for.

Needs orders:write.

Parameters

Body

Answers 200

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/hold" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Release an order kept backCopy Anchor Link

DELETE /api/v1/stores/{storeId}/orders/{orderId}/hold

Lets the order be sent again. An order that was not held is left as it is.

Needs orders:write.

Parameters

Answers 200

curl -X DELETE "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/hold" \
  -H "Authorization: Bearer $TOKEN"

List the tags a shop’s orders carryCopy Anchor Link

GET /api/v1/stores/{storeId}/orders/facets

For the controls that narrow the list. The commonest first, at most a hundred.

Needs orders:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/facets" \
  -H "Authorization: Bearer $TOKEN"

Change an order’s tagsCopy Anchor Link

PATCH /api/v1/stores/{storeId}/orders/{orderId}/tags

Puts tags on and takes them off by name, so two people labelling one order do not lose each other’s work. Sending the same change twice leaves the order as the first left it. Tags are the shop’s own and are never shown to a shopper.

Needs orders:write.

Parameters

Body

Answers 200

curl -X PATCH "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/tags" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

List an order’s notesCopy Anchor Link

GET /api/v1/stores/{storeId}/orders/{orderId}/notes

What the shop has written about the order, oldest first.

Needs orders:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/notes" \
  -H "Authorization: Bearer $TOKEN"

Add a note to an orderCopy Anchor Link

POST /api/v1/stores/{storeId}/orders/{orderId}/notes

Adds a note for the shop’s staff. Notes cannot be edited or deleted; a correction is another note.

Needs orders:write.

Parameters

Body

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/notes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Record an invoice paymentCopy Anchor Link

POST /api/v1/stores/{storeId}/orders/{orderId}/payments

Records that an order placed on account has been paid, by bank transfer, cheque or any other way outside the shop. Only for an order on payment terms, and only once. Emits order.paid.v1, so what follows a card payment follows this too.

Needs orders:write.

Parameters

Body, which may be left out: it is then read as {}.

Answers 200

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/payments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

List an order’s refundsCopy Anchor Link

GET /api/v1/stores/{storeId}/orders/{orderId}/refunds

Every adjustment to the order’s money, newest first: refunds, and store credit, returns, exchanges, cancellations and disputes.

Needs orders:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/refunds" \
  -H "Authorization: Bearer $TOKEN"

Refund an orderCopy Anchor Link

POST /api/v1/stores/{storeId}/orders/{orderId}/refunds

Refunds all or part of an order, everything still refundable when amount is left out. A card payment is refunded to the card; an order on account or paid with credit is recorded as refunded with nothing sent. Refused for an order imported from another platform, one paid in stablecoins, one whose payment has not completed, and an amount past what is left. Emits order.refunded.v1. Send an Idempotency-Key header to make a retry safe: a second request with the same key answers what the first did.

Needs orders:write.

Parameters

Body, which may be left out: it is then read as {}.

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/refunds" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

List an order’s returnsCopy Anchor Link

GET /api/v1/stores/{storeId}/orders/{orderId}/returns

The returns asked for on this order, and in returnable each line with what could still come back and why not. Also open to returns:read, a permission for the shop front.

Needs orders:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/returns" \
  -H "Authorization: Bearer $TOKEN"

Open a returnCopy Anchor Link

POST /api/v1/stores/{storeId}/orders/{orderId}/returns

Opens a return of some of an order’s sent lines. With orders:write a closed return window can be overridden. Approved at once when the shop’s policy approves returns on its own. Emits return.requested.v1. Also open to returns:write, a permission for the shop front.

Needs orders:write.

Parameters

Body, which may be left out: it is then read as {}.

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/orders/$ORDER_ID/returns" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json