Store orders

A store order is an order like a till sale, with source: online, the number the shopper sees in store_number (from 1001), a delivery or collection in fulfilment, and where its goods are in fulfilment_status. One list holds both, so your reports, stock and refunds work the same way.

Scroll sideways to see all of it →

1. Find them

curl

curl -sS "https://api.tuppence.ai/v1/orders?source=online&limit=10" \
  -H "Authorization: Bearer $TUPPENCE_SECRET_KEY"

Node

import { Tuppence } from "@tuppence/node";

const tuppence = new Tuppence(process.env.TUPPENCE_SECRET_KEY);
const orders = await tuppence.request("GET", "/v1/orders", { query: { source: "online", limit: 10 } });
console.log(orders.data.length);

Python

import os
from tuppence import Tuppence

tuppence = Tuppence(os.environ["TUPPENCE_SECRET_KEY"])
orders = tuppence.request("GET", "/v1/orders", params={"source": "online", "limit": 10})
print(len(orders["data"]))

Parameter	Finds
q	An order’s number (42 or #0042), the store’s own number (1042), or a customer’s email or name
fulfilment_status	unfulfilled, partially_fulfilled, fulfilled, delivered or cancelled
from, to	Business days, YYYY-MM-DD, both included
status	open, held, paid, completed or voided
customer	One customer’s orders (cus_…)

2. Read its page

GET /v1/orders/{id}/details answers who it is for, its delivery or collection, what the shopper was shown at checkout (snapshot), whether it can still be changed (editable), what is left of each line, and its timeline (payments, refunds, stock and messages), oldest first.

3. Change it before it is sent

An order can change while its fulfilment_status is unfulfilled: nothing of it is on its way.

Change	Route	Who
The delivery address, in the same country	POST /v1/orders/{id}/delivery_address	orders:write, keys too
Take lines off, refunded	POST /v1/orders/{id}/remove_lines	A person in the dashboard, with a fresh second factor
Cancel: everything left refunded, back in stock, the sale voided, fulfilment_status: cancelled	POST /v1/orders/{id}/cancel	A person in the dashboard, with a fresh second factor

4. Send the confirmation again

POST /v1/orders/{id}/resend_confirmation (orders:write, keys too) sends the shopper’s confirmation again, word for word, to the email they gave at checkout, with the same link to the order’s status page. It never goes to another address. The order’s timeline shows who sent it.

A refund goes back to the card the order was paid with. Tuppence’s fee on the payment isn’t returned. Delivery comes off only by cancelling. A till sale is refused with 409: take a return at the till instead.

An order a channel took the money for (a TikTok Shop order) is cancelled on the channel first, which refunds its buyer. Its stock comes back, nothing is refunded by Tuppence, and the answer’s return_order is null.

When a shopper asks for their data

You decide what happens to a shopper’s data, and Tuppence carries it out from their customer record, as for any client (A client’s data).

Export (GET /v1/customers/{id}/export) includes store: their baskets with the contact they typed, each checkout with what they were shown (snapshot), their store orders with the delivery address and the tax record (tax), parcels and tracking, returns with their reasons and the photos as files, the back-in-stock alerts they asked for and the cancellations they sent. elsewhere names who else was given some of it to do their part (carriers, the tax service, a sales channel): their copies follow their own rules. It needs orders:read; without it store is empty and withheld says so.

Deletion (POST /v1/customers/{id}/delete) also removes their name, email, phone and street address from every basket, checkout and order, their delivery notes and gift messages, the words of their returns and the photos, and their alerts. Every amount, order line and tax line stays, with the country, region and postcode the goods went to: that is the tax evidence you must keep. It is refused (409 invalid_state) while one of their orders is still on its way or a return of theirs is open: Finish or cancel order #1042 first, then delete this client.

When the shopper asks themselves. Every order’s page links to Your data, where the shopper can ask for a copy or to be deleted. The request reaches you as an alert (store_privacy_request_received, the store.privacy_request_received event) and waits on their customer page with 30 days on the clock. GET /v1/store_privacy_requests?customer=cus_…&status=open lists them; POST /v1/store_privacy_requests/{id}/complete answers one: a copy goes on their order’s page to download for 30 days, and a deletion runs as above, refused the same way while something of theirs is open.

Kept only as long as needed. Each night, a basket’s contact and street address go 30 days after the basket last changed if it never became an order, and a checkout that ended without an order keeps only its figures after 90 days. Visits to the store are counted without knowing who made them, and the counts behind them go after 30 days.

Agents and the assistant

Over MCP and in the Tuppence Assistant, list_store_orders and get_store_order read the store’s orders (a till sale isn’t one). cancel_store_order is the assistant’s only: the person approves it with a fresh second factor, and no API key or agent is ever offered it.

Events

Event	When
order.updated	The address changed
order.returned	Lines came off, or the order was cancelled
order.voided	The sale was voided

Next

• Store checkout
• Selling products online
• Refunds and payments