Skip to content
EvolveEvolveEvolve

orderBySignedLink

Queryin Order

Get order details from a signed order link, such as the one in an order confirmation email, for a buyer who may not be signed in. The token names the order and an expiry and is signed by the shop.

Null when the token is malformed, signed with another secret or expired, and on an engine or service that is not configured to sign order links.

Arguments

ArgumentTypeDescription
tokenString!

Returns

Order

FieldTypeDescription
idID!Unique identifier for the order
createdAtDateTime!Date and time when the order was created
createdByStringThe user or system that created the order
orderNumberString!Human-readable order number
purchaseOrderNumberStringPurchase-order / customer reference captured at checkout (B2B)
orderStatusOrderStatusTypeOrderStatusType contains a general status of the order. This is useful for categorizing orders in the UI.
paymentStateOrderPaymentStateTypeWhether 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.
payableBoolean!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.
requiredActionOrderRequiredActionWhat 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
customerEmailEmailAddressEmail address of the customer who placed the order
subTotalTaxedTotalPrice!Sum of all line items (i.e. price excluding all shipping and payment costs)
totalTaxedTotalPrice!Total price of the order including all costs
discountTotalTaxedPriceDiscount 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
selectedPaymentMethodPaymentMethodPayment method selected for the order
billingAddressAddressBilling address for the order
shippingAddressAddressShipping address for the order
shippingCostsTaxedPriceShipping costs for the order
deliveryRemarksStringNote for whoever delivers the goods, as the buyer typed it at checkout -- "please leave it under the shelter". Null where none was recorded.
vatNumberStringThe VAT number of the company the buyer ordered for, as recorded on the cart at checkout. Null where none was recorded.
isGuestBoolean!Indicates if the order was placed by a guest customer
vatShiftingMoneyThe 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.
vatExemptionMoneyThe 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.
vatOutcomeVatOutcomeWhich 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
deliverySlotDeliverySlotThe 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.
pickupPointPickupPointThe pickup point chosen in checkout, as it was when the order was placed. Null when the order is delivered or none was chosen.
approvalOrderApprovalApproval 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
openPaymentRedirectPaymentRedirectWhere 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
quoteQuoteThe 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 OrderBySignedLink($token: String!) {
  orderBySignedLink(token: $token) {
    id
    createdAt
    createdBy
    orderNumber
    purchaseOrderNumber
    orderStatus
    paymentState
    payable
    requiredAction {
      reason
      actor
    }
    deliveries {
      id
      createdAt
      status
      trackingId
      carrier
      trackingUrl
    }
    customerEmail
    subTotal {
      __typename
    }
    total {
      __typename
    }
    discountTotal {
      __typename
    }
    lineItems {
      id
      name
      quantity
    }
    selectedPaymentMethod {
      id
      internalId
      name
      provider
    }
    billingAddress {
      id
      name
      salutation
      givenName
      familyName
      streetAddress
      streetName
      streetNumber
      streetNumberSuffix
      additionalAddressInfo
      postalCode
      city
      country
      region
      phone
      email
      company
    }
    shippingAddress {
      id
      name
      salutation
      givenName
      familyName
      streetAddress
      streetName
      streetNumber
      streetNumberSuffix
      additionalAddressInfo
      postalCode
      city
      country
      region
      phone
      email
      company
    }
    shippingCosts {
      __typename
    }
    deliveryRemarks
    vatNumber
    isGuest
    vatOutcome {
      treatment
      reason
      incoterm
      eoriNumber
    }
    discountCodes {
      id
      code
    }
    deliverySlot {
      id
      deliveryDate
    }
    pickupPoint {
      id
      name
      type
      distanceInMeters
      alwaysOpen
      earliestPickupAt
    }
    approval {
      id
      version
      status
      pendingApproverRoleKeys
      viewerCanDecide
    }
    openPaymentRedirect {
      redirectUrl
    }
    lineReviews {
      reviewable
    }
    quote {
      quoteNumber
      createdAt
      status
      comment
      sellerComment
      purchaseOrderNumber
      validUntil
    }
    returnableLines {
      returnableQuantity
      requiresSerialNumber
      returnByDate
      exchangeable
    }
    returnRefundMethods
  }
}

The query selects the return type's fields two levels deep; pick the ones you need. The response shows its shape with placeholder values.

Served by

@evolve-framework/commercetoolsResolved
@evolve-framework/medusaResolved
@evolve-framework/sfccNot resolved

Used by

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