Order

Base path: /api/data/order

POST /api/data/order

Create a new order. Subtotal, total, and discount amounts are computed server-side. If a discountCode is provided, the discount is validated and applied automatically.

Auth: Session cookie required Tenant: Scoped via x-tenant-id header

Request Body

Field	Type	Required	Description
orderNumber	string	Yes	Unique order number
items	array	Yes	Order line items (min 1)
currency	string	No	ISO 4217 currency code, 3 chars (default USD)
customer	object	Yes	Customer info
customerId	string	No	Associated customer record ID
customerRoleIds	string[]	No	Customer's role IDs for discount eligibility
discountCode	string	No	Discount code to apply
shippingAddress	object	No	Shipping address
status	enum	No	Initial status override
shippingStatus	enum	No	Initial shipping status override
shipmentId	string	No	Associated shipment ID
trackingNumber	string	No	Tracking number
notes	string	No	Order notes

Item object:

Field	Type	Required	Description
productId	string	Yes	Product ID
name	string	Yes	Product name
sku	string	Yes	Product SKU
quantity	number	Yes	Quantity (positive integer)
unitPriceCents	number	Yes	Unit price in cents (non-negative integer)
currency	string	No	Currency code (default USD)

Customer object:

Field	Type	Required	Description
name	string	Yes	Customer name
email	string	No	Customer email
discordId	string	No	Customer Discord ID

Status values: PENDING_PAYMENT, PAID, FULFILLING, SHIPPED, COMPLETE, CANCELLED, REFUNDED

Shipping status values: PENDING, LABEL_CREATED, SHIPPED, DELIVERED, FAILED

Response (201)

Returns the created order record.

Errors

Status	Condition
400	Validation error, DiscountError, or operation failure

---

GET /api/data/order/:id

Retrieve an order by ID.

Auth: Session cookie required Tenant: Scoped via x-tenant-id header

Response (200)

Returns the order record.

Errors

Status	Condition
400	Operation error
404	Order not found

---

PATCH /api/data/order/:id

Update an order by ID. All fields are optional.

Auth: Session cookie required Tenant: Scoped via x-tenant-id header

Request Body

Field	Type	Required	Description
status	enum	No	Updated order status
items	array	No	Updated line items
subtotalCents	number	No	Updated subtotal
totalCents	number	No	Updated total
discountId	string	No	Updated discount ID
discountCode	string	No	Updated discount code
discountAmountCents	number	No	Updated discount amount
taxAmountCents	number	No	Updated sales tax amount in cents
currency	string	No	Updated currency
customer	object	No	Updated customer info
customerId	string	No	Updated customer record ID
customerRoleIds	string[]	No	Updated role IDs
shippingAddress	object	No	Updated shipping address
shippingStatus	enum	No	Updated shipping status
shipmentId	string	No	Updated shipment ID
trackingNumber	string	No	Updated tracking number
notes	string	No	Updated notes

Response (200)

Returns the updated order record.

Errors

Status	Condition
400	Validation error or operation failure

---

DELETE /api/data/order/:id

Remove an order by ID.

Auth: Session cookie required Tenant: Scoped via x-tenant-id header

Response (204)

No content.

Errors

Status	Condition
400	Operation error

---

GET /api/data/order/open

Returns a paginated list of open orders for the authenticated admin's tenant.

Auth: Session cookie required + admin.access permission
Tenant: Derived from authenticated session; fails closed if missing

Query Parameters

Parameter	Type	Required	Description
status	string	No	Filter to one open status: PENDING_PAYMENT, PAID, FULFILLING, SHIPPED
search	string	No	Substring search on orderNumber
createdFrom	ISO datetime	No	Filter orders created on or after this timestamp
createdTo	ISO datetime	No	Filter orders created on or before this timestamp
page	number	No	Page number (default: 1)
pageSize	number	No	Records per page (default: 50, max: 200)

Response (200)

{
  "items": [
    {
      "id": "string",
      "orderNumber": "string",
      "status": "PENDING_PAYMENT | PAID | FULFILLING | SHIPPED",
      "shippingStatus": "PENDING | LABEL_CREATED | SHIPPED | DELIVERED | FAILED",
      "totalCents": 1000,
      "currency": "USD",
      "customerName": "string",
      "createdAt": "ISO date",
      "updatedAt": "ISO date"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 42
}

Errors

Status	Condition
400	Invalid query parameters
403	Missing admin access or tenant context

---

GET /api/data/order/open/summary

Returns per-status open-order counts for the authenticated admin's tenant. Used by the dashboard summary cards.

Auth: Session cookie required + admin.access permission
Tenant: Derived from authenticated session; fails closed if missing

Response (200)

{
  "totalOpen": 42,
  "byStatus": {
    "PENDING_PAYMENT": 10,
    "PAID": 15,
    "FULFILLING": 12,
    "SHIPPED": 5
  }
}

Errors

Status	Condition
403	Missing admin access or tenant context

---

POST /api/orders/:id/invoice-link

Generates a public, time-limited pay-by-invoice link for an existing order. Merchant pastes the returned url into an email or message; the customer opens it in a browser to pay.

Auth: Session cookie required + admin.access permission
Tenant: Derived from authenticated session; fails closed if missing

Request Body

Field	Type	Required	Description
expiresInSeconds	number	No	Token validity window in seconds. Default: 604800 (7 days)

Response (200)

{
  "url": "https://app.example.com/orders/invoice/<token>",
  "token": "<base64url-hmac-token>",
  "expiresAt": "2025-05-02T00:00:00.000Z"
}

Errors

Status	Condition
400	Validation error
403	Missing admin access or tenant context
404	Order not found
503	INVOICE_LINK_SIGNING_SECRET not configured

---

GET /orders/invoice/:token

Public (no authentication required). Verifies the HMAC-signed token, fetches the order, and renders an HTML invoice page with order summary and processor-backed payment buttons.

Auth: None — token is the credential
Tenant: Resolved from the signed token payload

Response (200)

Returns an HTML page containing:

• Order number, customer name
• Line items with unit price and subtotal
• Discount row (when applicable)
• Payment buttons for each processor-backed method the tenant has enabled (excludes VENMO_P2P, CASHAPP_P2P, ZELLE, CHIME, PAYPAL_MANUAL, BTC_MANUAL)

Errors

Status	Condition
404	Token is invalid, expired, or tampered — returned for all failures to avoid leaking whether an order exists