orderByPublicId

Queryin Order

Get order details for anonymous/public viewing using a public ID. Used for order confirmation pages accessible without authentication. Whoever holds the public ID can read the order, for as long as it exists.

Arguments

Argument	Type	Description
`publicId`	`ID!`

Returns

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.

Example

Query
Response

query {
  orderByPublicId(publicId: "ae7fbbd3-9474-4be7-b321-2842a2294331") {
    id
    orderNumber
    orderStatus
    total {
      gross {
        centAmount
        currency
      }
    }
    lineItems {
      id
      quantity
      ... on OrderSingleLineItem {
        variant {
          sku
        }
      }
    }
    shippingAddress {
      givenName
      familyName
      city
    }
  }
}

{
  "data": {
    "orderByPublicId": {
      "id": "id-1",
      "orderNumber": "Example",
      "orderStatus": "OPEN",
      "total": {
        "gross": {
          "centAmount": 1,
          "currency": "EUR"
        }
      },
      "lineItems": [
        {
          "id": "id-1",
          "quantity": 1,
          "variant": {
            "sku": "SKU-1"
          }
        }
      ],
      "shippingAddress": {
        "givenName": "Example",
        "familyName": "Example",
        "city": "Example"
      }
    }
  }
}

The query is the example the schema documents. The response shows its shape with placeholder values.

Served by

@evolve-framework/commercetools	Resolved
@evolve-framework/medusa	Resolved
@evolve-framework/sfcc	Not resolved

Used by

The storefront packages that send it, in these GraphQL documents:

@evolve-storefront/feature-order: OrderPaymentMethodsByPublicId, OrderLookupByPublicId, OrderConfirmationById