Order Types

Order, OrderItem, OrderTax, OrderDiscount, OrderCustomer, and OrderAmounts — the shapes returned by every Orders API endpoint.

Schemas returned by the Orders API and embedded inside CheckoutSession responses and Webhook payloads.

All monetary amounts are CurrencyAmount values in the order's currency (e.g. cents for USD, pence for GBP, etc).

Order

The full order resource.

Field	Type	Description
`id`	OrderId	Unique order identifier.
`externalId`	string/null	Your internal order identifier, if provided at creation time. Unique per organization and mode.
`provider`	string	System that holds the order's record: `native` for orders held by Decal, `square` or `clover` for POS.
`currency`	FiatCurrency	The currency the order is charged in. Every amount on the order is in this currency.
`status`	string	`open`, `completed`, or `cancelled`.
`paymentStatus`	string	`unpaid`, `partially_paid`, `paid`, `overpaid`, `partially_refunded`, or `refunded`.
`collectionMethod`	OrderCollectionMethod	How payment is expected. See OrderCollectionMethod.
`issuedAt`	DateTime	When the bill was issued to the payer. Omitted on an immediate purchase or a bill not yet sent.
`dueAt`	DateTime	When payment is expected. Omitted on an immediate purchase.
`source`	OrderSource	Read-only. The channel that created the order. Always present. See OrderSource.
`amounts`	OrderAmounts	Monetary amounts for the order.
`items`	OrderItem[]	Line items.
`taxes`	OrderTax[]	Taxes applied to the order.
`discounts`	OrderDiscount[]	Discounts applied to the order.
`customer`	OrderCustomer / null	Customer snapshot at time of order.
`shippingAddress`	ShippingAddress / null	Shipping address.
`locationId`	LocationId / null	ID of the associated merchant location, if any.
`metadata`	Metadata / null	Key/value data attached to the order.
`paidAt`	DateTime / null	When payment was received.
`createdAt`	DateTime	When the order was created.
`updatedAt`	DateTime	When the order was last modified.
`version`	integer	Revision counter, starting at `1`. Increments only when the order actually changes, so it is safe to compare across two reads or two webhook deliveries to decide which is newer. Unlike `updatedAt`, it does not move when a sync rewrites the order with identical data.

OrderCollectionMethod

How payment on an order is expected, returned as the collectionMethod field on every Order. It is a string union:

type OrderCollectionMethod = "immediate" | "invoice";

Value	Description
`immediate`	A purchase paid at checkout. `issuedAt` and `dueAt` are omitted.
`invoice`	A bill paid later. `dueAt` says when payment is expected; `issuedAt` is omitted until the bill is sent.

The channel that created an order, returned as the source field on every Order. It is set once when the order is created and never changes. It is read-only: no request accepts it, and orders created through the API are always api. It is a string union:

type OrderSource =
  | "storefront"
  | "checkout_link"
  | "api"
  | "dashboard"
  | "terminal"
  | "external_pos";

Value	Description
`storefront`	Placed by a customer on the merchant's Decal storefront.
`checkout_link`	Created when a customer opened a checkout or payment link.
`api`	Created through the Decal API.
`dashboard`	Created by the merchant's staff in the Decal dashboard.
`terminal`	Rung up on Decal's own counter systems.
`external_pos`	Rung up on a connected third-party point of sale, such as Square.

source is independent of provider, which names the system that holds the order's record: an order created on a Decal storefront can still be held by a connected POS.

OrderAmounts

Grouped monetary amounts for the order.

Field	Type	Description
`subtotal`	CurrencyAmount	Sum of item totals.
`tax`	CurrencyAmount	Total tax amount.
`discount`	CurrencyAmount	Total discount amount.
`tip`	CurrencyAmount	Tip amount.
`total`	CurrencyAmount	Amount due: `subtotal + tax - discount + tip`.
`paid`	CurrencyAmount	Amount paid so far. Drives `paymentStatus`.

OrderItem

A line item on an order.

On create/update requests:

Field	Type	Required	Description
`name`	string	yes	Display name for the line item.
`quantity`	integer	yes	Quantity (must be a positive integer).
`unitPrice`	CurrencyAmount	yes	Price per unit. Must be non-negative.
`description`	string	no	Item description.
`externalId`	string	no	Your internal product identifier (SKU, POS ID, etc.).
`metadata`	Metadata	no	Key/value data for the item.

On responses, additional fields:

Field	Type	Description
`id`	string	Item identifier.
`totalPrice`	CurrencyAmount	`unitPrice × quantity`.
`imageUrl`	string/null	URL to an image for the item.
`itemType`	string	`product` for standard items, `value_load` for stored value reloads.

OrderTax

A tax line on the order.

On create/update requests:

Field	Type	Required	Description
`type`	string	yes	`additive` (added on top of subtotal) or `inclusive` (already embedded in item prices).
`amount`	CurrencyAmount	yes	Tax amount. Must be positive.
`name`	string	no	Label shown on the receipt. Defaults to `Tax`.
`externalId`	string	no	Your internal tax identifier (e.g. from your POS or accounting system).

On responses, additional fields:

Field	Type	Description
`id`	string	Tax identifier.
`rate`	number/null	Percentage rate as a number (e.g. `8.5` for 8.5%) if applicable, otherwise `null` for flat amounts.
`scope`	string	`order` for order-level taxes, `line_item` for per-item taxes.

OrderDiscount

A discount line on the order. Provide one of two shapes on create/update depending on type.

Fixed amount (type: "fixed"):

Field	Type	Required	Description
`type`	string	yes	Must be `fixed`.
`amount`	CurrencyAmount	yes	Discount amount. Must be positive.
`name`	string	no	Label shown on the receipt. Defaults to `Discount`.
`externalId`	string	no	Your internal discount identifier (e.g. from your POS or coupon system).

Percentage (type: "percentage"):

Field	Type	Required	Description
`type`	string	yes	Must be `percentage`.
`amount`	number	yes	Percentage to discount (e.g. `10` = 10% off), from 0.01 to 100. Rounded to two decimal places.
`name`	string	no	Label shown on the receipt. Defaults to `Discount`.
`externalId`	string	no	Your internal discount identifier (e.g. from your POS or coupon system).

Percentage discounts are calculated against the entire items subtotal automatically.

On responses, every discount has the same shape regardless of type:

Field	Type	Description
`id`	string	Discount identifier.
`name`	string	Discount label.
`type`	string	`fixed` or `percentage`.
`amount`	number	Deprecated — read `percentOff` and `appliedAmount` instead. For `fixed` discounts: CurrencyAmount. For `percentage` discounts: the percentage value (e.g. `10`).
`percentOff`	number/null	For `percentage` discounts: the percentage taken off, to two decimal places (e.g. `12.5` for 12.5% off). `null` for `fixed` discounts.
`appliedAmount`	number	The money the discount takes off, as a CurrencyAmount, for either type.
`scope`	string	`order` for order-level discounts, `line_item` for per-item discounts.
`externalId`	string	Your internal discount identifier, if provided at creation time.

OrderCustomer

On create/update requests — provide one of these to associate or create a customer:

Field	Type	Description
`id`	CustomerId	Existing Decal customer ID.
`externalId`	string	Your own customer identifier. Creates a customer record if none exists for this external ID.
`email`	string	Customer email. Creates the customer record if they don't exist.
`phone`	string	Customer phone number. Creates the customer record if they don't exist.
`name`	string	Customer display name.

Resolution priority: id > externalId > email > phone. When a new customer is created via email or phone, the provided externalId (if any) is also stored on the record.

On responses:

Field	Type	Description
`id`	CustomerId / null	Decal customer ID, if a customer record exists.
`externalId`	string/null	Your own customer identifier, if set on the customer record.
`email`	string/null	Customer email address.
`phone`	string/null	Customer phone number.
`name`	string/null	Customer display name.

Order Types

On this page