Create an order, take a PIN payment and invoice items#

This guide walks through creating an order, executing a PIN terminal payment, and generating an invoice for the order items.

Overview#

Create an order with createOrder
Add items to the order with addItemsToOrder
Attach a PIN payment method with addPaymentMethodToOrder
Execute the payment on the terminal with executePayment
Fetch the order's inventory item IDs with the items query
Invoice the items with invoiceItems and retrieve the invoice

Step 1 — Create an order#

Input: CreateOrderInput!

Name	Type	Required	Description
`channel_id`	String	Optional	The channel (storefront) to create the order in.

Returns: Order

Name	Type	Required	Description
`id`	ID!	Required	The ID
`number`	String!	Required	Order number
`total`	Money!	Required	Total value
`currency`	Currency!	Required	Currency code

mutation CreateOrder($input: CreateOrderInput!) {
  createOrder(input: $input) {
    order {
      id
      number
      status
      currency
    }
  }
}

{
  "input": {
    "channel_id": "3c7d1e5f-9a2b-4f8e-b6d0-1234abcd5678"
  }
}

Save the returned order.id — you'll use it in every subsequent step.

Step 2 — Add items#

Input: AddItemsToOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The order to add items to.
`items`	[OrderItemInput!]!▾	Required	Items to add.

Returns: Order

Name	Type	Required	Description
`id`	ID!	Required	The ID
`number`	String!	Required	Order number
`total`	Money!	Required	Total value
`currency`	Currency!	Required	Currency code

mutation AddItems($input: AddItemsToOrderInput!) {
  addItemsToOrder(input: $input) {
    order {
      id
      items {
        sku
        label
        quantity
        total
      }
      total
    }
  }
}

{
  "input": {
    "order_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "items": [
      { "sku": "BLK-HOODIE-M", "quantity": 1 },
      { "sku": "BLK-HOODIE-L", "quantity": 2 }
    ]
  }
}

Step 3 — Add a PIN payment method#

Use addPaymentMethodToOrder to register a PIN payment. Pass the terminal_id of the physical payment terminal to route the transaction to the correct device.

Input: AddPaymentMethodToOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The order ID.
`method_id`	String!	Required	The payment method ID (use `paymentMethods` query to list available methods).
`issuer_id`	String!	Required	The payment issuer ID.
`terminal_id`	String	Optional	The PIN terminal ID. Required for in-person PIN payments.
`drawer_id`	String	Optional	The cash drawer ID (for cash payments).

Returns: Order

Name	Type	Required	Description
`id`	ID!	Required	The ID
`number`	String!	Required	Order number
`total`	Money!	Required	Total value
`currency`	Currency!	Required	Currency code

mutation AddPaymentMethod($input: AddPaymentMethodToOrderInput!) {
  addPaymentMethodToOrder(input: $input) {
    order {
      id
      payments {
        details {
          id
          status
          amount
        }
      }
    }
  }
}

{
  "input": {
    "order_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "method_id": "e5f6a7b8-c9d0-1234-5678-90abcdef0123",
    "issuer_id": "f6a7b8c9-d0e1-2345-6789-0abcdef01234",
    "terminal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

ℹ

Tip:Save the payments[0].details.id from the response — this is the payment_id needed in step 4.

Step 4 — Execute the payment#

Send the payment to the terminal with executePayment. The terminal will prompt the customer to tap or insert their card.

Input: ExecutePaymentInput!

Name	Type	Required	Description
`payment_id`	String!	Required	The payment ID from `addPaymentMethodToOrder` (i.e. `order.payments[0].details.id`).

Returns: ExecutePaymentPayload

Name	Type	Required	Description
`payment`	Payment▾	Optional	The executed payment

mutation ExecutePayment($input: ExecutePaymentInput!) {
  executePayment(input: $input) {
    payment {
      id
      status
      amount
      is_paid
    }
  }
}

{
  "input": {
    "payment_id": "d4e5f6a7-b8c9-0123-4567-890abcdef012"
  }
}

Note:For PIN payments, payment.status transitions to PAID once the terminal confirms the transaction. Poll the order query or listen for a webhook event to detect completion.

Step 5 — Fetch inventory item IDs#

To invoice the items, you need the CollectionItem IDs for the order. Query the items endpoint filtered by order_id:

query GetOrderItems($filters: CollectionItemFilterInput!) {
  items(filters: $filters) {
    id
    sku
    label
    is_allocated
  }
}

{
  "filters": {
    "order_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a"
  }
}

Step 6 — Invoice the items#

Use invoiceItems to generate an invoice for all or a subset of items. Pass the CollectionItem IDs from step 5.

Input: InvoiceItemsInput!

Name	Type	Required	Description
`items`	[String!]!	Required	CollectionItem IDs to include on the invoice.
`invoice_id`	String	Optional	Existing invoice ID to add the items to. Omit to create a new invoice.

Returns: InvoiceItemsPayload

Name	Type	Required	Description
`invoice`	Invoice▾	Optional	The created invoice

mutation InvoiceItems($input: InvoiceItemsInput!) {
  invoiceItems(input: $input) {
    invoice {
      id
      number
      total
      currency
      pdf_url
      created_at
    }
  }
}

{
  "input": {
    "items": [
      "5a6b7c8d-9e0f-1234-5678-9abcdef01234",
      "6b7c8d9e-0f1a-2345-6789-0abcdef12345"
    ]
  }
}

The response includes pdf_url — a direct link to download the invoice PDF.

Notes#

Money values (total, amount) are integers in cents — e.g. 4998 = € 49,98.
Use the paymentMethods query to find valid method_id and issuer_id values for your channel.
You can invoice a subset of items by passing only some IDs — useful for partial fulfilment.
To retrieve the invoice later, use the invoice(id: ...) query with the invoice ID from the response.
See Authentication for how to pass your API key.