Server-to-server, tracking-only mirror saved with orders.channel = external_storefront. Requires a vendor Sanctum Bearer token
with orders:write (or a legacy wildcard token). Reuse the existing inventory-sync
credential after granting this scope; catalogue:write alone does not permit this call.
Customer tokens, widget embed keys and cookie sessions cannot record purchases.
The supplied vendor_id must match the authenticated vendor; it cannot override token ownership.
Send only finalized paid purchases and include ALL lines. An ordinary line omits
scan/routine fields and remains unattributed. A recommended line requires a scan ID,
a ProductUsageRoutine row ID, or both. Oyster validates vendor, product, scan and
owning customer; routine-only lines derive the scan, and scan-only lines must match
an actual recommended product. All recommended lines must belong to one Oyster
customer. Different scans for that customer are allowed. Email is optional context,
never attribution authority. A line names its product by SKU, or by the store's own product and
variant ids with a request platform, matching the catalogue sync, so a product synced without a
SKU can be credited. Unknown SKUs or store ids, or invalid attribution, reject the entire
request with 422; no products or customers are created.
Amounts exclude additional checkout/processing charges and precede later refunds.
Unit price is pre-discount; line discount is the total discount for that line.
Order discount must equal the sum of line discounts. Total equals sum(price*quantity)
minus discounts plus shipping plus tax. shipping_amount is the net shipping amount
after shipping discounts; discount_amount contains item discounts only.
Supported currency codes and at most two
decimal places are accepted. Integer minor-unit arithmetic checks the breakdown.
Identity is (authenticated vendor, order_id). A namespaced reference
is protected by database uniqueness, including simultaneous calls. Canonicalized
identical retries return the existing order; changed purchase payloads return 409.
Original external numbers/line IDs are retained in metadata/snapshots. Oyster's
unique display number contains the merchant number plus a stable identity suffix.
Preserve line ordering on retries; it determines the primary legacy scan and is
included in the payload hash. Omitted money breakdown fields normalize to zero.
Numeric/string amounts with the same value normalize identically.
Oyster takes no payment, wallet funds, inventory, shipment or customer confirmation.
This endpoint does not enqueue Klaviyo or other marketing events. It records purchase
attribution, not current net revenue or proof of delivery.
Retry transport failures, 429 and 5xx with backoff using the same identity/payload.
Fix credentials on 401/403 and review 409/422 rather than repeatedly retrying unchanged.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||