Orders

There are two ways to read an order, and they are not interchangeable.

Tool	Identity	Scope	Lookup
`get_my_order`	Buyer OAuth bearer	The buyer’s own orders, cross-store	`order_id`
`get_order`	Platform / store key	A single store	`id` + `orders:read`

get_my_order (and list_my_orders) are buyer-account tools — they return whatever the signed-in buyer purchased anywhere on Artos. Send the buyer bearer only. See Buyer account.
get_order is the store-scoped read for platform/merchant automation. It requires the orders:read scope and is store-bound (store_slug on the bridge).


{ "name": "get_my_order", "arguments": { "order_id": "order_789" } }


{ "name": "get_order", "arguments": { "store_slug": "energy-sport", "id": "order_789" } }

Human vs agent attribution

Every order records its buyer type, so agent-attributed orders are tracked separately from human storefront traffic across the dashboard and analytics. An order placed through the bridge is additionally attributed to the OAuth client that placed it.

Lifecycle webhooks

When ucp.webhookUrl is configured (platform setting or UCP_WEBHOOK_URL), Artos emits signed POST webhooks. A blank URL disables them silently.

Event `type`	When
`order.placed`	Order placed
`order.paid`	Payment captured
`order.shipped`	Fulfillment shipped
`order.delivered`	Fulfillment delivered
`order.cancelled`	Order cancelled
`order.refunded`	Refund issued

Payload


{
  "type": "order.shipped",
  "ucp": { "version": "…" },
  "order": {
    "id": "…",
    "permalink_url": "https://api.artos.sh/s/energy-sport/orders/…"
  }
}

Verify the signature (RFC 9421)

Each request carries Content-Digest, Signature-Input, Signature, and UCP-Version. The signature covers @method, @target-uri, and content-digest with the store’s ES256 key, published at the store’s /.well-known/ucp.


// 1. Recompute Content-Digest over the raw body and compare.
// 2. Fetch the store's signing key from /s/:slug/.well-known/ucp (signing_keys).
// 3. Verify Signature against the covered components in Signature-Input.
import { verifyMessageSignature } from "your-rfc9421-library"

Always verify before acting on a webhook; treat unverified requests as untrusted.

Limitations (Phase 1)

Single destination URL for all stores/agents — per-agent webhook_url from profiles is a future phase.
Return events are not webhooked yet — use list_my_returns + get_my_order.

Reconciliation

Prefer webhooks as the primary channel. On a missed delivery, poll get_order (store) or get_my_order (buyer).