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 (cents for USD).

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	Order source: `native` for API-created orders, `square` or `clover` for POS.
`currency`	string	Currency code (e.g. `USD`).
`status`	string	`open`, `completed`, or `cancelled`.
`paymentStatus`	string	`unpaid`, `partially_paid`, `paid`, `overpaid`, `partially_refunded`, or `refunded`.
`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.

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`	string/null	Percentage rate as a string (e.g. `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). Must be 0–100.
`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	For `fixed` discounts: CurrencyAmount. For `percentage` discounts: the percentage value (e.g. `10`).
`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.