Crystallize logo

Managing orders

The Orders domain lets you read orders, create them, attach payments and customer details, and drive them through fulfilment using pipelines. Order creation is also the natural end of a checkout — that flow is introduced on the Checkout flow page. This page is the full reference for managing orders.

Endpoint

Replace tenant-identifier with your tenant identifier.

https://shop-api.crystallize.com/tenant-identifier/order

Access and scopes

The Order endpoint is authenticated. Reading and writing orders requires the order scope. Administrative operations require the order:admin scope.

Reading orders

Use order to fetch a single order by its id, and orders to list a customer's orders.

order

Returns one order by id (a UUID), or null if no order matches.

query {
  order(id: "ORDER_ID") {
    id
    reference
    type
    createdAt
    paymentStatus
    total { gross net currency }
    customer { identifier firstName lastName email }
    items { name sku quantity type }
    pipelines { identifier stage }
  }
}

orders

Lists the orders for a given customerIdentifier. Pagination is controlled with limit (default 10) and skip (default 0).

query {
  orders(customerIdentifier: "customer@example.com", limit: 10, skip: 0) {
    id
    reference
    createdAt
    paymentStatus
    total { gross currency }
  }
}

Creating orders

You can build an order directly with create, or convert an existing cart into an order with createFromCart. Both mutations return the created order.

create

Creates a new order from an input object. The input can carry items, customer, order type, payment status, payments, pipelines, a stock location, related order ids, additional information, and meta. Item prices are supplied as gross/net, and the order's price context controls rounding (decimals) and whether discounts apply to net or gross prices.

mutation {
  create(input: {
    type: standard
    customer: { isGuest: false, identifier: "customer@example.com" }
    items: [
      {
        name: "T-shirt"
        sku: "TS-001"
        quantity: 1
        price: { gross: 25.0, net: 20.0 }
      }
    ]
    context: { price: { decimals: 2, currency: "eur" } }
  }) {
    id
    reference
    total { gross net currency }
  }
}

createFromCart

Creates an order from an existing cart, identified by the cart's id. Line items, totals, and customer are taken from the cart. The optional input adds order-level details that are not part of the cart, such as order type, payment status, payments, pipelines, stock location, related order ids, and additional information.

mutation {
  createFromCart(id: "CART_ID", input: { type: standard }) {
    id
    reference
    total { gross currency }
  }
}

Order types

An order's type describes its nature. Available values:

standard, draft, creditNote, replacement, backorder, preOrder, quote, recurring, split, test

Item types

Each line item has a type that classifies what it represents:

standard, subscription, shipping, fee, promotion, refund, service, digital, bonus, tax

Items carry a name, sku, quantity, unit price and subtotal (each with tax details), an optional product id and image, and meta. Subscription items also expose their subscription contract id and subscription details, and tiered prices expose the resolved tier.

Payments

Each payment records a provider, transaction id, amount, method, creation time, and meta. Two mutations manage the payments on an order:

  • addPayments — appends one or more payments to the order's existing payments.
  • setPayments — replaces all payments on the order with the supplied list.
mutation {
  addPayments(
    id: "ORDER_ID"
    payments: [
      { provider: "stripe", transactionId: "txn_123", amount: 25.0, method: "card" }
    ]
  ) {
    id
    paymentStatus
    payments { provider amount method }
  }
}

Payment statuses

An order's paymentStatus can be one of:

  • paid — fully paid.
  • partiallyPaid — partially paid.
  • partiallyRefunded — partially refunded.
  • refunded — fully refunded.
  • unpaid — not paid.
note

Payment status is explicit

The order's paymentStatus is a value you set, not one derived automatically from the payments you attach. Set it when you create the order, or include it alongside your payment updates so it stays consistent with the amounts recorded.

setCustomer

Sets or updates the customer on an order, identified by id. The customer input accepts identity fields (name, email, phone), company and tax details, addresses, external references, and meta. Use it to attach a customer to a guest order or to correct customer details after creation.

mutation {
  setCustomer(
    id: "ORDER_ID"
    customer: {
      isGuest: false
      identifier: "customer@example.com"
      firstName: "Jane"
      lastName: "Doe"
    }
  ) {
    id
    customer { identifier firstName lastName }
  }
}

setMeta

Sets order-level metadata as a list of key/value pairs. By default merge is true, so the supplied keys are merged into existing meta. Set merge to false to replace the order's meta entirely.

mutation {
  setMeta(
    id: "ORDER_ID"
    meta: [{ key: "channel", value: "pos" }]
    merge: true
  ) {
    id
    meta
  }
}

Pipelines and stages

Pipelines drive an order through fulfilment. An order can sit in several pipelines and stages at once, and its current placements are exposed under pipelines (each entry has an identifier and a stage).

addToStage

Places the order in a stage of the given pipeline while keeping it in any stages it already belongs to.

mutation {
  addToStage(id: "ORDER_ID", pipeline: "fulfilment", stage: "packing") {
    id
    pipelines { identifier stage }
  }
}

removeFromPipeline

Removes the order from the given pipeline, clearing its placement in that pipeline's stages.

mutation {
  removeFromPipeline(id: "ORDER_ID", pipeline: "fulfilment") {
    id
    pipelines { identifier stage }
  }
}