Orders

Secure order creation, statuses, and nickname changes.

A customer can create an order without an account. The built-in storefront checkout is the safest integration: it displays the current legal documents, collects the required consents, creates an idempotency key, and obtains a Turnstile token.

Creation

If you build a custom checkout, first fetch the current storefront and show the legal documents selected by the shop. Submit their exact legalDocumentVersion with the three informed consents:

curl -X POST https://api.itemshop.dev/api/v2/orders \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <random-32-to-128-character-value>" \
  -H "cf-turnstile-response: <widget-token>" \
  -d '{
    "productId": "<productId>",
    "nickname": "Steve",
    "paymentMethodName": "imojeTransfer:blik",
    "email": "[e-mail]",
    "quantity": 1,
    "termsAccepted": true,
    "immediatePerformanceConsent": true,
    "withdrawalAcknowledged": true,
    "legalDocumentVersion": "<64-character-SHA-256-of-the-documents-shown>"
  }'

Reuse an Idempotency-Key only for an identical retry. A new purchase attempt needs a new random key. In production, a missing Turnstile token or a stale/mismatched legal-document version blocks checkout.

The guest response contains limited data, a redirectUrl, orderId, and an opaque statusToken. Store that capability only on the client that needs to track the order; never put it in logs or a public URL.

Statuses

Status	Meaning
pending	Created, awaiting payment
paid	Paid and ready for plugin fulfilment
processing	The plugin started fulfilment
completed	The plugin acknowledged fulfilment
cancelled	Cancelled
failed	Payment failed
dispute	Dispute

The customer reads the limited status through GET /orders/public/{orderId}/status with the capability returned by checkout:

curl https://api.itemshop.dev/api/v2/orders/public/<orderId>/status \
  -H "x-order-status-token: <statusToken>"

GET /orders/payment-status/{orderId} exposes additional provider data and therefore requires a Bearer session for a user who can access the order’s shop.

Changing status (dashboard or integration)

A user with access or a shop key with orders:write can change status manually:

curl -X PUT https://api.itemshop.dev/api/v2/orders/<shopId>/orders/<orderId>/status \
  -H "X-API-Key: <shop-key>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "completed", "reason": "Fulfilled manually" }'

Nickname change

Before fulfilment completes, a customer can change the nickname by confirming a code sent to the email stored on the order:

1. Request a code

   POST /orders/public/{orderId}/nickname/request-change with the order’s email. The API sends a 6-digit code valid for 10 minutes.

2. Confirm

   POST /orders/public/{orderId}/nickname/change with the code and new nickname. After verification, the nickname changes and the previous value remains in history.