Order types

The types the order domain defines, with the fields other domains add to them.

Objects

Order

Fields added by Delivery options, Order approval, Payment, Product review, Quote and Return

Complete order information including customer details, line items, and status

Field	Type	Description
id	ID!	Unique identifier for the order
createdAt	DateTime!	Date and time when the order was created
createdBy	String	The user or system that created the order
orderNumber	String!	Human-readable order number
purchaseOrderNumber	String	Purchase-order / customer reference captured at checkout (B2B)
orderStatus	OrderStatusType	OrderStatusType contains a general status of the order. This is useful for categorizing orders in the UI.
paymentState	OrderPaymentStateType	Whether the order has been paid, and if not, why not. Null where the engine reports no payment state for the order. An order created before its payment is taken is unpaid as a matter of course, not as an anomaly, so a storefront reads this to decide whether to offer paying for it.
payable	Boolean!	Whether a payment may be started for this order right now, answered against the caller making the request. A client cannot derive this. An order held by an approval flow is not payable, and the approval reads as absent both when none was ever needed and when the caller may not see the flow -- so a colleague entitled to pay an order without being party to its approval takes the second for the first, and is offered a payment the server then refuses. The engine knows which of the two it is; a client has no way to tell. The same rule the payment itself applies, so a true here is not contradicted by the next call. Ask for it where a buyer is deciding whether to pay something -- an order page, a resume page, a failed payment return. An engine may have to go and ask about each order to answer it, so selecting it on every row of an order history costs a round trip per row and tells the buyer nothing they are acting on there.
requiredAction	OrderRequiredAction	What has to happen before the order can move on, and who has to do it. Null when nothing is waiting on anybody. One reason is given, by precedence: a delayed, backordered or cancelled shipment (the seller) before a pending approval (an approver) before a failed payment (the buyer). A delayed order whose payment also failed therefore reads as waiting on the seller. An open order in a business unit costs one approval-flow lookup, the same one payable makes; other orders cost nothing extra. That is fine for a page of orders that need action, and wasteful on every row of a full order history.
deliveries	[OrderDelivery!]	Deliveries (shipments) for the order, with track & trace information
customerEmail	EmailAddress	Email address of the customer who placed the order
subTotal	TaxedTotalPrice!	Sum of all line items (i.e. price excluding all shipping and payment costs)
total	TaxedTotalPrice!	Total price of the order including all costs
discountTotal	TaxedPrice	Discount applied to the order total, on top of any discount already reflected in the line items. A positive magnitude: subtract it, never add it. Showing it as a negative amount is a presentation choice, not a property of the data. Taxed like the amounts it has to be arithmetic with, so a summary reconciles in one basis: subTotal minus this plus shippingCosts equals total. The rate is the effective rate over the discounted goods -- exact for a single-rate basket, a blend where the basket mixes rates.
lineItems	[OrderLineItem!]!	Line items in the order
selectedPaymentMethod	PaymentMethod	Payment method selected for the order
billingAddress	Address	Billing address for the order
shippingAddress	Address	Shipping address for the order
shippingCosts	TaxedPrice	Shipping costs for the order
deliveryRemarks	String	Note for whoever delivers the goods, as the buyer typed it at checkout -- "please leave it under the shelter". Null where none was recorded.
vatNumber	String	The VAT number of the company the buyer ordered for, as recorded on the cart at checkout. Null where none was recorded.
isGuest	Boolean!	Indicates if the order was placed by a guest customer
vatShifting	Money	The amount of a reverse-charge line, negative and already reflected in total, where one is carried. A reverse-charged cart is taxed at 0% and gets no such line, so this is null on an order of one.Deprecated: A reverse-charged cart is taxed at 0%; read vatOutcome and the taxed totals.
vatExemption	Money	The amount of an export line, negative and already reflected in total, where one is carried. An exported cart is taxed at 0% and gets no such line, so this is null on an order of one.Deprecated: An exported cart is taxed at 0%; read vatOutcome and the taxed totals.
vatOutcome	VatOutcome	Which VAT rule the order's amounts follow, and why, as the cart it came from recorded it; the same as Cart.vatOutcome. Tells a reverse-charged or exported order from one taxed at 0%. Null where none was recorded and where the engine does not decide VAT itself.
discountCodes	[OrderDiscountCode!]!	Discount codes that were applied to the cart
deliverySlot	DeliverySlot	The delivery slot chosen in checkout, as it was when the order was placed. Null when the order is collected from a pickup point or none was chosen.
pickupPoint	PickupPoint	The pickup point chosen in checkout, as it was when the order was placed. Null when the order is delivered or none was chosen.
approval	OrderApproval	Approval flow for this order, so its status can be shown wherever the order appears rather than by searching the queue and joining back. Null where the order needed no approval, and null where the caller may not see the flow -- visibility follows the caller's associate permissions, which commercetools decides.
availablePaymentMethods	[PaymentMethod!]!	Available payment methods for the order. Country is required to determine the available payment methodsArguments: device
openPaymentRedirect	PaymentRedirect	Where the shopper can complete a payment still in progress on this order, at the provider that started it. Null when no payment is in progress, or when its provider has no page to return to, in which case the order is paid with a new payment once it is payable again. Asked of the provider on every read, so it can cost a request to it: query it where a shopper is about to continue, not in a listing.
lineReviews	[OrderLineReview!]!	One entry per line of the order, for writing a review from it
quote	Quote	The quote this order was placed against, where it came from one. Null for an order placed from a cart, which is most of them.
returnableLines	[ReturnableLine!]!	Lines that can still be returned; empty when nothing was delivered or all went back
returnRefundMethods	[ReturnRefundMethodType!]!	How a consumer's return of this order may be refunded; a refundMethod outside it is refused. Empty for a business unit's order, which is settled by credit note instead.

OrderDelivery

A delivery (shipment) of an order with track & trace information. Modelled as a flat shipment (one tracking identifier) so it maps onto both commercetools parcels and SAP/Emporix consignments.

Field	Type	Description
id	ID!	Unique identifier of the delivery / shipment
createdAt	DateTime!	Date and time the delivery was created
status	OrderDeliveryStatusType!	Current status of the delivery
trackingId	String	Tracking identifier used to follow the shipment with the carrier
carrier	String	Name of the carrier delivering the shipment
trackingUrl	URL	Direct track & trace URL, when available
items	[OrderDeliveryItem!]!	What went in this delivery. Summed across an order's deliveries it says how much of each line item has been dispatched, and so what is still to come.

OrderDeliveryItem

How much of one line item a delivery holds

Field	Type	Description
lineItem	OrderLineItem!	The line item, as the order's lineItems lists it
quantity	Int!	How many of the line item went in this delivery, which can be fewer than the line item's own quantity

OrderDiscountCode

An OrderDiscountCode represents a discount that was applied to the order. These are identified by their discount code.

Field	Type	Description
id	ID!	Unique identifier for the discount code
code	String!	The discount code string used
amount	Money!	The discount amount applied

OrderRequiredAction

Why an order is waiting, and who it is waiting on.

Field	Type	Description
reason	OrderActionReasonType!	What the order is waiting on
actor	OrderActorType!	Who has to act for the order to move on

OrderResult

Paginated result containing orders and metadata

Field	Type	Description
items	[Order!]!	List of orders returned in the result
pagination	Pagination!	Where this page sits within the full result set
statusCounts	[OrderStatusCount!]	How many orders each status holds under this list's search term and date range, whatever its status filter, so every status tab can show a count. Asked of the engine once per status, so query it where the tabs are shown. Null when the engine cannot count per status.

OrderStatusCount

The number of orders in one status

Field	Type	Description
status	OrderStatusType!
count	Int!

Enums

OrderActionReasonType

Why an order cannot move on by itself.

APPROVAL_PENDING	An approver of the business unit has yet to decide on the order
PAYMENT_FAILED	The last payment attempt failed, and the buyer can pay again
DELIVERY_DELAYED	The delivery is late
BACKORDERED	Part of the order is on backorder
SHIPMENT_CANCELLED	The shipment was cancelled while the order stands

OrderActorType

Who an order is waiting on.

BUYER	The buyer, or a colleague who may pay for the order
APPROVER	An associate who may approve orders for the business unit
SELLER	The merchant

OrderDeliveryStatusType

Normalized, engine-agnostic status of a delivery

OPEN	Created but not yet dispatched
SHIPPED	Dispatched / in transit
DELIVERED	Delivered to the customer
PICKED_UP	Ready for / collected at pickup
CANCELLED	Cancelled

OrderPaymentStateType

Whether an order has been paid for, and if not, why not. Separate from OrderStatusType because the two answer to different people and move independently: an order can be accepted and still owe money, and it can be paid in full and not yet accepted. One field cannot say both.

Money arriving therefore does not advance the order status. Whether an order has been accepted is answered by whatever runs the merchant's operation, and until it says so a paid order reads as OPEN.

BALANCE_DUE	Nothing has been paid yet, or an amount is still outstanding
PARTIALLY_PAID	Part of the amount has been paid and a balance remains
PENDING	A payment has been started and is awaiting confirmation
FAILED	A payment attempt failed. Reads differently to a buyer than never having paid
PAID	The order has been paid in full
CREDIT_OWED	Settled on credit rather than with money: the order is through checkout and billed, and the buyer pays afterwards. Unlike BALANCE_DUE, nothing is waiting on the buyer before the order can be fulfilled.

OrderStatusType

OPEN	Order is open and active
CANCELLED	Order has been cancelled
DELIVERED	Order has been delivered to the customer
IN_TRANSIT	Order is currently in transit
PICKUP_AVAILABLE	Order is available for pickup
PROBLEM	There is a problem with the order
PROCESSING	Order is currently being processed
RETURNED	Order has been returned