Mutations#

Mutations are write operations — use them to create, update, or delete resources. All mutations follow the same structure: a single input argument wraps all mutation fields, and the payload returns the affected resource.

mutation MutationName($input: MutationNameInput!) {
  mutationName(input: $input) {
    # fields to return
  }
}

Cart#

createCart#

Create a new empty cart.

No input required.

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

Example#

mutation {
  createCart {
    cart {
      id
      number
      currency
      total {
        amount
        currency
        formatted
      }
    }
  }
}

addItemsToCart#

Add one or more items to a cart by SKU.

Input: AddItemsToCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart
`items`	[ItemInput!]!▾	Required	Items to add

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

Example#

mutation AddItemsToCart($input: AddItemsToCartInput!) {
  addItemsToCart(input: $input) {
    cart {
      id
      items {
        sku
        label
        quantity
        total
      }
      total
    }
  }
}

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

removeItemsFromCart#

Remove one or more items from a cart.

Input: RemoveItemFromCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart
`ids`	[String!]!	Required	IDs of cart items to remove

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

Example#

mutation RemoveItemsFromCart($input: RemoveItemFromCartInput!) {
  removeItemsFromCart(input: $input) {
    cart {
      id
      items {
        sku
        quantity
      }
      total
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "ids": ["5a6b7c8d-9e0f-1234-5678-9abcdef01234"]
  }
}

setItemQuantityForCart#

Update the quantity of a specific item in the cart.

Input: SetItemQuantityForCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart
`sku`	String!	Required	SKU of the cart item to update
`quantity`	Int!	Required	New quantity

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

Example#

mutation SetItemQuantity($input: SetItemQuantityForCartInput!) {
  setItemQuantityForCart(input: $input) {
    cart {
      id
      items {
        sku
        quantity
        total
      }
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "sku": "BLK-HOODIE-M",
    "quantity": 3
  }
}

addCustomerToCart#

Attach a customer (contact) to a cart.

Input: AddCustomerToCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart
`contact_id`	String!	Required	The ID of the contact

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

Example#

mutation AddCustomerToCart($input: AddCustomerToCartInput!) {
  addCustomerToCart(input: $input) {
    cart {
      id
      customer {
        contact {
          email
          given_name
          family_name
        }
      }
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

addBillingAddressToCart#

Attach a billing address to a cart.

Input: AddBillingAddressToCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart
`address`	AddressInput!▾	Required	The billing address

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

Example#

mutation AddBillingAddress($input: AddBillingAddressToCartInput!) {
  addBillingAddressToCart(input: $input) {
    cart {
      id
      billing {
        address {
          address_line_1
          locality
          postal_code
          country_code
        }
      }
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "address": {
      "address_line_1": "Keizersgracht 313",
      "locality": "Amsterdam",
      "postal_code": "1016 EE",
      "country_code": "NL"
    }
  }
}

addShippingAddressToCart#

Attach a shipping address to a cart. Uses the same AddressInput shape as addBillingAddressToCart.

Input: AddShippingAddressToCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart
`address`	AddressInput!▾	Required	The shipping address

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

Example#

mutation AddShippingAddress($input: AddShippingAddressToCartInput!) {
  addShippingAddressToCart(input: $input) {
    cart {
      id
      delivery {
        address {
          address_line_1
          locality
          country_code
        }
      }
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "address": {
      "address_line_1": "Herengracht 401",
      "locality": "Amsterdam",
      "postal_code": "1017 BP",
      "country_code": "NL"
    }
  }
}

addShippingMethodToCart#

Select a shipping method for the cart. Available shipping methods can be fetched from cart.options.shipping_methods.

Input: AddShippingMethodToCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart
`method_id`	String!	Required	The ID of the shipping method

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

Example#

mutation AddShippingMethod($input: AddShippingMethodToCartInput!) {
  addShippingMethodToCart(input: $input) {
    cart {
      id
      delivery {
        method {
          id
          name
        }
      }
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "method_id": "e1f2a3b4-c5d6-7890-abcd-ef0123456789"
  }
}

addPaymentMethodToCart#

Select a payment method for the cart. Available payment methods can be fetched from cart.options.payment_methods.

Input: AddPaymentMethodToCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart
`method_id`	String!	Required	The ID of the payment method
`issuer_id`	String!	Required	The ID of the issuer (bank/scheme) for the payment method
`terminal_id`	String	Optional	Optional terminal ID (for PIN payments)
`drawer_id`	String	Optional	Optional cash-drawer ID

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

Example#

mutation AddPaymentMethod($input: AddPaymentMethodToCartInput!) {
  addPaymentMethodToCart(input: $input) {
    cart {
      id
      checkout {
        url
      }
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "method_id": "e5f6a7b8-c9d0-1234-5678-90abcdef0123",
    "issuer_id": "3a4b5c6d-7e8f-9012-3456-7890abcdef12"
  }
}

addCouponToCart#

Apply a coupon code to the cart.

Input: CouponInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart
`coupon`	String!	Required	The coupon code

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

Example#

mutation AddCoupon($input: CouponInput!) {
  addCouponToCart(input: $input) {
    cart {
      id
      coupons {
        code
      }
      total
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "coupon": "SUMMER25"
  }
}

removeCouponFromCart#

Remove an applied coupon from the cart.

Input: CouponInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart
`coupon`	String!	Required	The coupon code to remove

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

Example#

mutation RemoveCoupon($input: CouponInput!) {
  removeCouponFromCart(input: $input) {
    cart {
      id
      coupons {
        code
      }
      total
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "coupon": "SUMMER25"
  }
}

setNoteForCart#

Add a customer note to the cart.

Input: SetNoteForCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart
`note`	String!	Required	The note text

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

Example#

mutation SetNote($input: SetNoteForCartInput!) {
  setNoteForCart(input: $input) {
    cart {
      id
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "note": "Please deliver between 9-12"
  }
}

setReferenceForCart#

Set an external reference on the cart (e.g. your own order reference).

Input: SetReferenceForCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart
`reference`	String!	Required	The reference string

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

Example#

mutation SetReference($input: SetReferenceForCartInput!) {
  setReferenceForCart(input: $input) {
    cart {
      id
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "reference": "PO-2024-0042"
  }
}

confirmCart#

Confirm a cart and convert it to an order. The cart must have no validation_errors.

Input: ConfirmCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart to confirm

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

Example#

mutation ConfirmCart($input: ConfirmCartInput!) {
  confirmCart(input: $input) {
    order {
      id
      number
      total
      checkout {
        url
      }
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a"
  }
}

addPhoneNumberToCart#

Add a phone number to a cart.

Input: AddPhoneNumberToCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart
`phone_number`	PhoneNumberInput!▾	Required	Phone number details

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

Example#

mutation AddPhone($input: AddPhoneNumberToCartInput!) {
  addPhoneNumberToCart(input: $input) {
    cart {
      id
      phone_number {
        country_code
        national
        number
      }
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "phone_number": {
      "country_code": "NL",
      "national": "612345678"
    }
  }
}

addPickUpPointToCart#

Set a pickup point for cart delivery.

Input: AddPickUpPointToCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart
`spid`	String!	Required	Service-point ID of the pickup point (provider-issued)

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

Example#

mutation AddPickUp($input: AddPickUpPointToCartInput!) {
  addPickUpPointToCart(input: $input) {
    cart {
      id
      delivery {
        address {
          address_line_1
          locality
        }
      }
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "spid": "f6a7b8c9-d0e1-2345-6789-0abcdef12345"
  }
}

removeCustomerFromCart#

Remove the customer from a cart.

Input: RemoveCustomerFromCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

Example#

mutation RemoveCustomer($input: RemoveCustomerFromCartInput!) {
  removeCustomerFromCart(input: $input) {
    cart {
      id
      customer {
        contact {
          email
        }
      }
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a"
  }
}

setCountryCodeForCart#

Set the country code for the cart (affects VAT/tax calculations).

Input: SetCountryCodeForCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart
`country_code`	String!	Required	ISO country code (e.g. NL, DE, US)

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

Example#

mutation SetCountry($input: SetCountryCodeForCartInput!) {
  setCountryCodeForCart(input: $input) {
    cart {
      id
      total
      currency
      vat {
        percentage
        amount
      }
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "country_code": "NL"
  }
}

setCountryCodeOnCart#

Set the destination country code on a cart. The country is used when calculating prices, VAT and shipping for the cart.

Input: SetCountryCodeOnCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart
`country_code`	String!	Required	ISO 3166-1 alpha-2 country code (e.g. NL, DE)

Returns: SetCountryCodeForCartPayload!

Name	Type	Required	Description
`cart`	Cart▾	Optional	The updated cart

Example#

mutation SetCountryCodeOnCart($input: SetCountryCodeOnCartInput!) {
  setCountryCodeOnCart(input: $input) {
    cart {
      id
      number
      total {
        amount
        formatted
      }
      is_including_vat
      updated_at
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "country_code": "DE"
  }
}

setDutiesForCart#

Set the import duties on a cart, for example when shipping cross-border. The duties are reflected in the cart totals.

Input: SetDutiesForCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart
`duties`	Money!▾	Required	The duties to charge — pass the amount in cents

Returns: SetDutiesForCartPayload!

Name	Type	Required	Description
`cart`	Cart▾	Optional	The updated cart

Example#

mutation SetDutiesForCart($input: SetDutiesForCartInput!) {
  setDutiesForCart(input: $input) {
    cart {
      id
      number
      total {
        amount
        formatted
      }
      updated_at
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "duties": 1250
  }
}

setExpectedAtForCartItems#

Set the expected delivery date for specific cart items, for example when an item is backordered and will only become available at a known future date.

Input: SetExpectedAtForCartItemsInput!

Name	Type	Required	Description
`expected_at`	Int64!	Required	Expected delivery date — Unix timestamp in milliseconds
`items`	[String]!	Required	IDs of the cart items to update

Returns: SetExpectedAtForCartItemsPayload!

Name	Type	Required	Description
`items`	[CollectionItem]!▾	Required	The updated cart items

Example#

mutation SetExpectedAtForCartItems($input: SetExpectedAtForCartItemsInput!) {
  setExpectedAtForCartItems(input: $input) {
    items {
      id
      sku
      label
      is_expected
      status
      updated_at
    }
  }
}

{
  "input": {
    "expected_at": 1767225600000,
    "items": ["itm_7hRp2W", "itm_9kTn4B"]
  }
}

Order#

createOrder#

Create a new order.

Input: CreateOrderInput!

Name	Type	Required	Description
`channel_id`	String	Optional	The channel ID to create the order in
`currency`	Currency	Optional	ISO 4217 currency code (e.g. EUR)
`country_code`	String	Optional	ISO country code (e.g. NL)
`customer`	CustomerInput	Optional	Inline customer details
`phone_number`	PhoneNumberInput	Optional	Phone number on the order
`phone_number_id`	String	Optional	Existing phone-number ID
`delivery`	CreateOrderDeliveryInput	Optional	Initial delivery address/method
`billing`	CreateOrderBillingInput	Optional	Initial billing address
`meta_data`	JsonObject	Optional	Free-form metadata
`ordered_at`	Int64	Optional	Unix-ms timestamp when the order was placed (defaults to now)

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

Example#

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

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

addItemsToOrder#

Add items to an existing order.

Input: AddItemsToOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The order ID
`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

Example#

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

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

addCustomerToOrder#

Assign a customer to an order.

Input: AddCustomerToOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The order ID
`customer`	AttachCustomerInput!▾	Required	Reference to the customer to attach

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

Example#

mutation AddCustomer($input: AddCustomerToOrderInput!) {
  addCustomerToOrder(input: $input) {
    order {
      id
      customer {
        contact {
          email
          given_name
          family_name
        }
      }
    }
  }
}

{
  "input": {
    "order_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "customer": {
      "contact_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a"
    }
  }
}

addBillingAddressToOrder#

Set billing address on an order.

Input: AddBillingAddressToOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The order ID
`address_id`	String	Optional	ID of an existing address (use this OR `address`)
`address`	AddressInput▾	Optional	Inline billing address (use this OR `address_id`)

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

Example#

mutation AddBilling($input: AddBillingAddressToOrderInput!) {
  addBillingAddressToOrder(input: $input) {
    order {
      id
      billing {
        address {
          address_line_1
          locality
          postal_code
          country_code
        }
      }
    }
  }
}

{
  "input": {
    "order_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "address": {
      "address_line_1": "Keizersgracht 313",
      "locality": "Amsterdam",
      "postal_code": "1016 EE",
      "country_code": "NL"
    }
  }
}

addShippingAddressToOrder#

Set shipping address on an order.

Input: AddShippingAddressToOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The order ID
`type`	AddressType!▾	Required	Address kind
`address_id`	String	Optional	ID of an existing address (use this OR `address`)
`address`	AddressInput▾	Optional	Inline shipping address (use this OR `address_id`)

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

Example#

mutation AddShipping($input: AddShippingAddressToOrderInput!) {
  addShippingAddressToOrder(input: $input) {
    order {
      id
      delivery {
        address {
          address_line_1
          locality
          postal_code
          country_code
        }
      }
    }
  }
}

{
  "input": {
    "order_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "type": "ADDRESS",
    "address": {
      "address_line_1": "Herengracht 401",
      "locality": "Amsterdam",
      "postal_code": "1017 BP",
      "country_code": "NL"
    }
  }
}

cancelOrderItems#

Cancel items on an order.

Input: CancelOrderItemsInput!

Name	Type	Required	Description
`item_ids`	[String!]!	Required	IDs of the items to cancel

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

Example#

mutation Cancel($input: CancelOrderItemsInput!) {
  cancelOrderItems(input: $input) {
    order {
      id
      items {
        id
        is_cancelled
      }
    }
  }
}

{
  "input": {
    "item_ids": ["5a6b7c8d-9e0f-1234-5678-9abcdef01234"]
  }
}

addAdjustmentsToOrder#

Add one or more adjustments — fixed or percentage-based surcharges or discounts — to an order. Adjustments apply to the order as a whole and are reflected in the order totals.

Input: AddAdjustmentsToOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`adjustments`	[AdjustmentInput]!▾	Required	The adjustments to add to the order

Returns: AddAdjustmentsToOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation AddAdjustmentsToOrder($input: AddAdjustmentsToOrderInput!) {
  addAdjustmentsToOrder(input: $input) {
    order {
      id
      number
      subtotal {
        amount
        formatted
      }
      total {
        amount
        formatted
      }
      adjustments {
        id
        description
        amount
        is_percentage
        is_discount
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "adjustments": [
      {
        "description": "Loyalty discount",
        "is_percentage": true,
        "is_discount": true,
        "amount": 10
      }
    ]
  }
}

addContraFeesToOrder#

Add contra fees to an order — offsetting fee lines that counter an existing fee (for example to compensate a shipping or payment fee). Each contra fee references the fee it offsets via contra_fee_id.

Input: AddContraFeesToOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`fees`	[ContraFeeInput]!▾	Required	The contra fees to add to the order

Returns: AddContraFeesToOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation AddContraFeesToOrder($input: AddContraFeesToOrderInput!) {
  addContraFeesToOrder(input: $input) {
    order {
      id
      number
      total {
        amount
        formatted
      }
      fees {
        shipping {
          id
          description
          is_contra
          total {
            amount
            formatted
          }
        }
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "fees": [
      {
        "description": "Shipping fee waived",
        "type": "SHIPPING_FEE",
        "amount": 495,
        "contra_fee_id": "fee_3JvB6n"
      }
    ]
  }
}

addCouponToOrder#

Apply a coupon code to an order. The coupon's discount is reflected in the order totals.

Input: AddCouponToOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`coupon`	String!	Required	The coupon code to apply

Returns: AddCouponToOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation AddCouponToOrder($input: AddCouponToOrderInput!) {
  addCouponToOrder(input: $input) {
    order {
      id
      number
      coupons {
        code
        is_valid
      }
      total {
        amount
        formatted
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "coupon": "SUMMER10"
  }
}

addFeesToOrder#

Add one or more fees — payment, handling or shipping — to an order. The fee amounts are reflected in the order totals.

Input: AddFeesToOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`fees`	[FeeInput]!▾	Required	The fees to add to the order

Returns: AddFeesToOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation AddFeesToOrder($input: AddFeesToOrderInput!) {
  addFeesToOrder(input: $input) {
    order {
      id
      number
      total {
        amount
        formatted
      }
      fees {
        payment {
          id
          description
          total {
            amount
            formatted
          }
        }
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "fees": [
      {
        "description": "Payment provider surcharge",
        "type": "PAYMENT_FEE",
        "amount": 195
      }
    ]
  }
}

addPaymentMethodToOrder#

Add a payment method (with its issuer) to an order, creating a payment that can subsequently be executed. For point-of-sale payments, a terminal or cash drawer can be specified.

Input: AddPaymentMethodToOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`issuer_id`	String!	Required	The ID of the payment issuer (e.g. a specific bank or card scheme)
`method_id`	String!	Required	The ID of the payment method
`terminal_id`	String	Optional	The ID of the POS terminal to process the payment on
`drawer_id`	String	Optional	The ID of the POS cash drawer for cash payments

Returns: AddPaymentMethodToOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation AddPaymentMethodToOrder($input: AddPaymentMethodToOrderInput!) {
  addPaymentMethodToOrder(input: $input) {
    order {
      id
      number
      total {
        amount
        formatted
      }
      payments {
        id
        type
        amount {
          amount
          formatted
        }
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "issuer_id": "iss_1RbD5h",
    "method_id": "mtd_8FsJ2c"
  }
}

addPhoneNumberToOrder#

Add a phone number to an order — for example for delivery notifications — either by referencing an existing phone number by ID or by supplying a new one.

Input: AddPhoneNumberToOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`phone_number_id`	String	Optional	The ID of an existing phone number to attach
`phone_number`	PhoneNumberInput▾	Optional	A new phone number to attach — used when no `phone_number_id` is given

Returns: AddPhoneNumberToOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation AddPhoneNumberToOrder($input: AddPhoneNumberToOrderInput!) {
  addPhoneNumberToOrder(input: $input) {
    order {
      id
      number
      phone_number {
        id
        country_code
        number
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "phone_number": {
      "country_code": "NL",
      "number": "+31612345678"
    }
  }
}

addPickUpPointToOrder#

Set a carrier pick-up point (service point) as the delivery location for an entire order, identified by its service point ID.

Input: AddPickUpPointToOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`spid`	String!	Required	The service point ID of the pick-up point (as returned by the shipping method's pickup points)

Returns: AddPickUpPointToOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation AddPickUpPointToOrder($input: AddPickUpPointToOrderInput!) {
  addPickUpPointToOrder(input: $input) {
    order {
      id
      number
      status
      shipping {
        pickup_point {
          id
          name
          carrier
        }
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "spid": "8004-NL-100310"
  }
}

addShippingMethodToOrder#

Assign a shipping method to an order. The method applies to the order's delivery and is reflected in the order's shipping details.

Input: AddShippingMethodToOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`method_id`	String!	Required	The ID of the shipping method to apply

Returns: AddShippingMethodToOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation AddShippingMethodToOrder($input: AddShippingMethodToOrderInput!) {
  addShippingMethodToOrder(input: $input) {
    order {
      id
      number
      status
      shipping {
        method {
          id
          name
          carrier
        }
        expected_at
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "method_id": "shm_3DcF6a"
  }
}

openOrder#

Reopen an order, setting its state back to open so it can be modified again.

Input: OpenOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order to open

Returns: OpenOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The opened order

Example#

mutation OpenOrder($input: OpenOrderInput!) {
  openOrder(input: $input) {
    order {
      id
      number
      status
      is_cancelled
      total {
        amount
        formatted
      }
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ"
  }
}

recalculateOrderPrices#

Recalculate the prices and totals of an order, for example after price list or item changes, so its totals reflect the current pricing.

Input: RecalculateOrderPricesInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order to recalculate

Returns: RecalculateOrderPricesPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The order with recalculated prices

Example#

mutation RecalculateOrderPrices($input: RecalculateOrderPricesInput!) {
  recalculateOrderPrices(input: $input) {
    order {
      id
      number
      subtotal {
        amount
        formatted
      }
      total {
        amount
        formatted
      }
      total_excluding_vat {
        amount
        formatted
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ"
  }
}

removeAdjustmentsFromOrder#

Remove one or more adjustments — surcharges or discounts — from an order by their IDs. The order totals are updated accordingly.

Input: RemoveAdjustmentsFromOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`adjustment_ids`	[String]!	Required	The IDs of the adjustments to remove

Returns: RemoveAdjustmentsFromOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation RemoveAdjustmentsFromOrder($input: RemoveAdjustmentsFromOrderInput!) {
  removeAdjustmentsFromOrder(input: $input) {
    order {
      id
      number
      subtotal {
        amount
        formatted
      }
      total {
        amount
        formatted
      }
      adjustments {
        id
        description
        amount
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "adjustment_ids": ["adj_6Yc3wHt"]
  }
}

removeBillingAddressFromOrder#

Remove the billing address from an order.

Input: RemoveBillingAddressFromOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order

Returns: RemoveBillingAddressFromOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation RemoveBillingAddressFromOrder($input: RemoveBillingAddressFromOrderInput!) {
  removeBillingAddressFromOrder(input: $input) {
    order {
      id
      number
      billing {
        address {
          address_line_1
          locality
        }
      }
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ"
  }
}

removeCouponFromOrder#

Remove a previously applied coupon code from an order. The coupon's discount is taken out of the order totals.

Input: RemoveCouponFromOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`coupon`	String!	Required	The coupon code to remove

Returns: RemoveCouponFromOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation RemoveCouponFromOrder($input: RemoveCouponFromOrderInput!) {
  removeCouponFromOrder(input: $input) {
    order {
      id
      number
      coupons {
        code
        is_valid
      }
      total {
        amount
        formatted
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "coupon": "SUMMER10"
  }
}

removeCustomerFromOrder#

Detach the customer from an order, leaving the order without an associated customer.

Input: RemoveCustomerFromOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order

Returns: RemoveCustomerFromOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation RemoveCustomerFromOrder($input: RemoveCustomerFromOrderInput!) {
  removeCustomerFromOrder(input: $input) {
    order {
      id
      number
      customer {
        contact {
          id
        }
      }
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ"
  }
}

removeItemsFromOrder#

Remove items from an order by their item IDs. The order totals are recalculated and the updated order is returned.

Input: RemoveItemsFromOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order to remove the items from
`ids`	[String]!	Required	IDs of the order items to remove

Returns: RemoveItemsFromOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation RemoveItemsFromOrder($input: RemoveItemsFromOrderInput!) {
  removeItemsFromOrder(input: $input) {
    order {
      id
      number
      items {
        id
        sku
        quantity
      }
      total {
        amount
        formatted
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "ids": ["itm_7GhQ2w", "itm_9KpR4t"]
  }
}

removePhoneNumberFromOrder#

Remove the phone number from an order. Returns the updated order.

Input: RemovePhoneNumberFromOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order to remove the phone number from

Returns: RemovePhoneNumberFromOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation RemovePhoneNumberFromOrder($input: RemovePhoneNumberFromOrderInput!) {
  removePhoneNumberFromOrder(input: $input) {
    order {
      id
      number
      phone_number {
        country_code
        number
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ"
  }
}

setCountryCodeForOrder#

Set the destination country code on an order. The country is used when calculating prices, VAT and shipping for the order.

Input: SetCountryCodeForOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`country_code`	String!	Required	ISO 3166-1 alpha-2 country code (e.g. NL, DE)

Returns: SetCountryCodeForOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation SetCountryCodeForOrder($input: SetCountryCodeForOrderInput!) {
  setCountryCodeForOrder(input: $input) {
    order {
      id
      number
      total {
        amount
        formatted
      }
      is_including_vat
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "country_code": "NL"
  }
}

setCountryCodeOnOrder#

Set the destination country code on an order, used when calculating prices, VAT and shipping. Takes the same input as setCountryCodeForOrder and returns the same payload.

Input: SetCountryCodeOnOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`country_code`	String!	Required	ISO 3166-1 alpha-2 country code (e.g. NL, DE)

Returns: SetCountryCodeForOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation SetCountryCodeOnOrder($input: SetCountryCodeOnOrderInput!) {
  setCountryCodeOnOrder(input: $input) {
    order {
      id
      number
      total {
        amount
        formatted
      }
      is_including_vat
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "country_code": "BE"
  }
}

setDutiesForOrder#

Set the import duties on an order, for example when shipping cross-border. The duties are reflected in the order totals.

Input: SetDutiesForOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`duties`	Money!▾	Required	The duties to charge — pass the amount in cents

Returns: SetDutiesForOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation SetDutiesForOrder($input: SetDutiesForOrderInput!) {
  setDutiesForOrder(input: $input) {
    order {
      id
      number
      total {
        amount
        formatted
      }
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "duties": 1250
  }
}

setExpirationDateForOrder#

Set the expiration date of an order. After this date an unconfirmed order expires and its claimed stock is released.

Input: SetExpirationDateForOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`expires_at`	Int64!	Required	Expiration date — Unix timestamp in milliseconds

Returns: SetExpirationDateForOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation SetExpirationDateForOrder($input: SetExpirationDateForOrderInput!) {
  setExpirationDateForOrder(input: $input) {
    order {
      id
      number
      status
      expires_at
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "expires_at": 1767225600000
  }
}

setItemQuantityForOrder#

Set the quantity of a SKU on an order to an absolute value — items are added or removed until the order holds exactly the requested quantity.

Input: SetItemQuantityForOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`sku`	String!	Required	The SKU to set the quantity for
`quantity`	Int!	Required	The new absolute quantity for this SKU

Returns: SetItemQuantityForOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation SetItemQuantityForOrder($input: SetItemQuantityForOrderInput!) {
  setItemQuantityForOrder(input: $input) {
    order {
      id
      number
      total
      items {
        ids
        sku
        quantity
      }
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "sku": "SKU-8471",
    "quantity": 3
  }
}

setItemQuantityOnOrder#

Set the quantity of a SKU on an order to an absolute value. Equivalent to setItemQuantityForOrder — both return the same payload.

Input: SetItemQuantityOnOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`sku`	String!	Required	The SKU to set the quantity for
`quantity`	Int!	Required	The new absolute quantity for this SKU

Returns: SetItemQuantityForOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation SetItemQuantityOnOrder($input: SetItemQuantityOnOrderInput!) {
  setItemQuantityOnOrder(input: $input) {
    order {
      id
      number
      total
      items {
        ids
        sku
        quantity
      }
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "sku": "SKU-8471",
    "quantity": 3
  }
}

setNoteForOrder#

Set a note on an order, for example special instructions from the customer or an internal remark. The note replaces any previously set note.

Input: SetNoteForOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`note`	String!	Required	The note to set on the order

Returns: SetNoteForOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation SetNoteForOrder($input: SetNoteForOrderInput!) {
  setNoteForOrder(input: $input) {
    order {
      id
      number
      status
      customer {
        notes
      }
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "note": "Please deliver at the back entrance."
  }
}

setOrderTag#

Set a tag on an order by selecting an option for a tag key, for example to label the order for filtering and workflow automation.

Input: SetOrderTagInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`key_id`	String!	Required	The ID of the tag key
`option_id`	String!	Required	The ID of the tag option to set for the key

Returns: SetOrderTagPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation SetOrderTag($input: SetOrderTagInput!) {
  setOrderTag(input: $input) {
    order {
      id
      number
      status
      tags {
        id
        label
      }
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "key_id": "tgk_3pWm5J",
    "option_id": "tgo_8qZr1N"
  }
}

setPositionForOrder#

Set the warehouse position for an order, for example the packing station or storage slot where the order is being prepared. Returns the updated order.

Input: SetPositionForOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`position`	String!	Required	The position to assign to the order (e.g. a packing station or storage slot)

Returns: SetPositionForOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation SetPositionForOrder($input: SetPositionForOrderInput!) {
  setPositionForOrder(input: $input) {
    order {
      id
      number
      position
      status
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "position": "A-12-03"
  }
}

setReferenceForOrder#

Set a custom reference on an order, for example the customer's purchase order number. Returns the updated order.

Input: SetReferenceForOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`reference`	String!	Required	The reference to set on the order (e.g. a purchase order number)

Returns: SetReferenceForOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation SetReferenceForOrder($input: SetReferenceForOrderInput!) {
  setReferenceForOrder(input: $input) {
    order {
      id
      number
      status
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "reference": "PO-2026-00481"
  }
}

updateAdjustmentForOrder#

Update an existing adjustment (discount or surcharge) on an order — change its description, amount, or whether the amount is a percentage.

Input: UpdateAdjustmentForOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`discount_id`	String!	Required	The ID of the adjustment to update
`description`	String!	Required	Description shown on the order and invoice
`is_percentage`	Boolean!	Required	Whether the amount is a percentage instead of a fixed amount
`amount`	Float!	Required	The adjustment amount — a percentage when is_percentage is true, otherwise a fixed amount in cents

Returns: UpdateAdjustmentForOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation UpdateAdjustment($input: UpdateAdjustmentForOrderInput!) {
  updateAdjustmentForOrder(input: $input) {
    order {
      id
      number
      total
      adjustments {
        id
        description
        amount
        is_percentage
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_2kV8mT",
    "discount_id": "adj_5qN7xB",
    "description": "Loyalty discount",
    "is_percentage": true,
    "amount": 10
  }
}

updateFeeForOrder#

Update an existing fee on an order — change its description or amount. The fee is identified by its fee_id and the change is reflected in the order totals.

Input: UpdateFeeForOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order carrying the fee
`fee_id`	String!	Required	The ID of the fee to update
`description`	String!	Required	Human-readable description shown on the order
`amount`	Money!▾	Required	New fee amount in cents

Returns: UpdateFeeForOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation UpdateFeeForOrder($input: UpdateFeeForOrderInput!) {
  updateFeeForOrder(input: $input) {
    order {
      id
      number
      total {
        amount
        formatted
      }
      fees {
        payment {
          id
          description
          total {
            amount
            formatted
          }
        }
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "fee_id": "fee_6Jd4rN",
    "description": "Payment provider surcharge",
    "amount": 295
  }
}

Order items#

addAdjustmentsToOrderItem#

Add one or more adjustments — fixed or percentage-based surcharges or discounts — to a single order item, or to several items at once via item_ids.

Input: AddAdjustmentsToOrderItemInput!

Name	Type	Required	Description
`item_id`	String	Optional	The ID of the order item to adjust
`item_ids`	[String]	Optional	IDs of multiple order items to adjust — alternative to `item_id`
`adjustments`	[AdjustmentInput]▾	Optional	The adjustments to add to the item(s)

Returns: AddAdjustmentsToOrderItemPayload!

Name	Type	Required	Description
`item`	CollectionItem▾	Optional	The updated order item (when a single `item_id` was passed)
`items`	[CollectionItem]!▾	Required	All updated order items

Example#

mutation AddAdjustmentsToOrderItem($input: AddAdjustmentsToOrderItemInput!) {
  addAdjustmentsToOrderItem(input: $input) {
    items {
      id
      sku
      label
      pricing {
        amount {
          amount
          formatted
        }
        original_amount {
          amount
          formatted
        }
      }
    }
  }
}

{
  "input": {
    "item_id": "itm_7GhQ2w",
    "adjustments": [
      {
        "description": "Damaged packaging discount",
        "is_percentage": false,
        "is_discount": true,
        "amount": 500
      }
    ]
  }
}

addAdjustmentsToOrderItems#

Add adjustments to multiple order items in a single call, where each adjustment targets a specific item via its own item_id.

Input: AddAdjustmentsToOrderItemsInput!

Name	Type	Required	Description
`adjustments`	[NewOrderItemAdjustmentInput]▾	Optional	Per-item adjustments to apply

Returns: AddAdjustmentsToOrderItemsPayload!

Name	Type	Required	Description
`items`	[CollectionItem]!▾	Required	The updated order items

Example#

mutation AddAdjustmentsToOrderItems($input: AddAdjustmentsToOrderItemsInput!) {
  addAdjustmentsToOrderItems(input: $input) {
    items {
      id
      sku
      label
      pricing {
        amount {
          amount
          formatted
        }
        original_amount {
          amount
          formatted
        }
      }
    }
  }
}

{
  "input": {
    "adjustments": [
      {
        "item_id": "itm_7GhQ2w",
        "description": "Bundle discount",
        "amount": 15,
        "is_percentage": true,
        "is_discount": true
      },
      {
        "item_id": "itm_9KpR4t",
        "description": "Bundle discount",
        "amount": 15,
        "is_percentage": true,
        "is_discount": true
      }
    ]
  }
}

addContraFeesToOrderItems#

Add contra fees to specific order items — offsetting fee lines that counter an existing fee on those items. Each contra fee references the fee it offsets via contra_fee_id.

Input: AddContraFeesToOrderItemsInput!

Name	Type	Required	Description
`item_ids`	[String]!	Required	IDs of the order items to add the contra fees to
`fees`	[ContraFeeInput]!▾	Required	The contra fees to add

Returns: AddContraFeesToOrderItemsPayload!

Name	Type	Required	Description
`items`	[CollectionItem]!▾	Required	The updated order items

Example#

mutation AddContraFeesToOrderItems($input: AddContraFeesToOrderItemsInput!) {
  addContraFeesToOrderItems(input: $input) {
    items {
      id
      sku
      label
      pricing {
        amount {
          amount
          formatted
        }
      }
    }
  }
}

{
  "input": {
    "item_ids": ["itm_7GhQ2w", "itm_9KpR4t"],
    "fees": [
      {
        "description": "Handling fee compensation",
        "type": "HANDLING_FEE",
        "amount": 250,
        "contra_fee_id": "fee_3JvB6n"
      }
    ]
  }
}

addDiscountsToOrderItem#

Add one or more discounts — percentage or fixed monetary value — to a single order item.

Input: AddDiscountsToOrderItemInput!

Name	Type	Required	Description
`item_id`	String!	Required	The ID of the order item
`discounts`	[DiscountInput]!▾	Required	The discounts to add to the item

Returns: AddAdjustmentsToOrderItemPayload!

Name	Type	Required	Description
`item`	CollectionItem▾	Optional	The updated order item
`items`	[CollectionItem]!▾	Required	All updated order items

Example#

mutation AddDiscountsToOrderItem($input: AddDiscountsToOrderItemInput!) {
  addDiscountsToOrderItem(input: $input) {
    item {
      id
      sku
      label
      pricing {
        amount {
          amount
          formatted
        }
        original_amount {
          amount
          formatted
        }
      }
    }
  }
}

{
  "input": {
    "item_id": "itm_7GhQ2w",
    "discounts": [
      {
        "description": "Display model discount",
        "type": "PERCENTAGE",
        "value": 20
      }
    ]
  }
}

addFeesToOrderItems#

Add one or more fees — payment, handling or shipping — to specific order items. The fee amounts are reflected in the pricing of the affected items.

Input: AddFeesToOrderItemsInput!

Name	Type	Required	Description
`item_ids`	[String]!	Required	IDs of the order items to add the fees to
`fees`	[FeeInput]!▾	Required	The fees to add to the items

Returns: AddFeesToOrderItemsPayload!

Name	Type	Required	Description
`items`	[CollectionItem]!▾	Required	The updated order items

Example#

mutation AddFeesToOrderItems($input: AddFeesToOrderItemsInput!) {
  addFeesToOrderItems(input: $input) {
    items {
      id
      sku
      label
      pricing {
        amount {
          amount
          formatted
        }
      }
    }
  }
}

{
  "input": {
    "item_ids": ["itm_7GhQ2w", "itm_9KpR4t"],
    "fees": [
      {
        "description": "Gift wrapping",
        "type": "HANDLING_FEE",
        "amount": 350
      }
    ]
  }
}

addPickUpPointToOrderItem#

Set a carrier pick-up point (service point) as the delivery location for a single order item, identified by its service point ID.

Input: AddPickUpPointToOrderItemInput!

Name	Type	Required	Description
`item_id`	String!	Required	The ID of the order item
`spid`	String!	Required	The service point ID of the pick-up point (as returned by the shipping method's pickup points)

Returns: AddPickUpPointToOrderItemPayload!

Name	Type	Required	Description
`item`	CollectionItem▾	Optional	The updated order item

Example#

mutation AddPickUpPointToOrderItem($input: AddPickUpPointToOrderItemInput!) {
  addPickUpPointToOrderItem(input: $input) {
    item {
      id
      sku
      label
      status
      delivery {
        id
        type
        expected_at
      }
    }
  }
}

{
  "input": {
    "item_id": "itm_7hRp2W",
    "spid": "8004-NL-100310"
  }
}

addPickUpPointToOrderItems#

Set carrier pick-up points (service points) as the delivery location for multiple order items in a single call. Each item is paired with its own service point ID.

Input: AddPickUpPointToOrderItemsInput!

Name	Type	Required	Description
`items`	[AddPickUpPointToOrderItemInput]!▾	Required	The items to assign a pick-up point to

Returns: AddPickUpPointToOrderItemsPayload!

Name	Type	Required	Description
`items`	[CollectionItem]!▾	Required	The updated order items

Example#

mutation AddPickUpPointToOrderItems($input: AddPickUpPointToOrderItemsInput!) {
  addPickUpPointToOrderItems(input: $input) {
    items {
      id
      sku
      label
      status
      delivery {
        id
        type
        expected_at
      }
    }
  }
}

{
  "input": {
    "items": [
      { "item_id": "itm_7hRp2W", "spid": "8004-NL-100310" },
      { "item_id": "itm_9kTn4B", "spid": "8004-NL-100310" }
    ]
  }
}

addShippingAddressToOrderItems#

Set a shipping destination for multiple order items in a single call. Each item can reference an existing address, supply a new address, or point to a service point or location, allowing different items of one order to ship to different destinations.

Input: AddShippingAddressToOrderItemsInput!

Name	Type	Required	Description
`items`	[AddShippingAddressToOrderItemInput]!▾	Required	The items to assign a shipping destination to

Returns: AddShippingAddressToOrderItemsPayload!

Name	Type	Required	Description
`items`	[CollectionItem]!▾	Required	The updated order items

Example#

mutation AddShippingAddressToOrderItems($input: AddShippingAddressToOrderItemsInput!) {
  addShippingAddressToOrderItems(input: $input) {
    items {
      id
      sku
      label
      status
      delivery {
        id
        type
        expected_at
      }
    }
  }
}

{
  "input": {
    "items": [
      {
        "item_id": "itm_7hRp2W",
        "type": "ADDRESS",
        "address": {
          "address_line_1": "Keizersgracht 313",
          "locality": "Amsterdam",
          "postal_code": "1016 EE",
          "country_code": "NL"
        }
      },
      {
        "item_id": "itm_9kTn4B",
        "type": "ADDRESS",
        "address_id": "adr_5FgH1s"
      }
    ]
  }
}

allocateOrderItems#

Allocate specific order items to available inventory so they are reserved for fulfilment.

Input: AllocateOrderItemsInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`items`	[String]!	Required	IDs of the order items to allocate

Returns: AllocateOrderItemsPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation AllocateOrderItems($input: AllocateOrderItemsInput!) {
  allocateOrderItems(input: $input) {
    order {
      id
      number
      state
      status
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_9GtRfK",
    "items": ["itm_2mQx9k", "itm_7bTn4w"]
  }
}

approveOrderItems#

Approve specific order items so they are released for further processing and fulfilment.

Input: ApproveOrderItemsInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`items`	[String]!	Required	IDs of the order items to approve

Returns: ApproveOrderItemsPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation ApproveOrderItems($input: ApproveOrderItemsInput!) {
  approveOrderItems(input: $input) {
    order {
      id
      number
      state
      status
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_9GtRfK",
    "items": ["itm_2mQx9k", "itm_7bTn4w"]
  }
}

assignInventoryToOrderItems#

Assign specific inventory to order items by linking each item to a warehouse location, reserving that stock for the order.

Input: AssignInventoryToOrderItemsInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`items`	[InventoryItemInput]!▾	Required	The order items and the inventory location to assign each of them to

Returns: AssignInventoryToOrderItemsPayload!

Name	Type	Required	Description
`items`	[CollectionItem]!▾	Required	The updated order items

Example#

mutation AssignInventoryToOrderItems($input: AssignInventoryToOrderItemsInput!) {
  assignInventoryToOrderItems(input: $input) {
    items {
      id
      sku
      status
      is_allocated
      is_reserved
    }
  }
}

{
  "input": {
    "order_id": "ord_9GtRfK",
    "items": [
      { "id": "itm_2mQx9k", "location_id": "loc_5wPn8d" },
      { "id": "itm_7bTn4w", "location_id": "loc_5wPn8d" }
    ]
  }
}

cancelCollectOrderItems#

Cancel the collect step for specific order items, so items previously marked for collection are no longer collected.

Input: CancelCollectOrderItemsInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`items`	[String]!	Required	IDs of the order items to cancel collection for

Returns: CancelCollectOrderItemsPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation CancelCollectOrderItems($input: CancelCollectOrderItemsInput!) {
  cancelCollectOrderItems(input: $input) {
    order {
      id
      number
      state
      status
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_9GtRfK",
    "items": ["itm_2mQx9k", "itm_7bTn4w"]
  }
}

collectOrderItems#

Mark one or more order items as collected, for example when a customer picks up their items at a store or collection point. Returns the updated order.

Input: CollectOrderItemsInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order whose items are collected
`items`	[String]!	Required	IDs of the order items to mark as collected

Returns: CollectOrderItemsPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation CollectOrderItems($input: CollectOrderItemsInput!) {
  collectOrderItems(input: $input) {
    order {
      id
      number
      state
      total
      items {
        id
        sku
        quantity
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_7Ks9mL",
    "items": ["oitm_2xQ8pR", "oitm_5nT3wY"]
  }
}

deallocateOrderItems#

Release the warehouse stock allocations for specific order items, making the claimed stock available again without cancelling the items.

Input: DeallocateOrderItemsInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`items`	[String]!	Required	IDs of the order items to deallocate

Returns: DeallocateOrderItemsPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation DeallocateOrderItems($input: DeallocateOrderItemsInput!) {
  deallocateOrderItems(input: $input) {
    order {
      id
      number
      status
      items {
        ids
        sku
        quantity
      }
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_5tGh7Y",
    "items": ["itm_8jRw3D", "itm_2qLc7V"]
  }
}

finishOrderItems#

Mark one or more order items as finished, completing their fulfilment flow. Returns the updated order.

Input: FinishOrderItemsInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`items`	[String]!	Required	IDs of the order items to finish

Returns: FinishOrderItemsPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation FinishOrderItems($input: FinishOrderItemsInput!) {
  finishOrderItems(input: $input) {
    order {
      id
      number
      status
      items {
        ids
        sku
      }
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "items": ["itm_5wRt8Kd", "itm_2pLm6Vx"]
  }
}

haltOrderItems#

Halt the fulfilment of one or more order items, pausing them in the processing flow. Returns the updated order.

Input: HaltOrderItemsInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`items`	[HaltedItemInput]!▾	Required	The order items to halt

Returns: HaltOrderItemsPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation HaltOrderItems($input: HaltOrderItemsInput!) {
  haltOrderItems(input: $input) {
    order {
      id
      number
      status
      items {
        ids
        sku
      }
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "items": [
      { "item_id": "itm_5wRt8Kd" },
      { "item_id": "itm_2pLm6Vx" }
    ]
  }
}

invoiceItems#

Invoice one or more order items. Pass an existing invoice_id to add the items to that invoice, or omit it to create a new invoice for the items.

Input: InvoiceItemsInput!

Name	Type	Required	Description
`invoice_id`	String	Optional	ID of an existing invoice to add the items to — omit to create a new invoice
`items`	[String]!	Required	IDs of the order items to invoice

Returns: InvoiceItemsPayload

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

Example#

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

{
  "input": {
    "items": ["itm_5wRt8Kd", "itm_2pLm6Vx"]
  }
}

receiveOrderItems#

Register order items as received into the warehouse, recording the location and position where each item is stored. Typically used for inbound purchase or return flows.

Input: ReceiveOrderItemsInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`items`	[ReceiveItemInput]!▾	Required	The items to receive

Returns: ReceiveOrderItemsPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation ReceiveOrderItems($input: ReceiveOrderItemsInput!) {
  receiveOrderItems(input: $input) {
    order {
      id
      number
      status
      items {
        id
        sku
        position
        is_received
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "items": [
      {
        "item_id": "itm_4Tp8vLc",
        "position": "A-01-03",
        "location_id": "loc_2Jd6bJw"
      }
    ]
  }
}

releaseOrderItems#

Release one or more order items for fulfilment, making them available for the next step in the warehouse process.

Input: ReleaseOrderItemsInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`items`	[ReleaseOrderItem]!▾	Required	The items to release

Returns: ReleaseOrderItemsPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation ReleaseOrderItems($input: ReleaseOrderItemsInput!) {
  releaseOrderItems(input: $input) {
    order {
      id
      number
      status
      items {
        id
        sku
        is_released
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "items": [
      { "item_id": "itm_4Tp8vLc" },
      { "item_id": "itm_8Rq1sZn" }
    ]
  }
}

removeAdjustmentsFromOrderItem#

Remove one or more adjustments — surcharges or discounts — from an order item. Pass a single item_id or multiple item_ids to remove the adjustments from several items at once.

Input: RemoveAdjustmentsFromOrderItemInput!

Name	Type	Required	Description
`adjustment_ids`	[String]!	Required	The IDs of the adjustments to remove
`item_id`	String	Optional	The ID of a single order item to remove the adjustments from
`item_ids`	[String]	Optional	The IDs of multiple order items to remove the adjustments from

Returns: RemoveAdjustmentsFromOrderItemPayload!

Name	Type	Required	Description
`item`	CollectionItem▾	Optional	The updated order item (when a single `item_id` was passed)
`items`	[CollectionItem]!▾	Required	The updated order items

Example#

mutation RemoveAdjustmentsFromOrderItem($input: RemoveAdjustmentsFromOrderItemInput!) {
  removeAdjustmentsFromOrderItem(input: $input) {
    items {
      id
      sku
      label
      status
      is_cancelled
      updated_at
    }
  }
}

{
  "input": {
    "item_id": "itm_4Tp8vLc",
    "adjustment_ids": ["adj_6Yc3wHt"]
  }
}

removeDiscountsFromOrderItem#

Remove one or more previously applied discounts from a single order item by discount ID.

Input: RemoveDiscountsFromOrderItemInput!

Name	Type	Required	Description
`item_id`	String!	Required	The ID of the order item
`discount_ids`	[String]!	Required	IDs of the discounts to remove from the item

Returns: RemoveAdjustmentsFromOrderItemPayload!

Name	Type	Required	Description
`item`	CollectionItem▾	Optional	The updated order item
`items`	[CollectionItem]!▾	Required	All updated order items

Example#

mutation RemoveDiscountsFromOrderItem($input: RemoveDiscountsFromOrderItemInput!) {
  removeDiscountsFromOrderItem(input: $input) {
    item {
      id
      sku
      label
      pricing {
        amount {
          amount
          formatted
        }
        original_amount {
          amount
          formatted
        }
      }
    }
  }
}

{
  "input": {
    "item_id": "itm_7GhQ2w",
    "discount_ids": ["dsc_3JkP8n"]
  }
}

restockOrderItems#

Put returned or cancelled order items back into stock, optionally at a specific warehouse location and position.

Input: RestockOrderItemsInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`items`	[RestockItemInput]!▾	Required	The order items to restock

Returns: RestockOrderItemsPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation RestockOrderItems($input: RestockOrderItemsInput!) {
  restockOrderItems(input: $input) {
    order {
      id
      number
      status
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "items": [
      {
        "item_id": "itm_4Fq8Zw",
        "location_id": "loc_2Bn7Kd",
        "position": "A-03-2"
      }
    ]
  }
}

returnOrderItems#

Register order items as returned, optionally recording the return reason and a track & trace code for the return shipment.

Input: ReturnOrderItemsInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`items`	[ReturnItemInput]!▾	Required	The order items to return

Returns: ReturnOrderItemsPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation ReturnOrderItems($input: ReturnOrderItemsInput!) {
  returnOrderItems(input: $input) {
    order {
      id
      number
      status
      total {
        amount
        formatted
      }
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "items": [
      {
        "item_id": "itm_4Fq8Zw",
        "reason": "SIZE_TOO_SMALL",
        "track_trace_code": "3STBJK987654321"
      }
    ]
  }
}

setExpectedAtForOrderItems#

Set the expected delivery date for specific order items, for example when an item is backordered and will only become available at a known future date.

Input: SetExpectedAtForOrderItemsInput!

Name	Type	Required	Description
`expected_at`	Int64!	Required	Expected delivery date — Unix timestamp in milliseconds
`items`	[String]!	Required	IDs of the order items to update

Returns: SetExpectedAtForOrderItemsPayload

Name	Type	Required	Description
`items`	[CollectionItem!]!▾	Required	Items whose expected delivery date was updated

Example#

mutation SetExpectedAtForOrderItems($input: SetExpectedAtForOrderItemsInput!) {
  setExpectedAtForOrderItems(input: $input) {
    items {
      id
      sku
      label
      is_expected
      status
      updated_at
    }
  }
}

{
  "input": {
    "expected_at": 1767225600000,
    "items": ["itm_7hRp2W", "itm_9kTn4B"]
  }
}

setMetaDataForOrderItems#

Attach free-form metadata to specific order items, for example personalisation details or references from an external system.

Input: SetMetaDataForOrderItemsInput!

Name	Type	Required	Description
`meta_data`	JsonObject!▾	Required	Arbitrary metadata to store on the items
`items`	[String]!	Required	IDs of the order items to attach the metadata to

Returns: SetMetaDataForOrderItemsPayload!

Name	Type	Required	Description
`items`	[CollectionItem]!▾	Required	The updated order items

Example#

mutation SetMetaDataForOrderItems($input: SetMetaDataForOrderItemsInput!) {
  setMetaDataForOrderItems(input: $input) {
    items {
      id
      sku
      label
      meta_data
      updated_at
    }
  }
}

{
  "input": {
    "meta_data": {
      "engraving": "Happy Birthday!",
      "external_reference": "EXT-20431"
    },
    "items": ["itm_7hRp2W", "itm_9kTn4B"]
  }
}

setOriginForOrderItems#

Set the origin for one or more order items — either a warehouse location or an address the items should ship from. Returns the updated items.

Input: SetOriginForOrderItemsInput!

Name	Type	Required	Description
`item_ids`	[String]!	Required	IDs of the order items to set the origin for
`location_id`	String	Optional	The ID of the warehouse location the items should ship from
`address_id`	String	Optional	The ID of the address the items should ship from

Returns: SetOriginForOrderItemsPayload!

Name	Type	Required	Description
`items`	[CollectionItem]!▾	Required	The updated order items

Example#

mutation SetOriginForOrderItems($input: SetOriginForOrderItemsInput!) {
  setOriginForOrderItems(input: $input) {
    items {
      id
      sku
      label
      status
    }
  }
}

{
  "input": {
    "item_ids": ["itm_7GhQ2w", "itm_9KpR4t"],
    "location_id": "loc_5nT3wY"
  }
}

setPositionForOrderItems#

Set the warehouse position for one or more order items, for example the bin or shelf where the items are stored while awaiting fulfilment. Returns the updated items.

Input: SetPositionForOrderItemsInput!

Name	Type	Required	Description
`item_ids`	[String]!	Required	IDs of the order items to set the position for
`position`	String!	Required	The position to assign to the items (e.g. a bin or shelf code)

Returns: SetPositionForOrderItemsPayload!

Name	Type	Required	Description
`items`	[CollectionItem]!▾	Required	The updated order items

Example#

mutation SetPositionForOrderItems($input: SetPositionForOrderItemsInput!) {
  setPositionForOrderItems(input: $input) {
    items {
      id
      sku
      label
      position
    }
  }
}

{
  "input": {
    "item_ids": ["itm_7GhQ2w", "itm_9KpR4t"],
    "position": "B-04-17"
  }
}

setPriceForOrderItems#

Override the price of one or more order items, for example to apply a negotiated price. Each entry targets a specific item and sets its new price in cents. Returns the updated items.

Input: SetPriceForOrderItemsInput!

Name	Type	Required	Description
`items`	[OrderItemPricingUpdateInput]!▾	Required	Price updates, one per order item

Returns: SetPriceForOrderItemsPayload!

Name	Type	Required	Description
`items`	[CollectionItem]!▾	Required	The updated order items

Example#

mutation SetPriceForOrderItems($input: SetPriceForOrderItemsInput!) {
  setPriceForOrderItems(input: $input) {
    items {
      id
      sku
      label
      pricing {
        amount {
          amount
          formatted
        }
        original_amount {
          amount
          formatted
        }
      }
    }
  }
}

{
  "input": {
    "items": [
      {
        "item_id": "itm_7GhQ2w",
        "price": 1999,
        "original_price": 2499
      },
      {
        "item_id": "itm_9KpR4t",
        "price": 4500
      }
    ]
  }
}

setShipAtForOrderItems#

Set the planned ship date for one or more order items, scheduling when they should leave the warehouse.

Input: SetShipAtForOrderItemsInput!

Name	Type	Required	Description
`ship_at`	Int64!	Required	Planned ship date as Unix ms timestamp
`items`	[String]!	Required	IDs of the order items to schedule

Returns: SetShipAtForOrderItemsPayload

Name	Type	Required	Description
`items`	[CollectionItem!]!▾	Required	Items whose suggested ship date was updated

Example#

mutation SetShipAt($input: SetShipAtForOrderItemsInput!) {
  setShipAtForOrderItems(input: $input) {
    items {
      id
      sku
      label
      status
      is_picked
      is_collected
    }
  }
}

{
  "input": {
    "ship_at": 1783036800000,
    "items": ["itm_7hK3mR", "itm_2wQ9xN"]
  }
}

startItemCancellationProcess#

Start the cancellation process for one or more items on an order. Optionally pass a contra_id per item to link the cancellation to a contra (compensating) item.

Input: StartItemCancellationProcessInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order the items belong to
`location_id`	String	Optional	Location where the cancellation is processed
`items`	[ItemCancellationProcessInput]!▾	Required	The items to cancel

Returns: StartItemCancellationProcessPayload!

Name	Type	Required	Description
`items`	[CollectionItem]!▾	Required	The items with the cancellation process started

Example#

mutation StartItemCancellation($input: StartItemCancellationProcessInput!) {
  startItemCancellationProcess(input: $input) {
    items {
      id
      sku
      label
      status
      is_cancelled
    }
  }
}

{
  "input": {
    "order_id": "ord_2kV8mT",
    "items": [
      { "id": "itm_7hK3mR" },
      { "id": "itm_2wQ9xN" }
    ]
  }
}

updateAdjustmentForOrderItem#

Update an existing adjustment — a fixed or percentage-based surcharge or discount — on an order item, or on several items at once via item_ids. The adjustment is identified by its discount_id.

Input: UpdateAdjustmentForOrderItemInput!

Name	Type	Required	Description
`item_id`	String	Optional	The ID of the order item carrying the adjustment
`item_ids`	[String]	Optional	IDs of multiple order items to update — alternative to `item_id`
`discount_id`	String!	Required	The ID of the adjustment to update
`description`	String!	Required	Human-readable description shown on the item
`is_percentage`	Boolean!	Required	Whether `amount` is a percentage instead of a fixed value
`amount`	Float!	Required	Adjustment value — a percentage when `is_percentage` is true, otherwise a fixed amount in cents

Returns: UpdateAdjustmentForOrderItemPayload!

Name	Type	Required	Description
`item`	CollectionItem▾	Optional	The updated order item (when a single `item_id` was passed)
`items`	[CollectionItem]!▾	Required	All updated order items

Example#

mutation UpdateAdjustmentForOrderItem($input: UpdateAdjustmentForOrderItemInput!) {
  updateAdjustmentForOrderItem(input: $input) {
    items {
      id
      sku
      label
      pricing {
        amount {
          amount
          formatted
        }
        original_amount {
          amount
          formatted
        }
      }
    }
  }
}

{
  "input": {
    "item_id": "itm_7GhQ2w",
    "discount_id": "dsc_4Tn8pW",
    "description": "Damaged packaging discount",
    "is_percentage": false,
    "amount": 750
  }
}

updateDiscountOnOrderItem#

Update an existing discount on an order item — change its description, type or value. The discount is identified by its discount_id.

Input: UpdateDiscountOnOrderItemInput!

Name	Type	Required	Description
`item_id`	String!	Required	The ID of the order item carrying the discount
`discount_id`	String!	Required	The ID of the discount to update
`description`	String!	Required	Human-readable description shown on the item
`type`	DiscountType!▾	Required	How the discount value is interpreted
`value`	Float!	Required	Discount value — a percentage when `type` is PERCENTAGE, otherwise a fixed amount in cents

Returns: UpdateAdjustmentForOrderItemPayload!

Name	Type	Required	Description
`item`	CollectionItem▾	Optional	The updated order item
`items`	[CollectionItem]!▾	Required	All updated order items

Example#

mutation UpdateDiscountOnOrderItem($input: UpdateDiscountOnOrderItemInput!) {
  updateDiscountOnOrderItem(input: $input) {
    item {
      id
      sku
      label
      pricing {
        amount {
          amount
          formatted
        }
        original_amount {
          amount
          formatted
        }
      }
    }
  }
}

{
  "input": {
    "item_id": "itm_7GhQ2w",
    "discount_id": "dsc_4Tn8pW",
    "description": "Loyalty discount",
    "type": "PERCENTAGE",
    "value": 10
  }
}

Organisation#

createOrganisation#

Create a new organisation.

Input: OrganisationInput!

Name	Type	Required	Description
`name`	String!	Required	Organisation name
`type`	OrganisationType!▾	Required	Organisation type
`is_guest`	Boolean!	Required	Whether this is a guest organisation
`administration`	AdministrationInput!	Required	Administration / accounting details
`audience_id`	String	Optional	Audience to associate this organisation with
`addressing`	AddressingInput	Optional	Billing and shipping addresses
`phone_numbers`	PhoneNumberInput	Optional	Phone numbers
`registration`	RegistrationInput	Optional	VAT / company registration
`channel_id`	String	Optional	Channel association
`price_list_id`	String	Optional	Price list

Returns: Organisation

Name	Type	Required	Description
`id`	ID!	Required	The ID
`name`	String	Optional	Organisation name
`type`	OrganisationType!▾	Required	Type of organisation
`number`	String	Optional	Organisation number

Example#

mutation CreateOrg($input: OrganisationInput!) {
  createOrganisation(input: $input) {
    organisation {
      id
      name
      type
      number
    }
  }
}

{
  "input": {
    "name": "Bakkerij De Vries B.V.",
    "type": "DEFAULT",
    "is_guest": false,
    "administration": {
      "language_code": "nl",
      "currency": "EUR"
    }
  }
}

updateOrganisation#

Update an existing organisation.

Input: UpdateOrganisationInput!

Name	Type	Required	Description
`id`	ID!	Required	The organisation ID
`name`	String!	Required	Organisation name
`type`	OrganisationType!	Required	Organisation type
`administration`	AdministrationInput!	Required	Administration / accounting details
`avatar`	String	Optional	Avatar URL
`addressing`	AddressingInput	Optional	Billing and shipping addresses
`registration`	RegistrationInput	Optional	VAT / company registration

Returns: Organisation

Name	Type	Required	Description
`id`	ID!	Required	The ID
`name`	String	Optional	Organisation name
`type`	OrganisationType!▾	Required	Type of organisation
`number`	String	Optional	Organisation number

Example#

mutation UpdateOrg($input: UpdateOrganisationInput!) {
  updateOrganisation(input: $input) {
    organisation {
      id
      name
    }
  }
}

{
  "input": {
    "id": "b2c3d4e5-f6a7-8901-2345-67890abcdef0",
    "name": "Bakkerij De Vries & Zonen B.V.",
    "type": "DEFAULT",
    "administration": {
      "language_code": "nl",
      "currency": "EUR"
    }
  }
}

addBillingAddressToOrganisation#

Attach a billing address to an organisation — either by referencing an existing address with address_id or by supplying a new address.

Input: AddBillingAddressToOrganisationInput!

Name	Type	Required	Description
`organisation_id`	String!	Required	The ID of the organisation
`address_id`	String	Optional	ID of an existing address to use as the billing address
`address`	AddressInput▾	Optional	A new billing address — alternative to `address_id`

Returns: AddBillingAddressToOrganisationPayload!

Name	Type	Required	Description
`organisation`	Organisation▾	Optional	The updated organisation

Example#

mutation AddBillingAddressToOrganisation($input: AddBillingAddressToOrganisationInput!) {
  addBillingAddressToOrganisation(input: $input) {
    organisation {
      id
      name
      billing_address {
        primary {
          address_line_1
          locality
          postal_code
          country_code
        }
      }
    }
  }
}

{
  "input": {
    "organisation_id": "org_4TnV8b",
    "address": {
      "address_line_1": "Keizersgracht 313",
      "locality": "Amsterdam",
      "postal_code": "1016 EE",
      "country_code": "NL",
      "organisation": "Acme B.V."
    }
  }
}

addContactToAccountOrganisation#

Add a contact to a shared (account) organisation with a specific role, referencing the contact by ID or by email address.

Input: AddContactToAccountOrganisationInput!

Name	Type	Required	Description
`organisation_id`	ID	Optional	The ID of the shared organisation
`contact`	SharedContactInput!▾	Required	The contact to add and the role to assign

Returns: AddContactToAccountOrganisationPayload!

Name	Type	Required	Description
`organisation`	Organisation▾	Optional	The updated organisation

Example#

mutation AddContactToAccountOrganisation($input: AddContactToAccountOrganisationInput!) {
  addContactToAccountOrganisation(input: $input) {
    organisation {
      id
      name
      type
      shared_contacts {
        role
        contact {
          id
          email
        }
      }
    }
  }
}

{
  "input": {
    "organisation_id": "org_4TnV8b",
    "contact": {
      "email": "jane@acme.com",
      "role": "USER"
    }
  }
}

addOrganisationToAccount#

Add an organisation to the signed-in customer account, including its administration details, addressing, phone numbers and registration.

Input: AddOrganisationToAccountInput!

Name	Type	Required	Description
`id`	String	Optional	Optional client-supplied identifier for the organisation
`name`	String!	Required	Name of the organisation
`administration`	AdministrationInput!▾	Required	Administration details of the organisation
`addressing`	AddressingInput▾	Optional	Billing and shipping addresses
`phone_numbers`	[PhoneNumberInput]▾	Optional	Phone numbers of the organisation
`registration`	RegistrationInput▾	Optional	Company registration details (e.g. VAT)
`coc_number`	String	Optional	Chamber of Commerce number

Returns: AddOrganisationToAccountPayload!

Name	Type	Required	Description
`account`	Account▾	Optional	The updated customer account

Example#

mutation AddOrganisationToAccount($input: AddOrganisationToAccountInput!) {
  addOrganisationToAccount(input: $input) {
    account {
      email
      given_name
      family_name
      organisations {
        id
        name
        coc_number
      }
    }
  }
}

{
  "input": {
    "name": "Acme B.V.",
    "administration": {
      "email": "billing@acme.example"
    },
    "coc_number": "12345678",
    "phone_numbers": [
      {
        "country_code": "NL",
        "number": "+31201234567"
      }
    ]
  }
}

addOrganisationToContact#

Link an existing organisation to a contact, optionally marking it as the contact's primary organisation.

Input: AddOrganisationToContactInput!

Name	Type	Required	Description
`contact_id`	String!	Required	The ID of the contact
`organisation_id`	String!	Required	The ID of the organisation to link
`is_primary`	Boolean!	Required	Whether this is the contact's primary organisation

Returns: AddOrganisationToContactPayload!

Name	Type	Required	Description
`contact`	Contact▾	Optional	The updated contact

Example#

mutation AddOrganisationToContact($input: AddOrganisationToContactInput!) {
  addOrganisationToContact(input: $input) {
    contact {
      id
      email
      name
      organisations {
        primary {
          id
          name
        }
      }
    }
  }
}

{
  "input": {
    "contact_id": "cnt_6XdF9s",
    "organisation_id": "org_3PzL8v",
    "is_primary": true
  }
}

addPhoneNumberToOrganisation#

Add a phone number to an organisation, either by referencing an existing phone number by ID or by supplying a new one. The number can be marked as the organisation's primary phone number.

Input: AddPhoneNumberToOrganisationInput!

Name	Type	Required	Description
`organisation_id`	String!	Required	The ID of the organisation
`phone_number_id`	String	Optional	The ID of an existing phone number to attach
`phone_number`	PhoneNumberInput▾	Optional	A new phone number to attach — used when no `phone_number_id` is given
`is_primary`	Boolean!	Required	Whether this is the organisation's primary phone number

Returns: AddPhoneNumberToOrganisationPayload!

Name	Type	Required	Description
`organisation`	Organisation▾	Optional	The updated organisation

Example#

mutation AddPhoneNumberToOrganisation($input: AddPhoneNumberToOrganisationInput!) {
  addPhoneNumberToOrganisation(input: $input) {
    organisation {
      id
      name
      phone_numbers {
        primary {
          id
          country_code
          number
        }
      }
    }
  }
}

{
  "input": {
    "organisation_id": "org_3PzL8v",
    "phone_number": {
      "country_code": "NL",
      "number": "+31201234567"
    },
    "is_primary": true
  }
}

addShippingAddressToOrganisation#

Attach a shipping address to an organisation — either by referencing an existing address with address_id or by supplying a new address.

Input: AddShippingAddressToOrganisationInput!

Name	Type	Required	Description
`organisation_id`	String!	Required	The ID of the organisation
`address_id`	String	Optional	ID of an existing address to use as the shipping address
`address`	AddressInput▾	Optional	A new shipping address — alternative to `address_id`

Returns: AddShippingAddressToOrganisationPayload!

Name	Type	Required	Description
`organisation`	Organisation▾	Optional	The updated organisation

Example#

mutation AddShippingAddressToOrganisation($input: AddShippingAddressToOrganisationInput!) {
  addShippingAddressToOrganisation(input: $input) {
    organisation {
      id
      name
      shipping_address {
        primary {
          address_line_1
          locality
          postal_code
          country_code
        }
      }
    }
  }
}

{
  "input": {
    "organisation_id": "org_4TnV8b",
    "address": {
      "address_line_1": "Keizersgracht 313",
      "locality": "Amsterdam",
      "postal_code": "1016 EE",
      "country_code": "NL",
      "organisation": "Acme B.V."
    }
  }
}

addVatNumberToOrganisation#

Add a VAT registration (country code + number) to an organisation. The registration is stored on the organisation and can subsequently be verified.

Input: VatNumberInput!

Name	Type	Required	Description
`organisation_id`	String!	Required	The ID of the organisation to add the VAT number to
`registration`	RegistrationInput!▾	Required	The VAT registration details

Returns: AddVatNumberToOrganisationPayload!

Name	Type	Required	Description
`organisation`	Organisation▾	Optional	The updated organisation

Example#

mutation AddVatNumber($input: VatNumberInput!) {
  addVatNumberToOrganisation(input: $input) {
    organisation {
      id
      name
      registration {
        id
        country_code
        number
      }
    }
  }
}

{
  "input": {
    "organisation_id": "org_8kT2mQ",
    "registration": {
      "country_code": "NL",
      "number": "NL123456789B01"
    }
  }
}

blockOrganisation#

Block an organisation. The organisation is flagged as blocked (is_blocked) on the organisation record.

Input: BlockOrganisationInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the organisation to block

Returns: BlockOrganisationPayload!

Name	Type	Required	Description
`organisation`	Organisation▾	Optional	The updated organisation

Example#

mutation BlockOrganisation($input: BlockOrganisationInput!) {
  blockOrganisation(input: $input) {
    organisation {
      id
      name
      is_blocked
    }
  }
}

{
  "input": {
    "id": "org_8kT2mQ"
  }
}

logInAsOrganisation#

Log the current session in on behalf of an organisation. Returns a new token scoped to that organisation, to be used for subsequent requests.

Input: LogInAsOrganisationInput!

Name	Type	Required	Description
`organisation_id`	String!	Required	The ID of the organisation to log in as

Returns: LogInAsOrganisationPayload!

Name	Type	Required	Description
`token`	String!	Required	The new session token scoped to the organisation
`expires_at`	Int64!	Required	When the token expires — Unix timestamp in milliseconds

Example#

mutation LogInAsOrganisation($input: LogInAsOrganisationInput!) {
  logInAsOrganisation(input: $input) {
    token
    expires_at
  }
}

{
  "input": {
    "organisation_id": "org_7pQm3Xw"
  }
}

logOutAsOrganisation#

End the current organisation session started with logInAsOrganisation. Returns a new token that is no longer scoped to the organisation.

No input.

Returns: LogOutAsOrganisationPayload!

Name	Type	Required	Description
`token`	String!	Required	The new session token, no longer scoped to the organisation
`expires_at`	Int64!	Required	When the token expires — Unix timestamp in milliseconds

Example#

mutation LogOutAsOrganisation {
  logOutAsOrganisation {
    token
    expires_at
  }
}

markOrganisationAsDefault#

Mark one of the account's organisations as the default organisation, for example the one used by default for new orders. Returns the updated account.

Input: MarkOrganisationAsDefaultInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the organisation to mark as default

Returns: MarkOrganisationAsDefaultPayload!

Name	Type	Required	Description
`account`	Account▾	Optional	The updated account

Example#

mutation MarkOrganisationAsDefault($input: MarkOrganisationAsDefaultInput!) {
  markOrganisationAsDefault(input: $input) {
    account {
      email
      given_name
      family_name
      organisations {
        id
        name
        type
      }
    }
  }
}

{
  "input": {
    "id": "org_4Yt8vN"
  }
}

removeContactFromAccountOrganisation#

Remove a contact from a shared (account) organisation, revoking that contact's membership.

Input: RemoveContactFromAccountOrganisationInput!

Name	Type	Required	Description
`organisation_id`	ID	Optional	The ID of the shared organisation
`contact_id`	ID!	Required	The ID of the contact to remove

Returns: RemoveContactFromAccountOrganisationPayload!

Name	Type	Required	Description
`organisation`	Organisation▾	Optional	The updated organisation

Example#

mutation RemoveContactFromAccountOrganisation($input: RemoveContactFromAccountOrganisationInput!) {
  removeContactFromAccountOrganisation(input: $input) {
    organisation {
      id
      name
      type
      shared_contacts {
        role
        contact {
          id
          email
        }
      }
    }
  }
}

{
  "input": {
    "organisation_id": "org_4TnV8b",
    "contact_id": "cnt_5RwK9d"
  }
}

removeContactFromOrganisation#

Remove a contact from an organisation, referencing both the organisation and the contact by ID.

Input: RemoveContactFromOrganisationInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the organisation
`contact_id`	ID!	Required	The ID of the contact to remove

Returns: RemoveContactFromOrganisationPayload!

Name	Type	Required	Description
`organisation`	Organisation▾	Optional	The updated organisation

Example#

mutation RemoveContactFromOrganisation($input: RemoveContactFromOrganisationInput!) {
  removeContactFromOrganisation(input: $input) {
    organisation {
      id
      name
      type
      updated_at
    }
  }
}

{
  "input": {
    "id": "org_4TnV8b",
    "contact_id": "cnt_5RwK9d"
  }
}

removeOrganisationFromAccount#

Remove an organisation from the signed-in customer account. Returns the updated account.

Input: RemoveOrganisationFromAccountInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the organisation to remove from the account

Returns: RemoveOrganisationFromAccountPayload!

Name	Type	Required	Description
`account`	Account▾	Optional	The updated customer account

Example#

mutation RemoveOrganisationFromAccount($input: RemoveOrganisationFromAccountInput!) {
  removeOrganisationFromAccount(input: $input) {
    account {
      email
      given_name
      family_name
      organisations {
        id
        name
      }
    }
  }
}

{
  "input": {
    "id": "org_4WnB6c"
  }
}

removeRegistrationFromOrganisation#

Remove a company registration (such as a VAT registration) from an organisation. Returns the updated organisation.

Input: RemoveRegistrationFromOrganisationInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the registration to remove

Returns: RemoveRegistrationFromOrganisationPayload!

Name	Type	Required	Description
`organisation`	Organisation▾	Optional	The updated organisation

Example#

mutation RemoveRegistrationFromOrganisation($input: RemoveRegistrationFromOrganisationInput!) {
  removeRegistrationFromOrganisation(input: $input) {
    organisation {
      id
      name
      coc_number
      registration {
        id
        number
        country_code
      }
    }
  }
}

{
  "input": {
    "id": "reg_2VtY5n"
  }
}

setOrganisationTag#

Set a tag on an organisation by picking an option for a tagging key, for example to segment organisations by industry or account tier. Returns the updated organisation.

Input: SetOrganisationTagInput!

Name	Type	Required	Description
`organisation_id`	String!	Required	The ID of the organisation to tag
`key_id`	String!	Required	The ID of the tagging key
`option_id`	String!	Required	The ID of the option to set for the tagging key

Returns: SetOrganisationTagPayload!

Name	Type	Required	Description
`organisation`	Organisation▾	Optional	The updated organisation

Example#

mutation SetOrganisationTag($input: SetOrganisationTagInput!) {
  setOrganisationTag(input: $input) {
    organisation {
      id
      name
      tags {
        id
        label
      }
    }
  }
}

{
  "input": {
    "organisation_id": "org_8kT2mQ",
    "key_id": "key_3Fp7Lx",
    "option_id": "opt_9RwB5n"
  }
}

unblockOrganisation#

Unblock a previously blocked organisation, allowing it to place orders again.

Input: UnblockOrganisationInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the organisation to unblock

Returns: UnblockOrganisationPayload!

Name	Type	Required	Description
`organisation`	Organisation▾	Optional	The unblocked organisation

Example#

mutation UnblockOrganisation($input: UnblockOrganisationInput!) {
  unblockOrganisation(input: $input) {
    organisation {
      id
      name
      number
      is_blocked
    }
  }
}

{
  "input": {
    "id": "org_6tY3nH"
  }
}

updateContactRoleInOrganisation#

Change the role of a contact within a shared organisation — for example promote a user to admin.

Input: UpdateContactRoleInOrganisationInput!

Name	Type	Required	Description
`organisation_id`	ID	Optional	The ID of the organisation the contact belongs to
`contact_id`	ID!	Required	The ID of the contact whose role is changed
`role`	SharedContactRole!▾	Required	The new role of the contact within the organisation

Returns: UpdateContactRoleInOrganisationPayload!

Name	Type	Required	Description
`organisation`	Organisation▾	Optional	The updated organisation

Example#

mutation UpdateContactRoleInOrganisation($input: UpdateContactRoleInOrganisationInput!) {
  updateContactRoleInOrganisation(input: $input) {
    organisation {
      id
      name
      shared_contacts {
        role
        contact {
          id
          email
        }
      }
    }
  }
}

{
  "input": {
    "organisation_id": "org_9Bw3nT",
    "contact_id": "cnt_2Fj8kL",
    "role": "ADMIN"
  }
}

updateOrganisationOnAccount#

Update an organisation linked to the signed-in customer account — its name, administration details, addressing, phone numbers and registration.

Input: UpdateOrganisationOnAccountInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the organisation to update
`name`	String!	Required	Name of the organisation
`administration`	AdministrationInput!▾	Required	Administration details of the organisation
`addressing`	AddressingInput▾	Optional	Billing and shipping addresses
`phone_numbers`	[PhoneNumberInput]▾	Optional	Phone numbers of the organisation
`registration`	RegistrationInput▾	Optional	Company registration details (e.g. VAT)
`coc_number`	String	Optional	Chamber of Commerce number

Returns: UpdateOrganisationOnAccountPayload!

Name	Type	Required	Description
`account`	Account▾	Optional	The updated customer account

Example#

mutation UpdateOrganisationOnAccount($input: UpdateOrganisationOnAccountInput!) {
  updateOrganisationOnAccount(input: $input) {
    account {
      email
      given_name
      family_name
      organisations {
        id
        name
        coc_number
      }
    }
  }
}

{
  "input": {
    "id": "org_9Bw3nT",
    "name": "Acme B.V.",
    "administration": {
      "email": "billing@acme.example"
    },
    "coc_number": "12345678",
    "phone_numbers": [
      {
        "country_code": "NL",
        "number": "+31201234567"
      }
    ]
  }
}

Payment#

executePayment#

Execute a payment for an order.

Input: ExecutePaymentInput!

Name	Type	Required	Description
`payment_id`	String!	Required	The ID of the payment to execute (obtained from `addPaymentMethodToOrder`)

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

Example#

mutation Pay($input: ExecutePaymentInput!) {
  executePayment(input: $input) {
    payment {
      id
      status
      amount
      return_url
    }
  }
}

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

createRefund#

Create a refund for an order payment.

Input: CreateRefundInput!

Name	Type	Required	Description
`payment_id`	String!	Required	The payment ID to refund
`amount`	Int!	Required	Amount to refund (in cents)

Name	Type	Required	Description
`payment`	Payment▾	Optional	The refund payment record

Example#

mutation Refund($input: CreateRefundInput!) {
  createRefund(input: $input) {
    payment {
      id
      amount
      status
      is_refund
    }
  }
}

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

Customer authentication#

logInCustomer#

Authenticate a customer with email and password. Returns a short-lived session token.

Input: LogInCustomerInput!

Name	Type	Required	Description
`email`	String!	Required	Customer's email address
`password`	String!	Required	Customer's password

Name	Type	Required	Description
`token`	String!	Required	Session token (Bearer)
`expires_at`	Int64!	Required	Expiry as Unix milliseconds

Example#

mutation LogIn($input: LogInCustomerInput!) {
  logInCustomer(input: $input) {
    token
    expires_at
  }
}

{
  "input": {
    "email": "jan@example.nl",
    "password": "s3cur3Pa$$w0rd"
  }
}

registerCustomer#

Input: RegisterCustomerInput!

Name	Type	Required	Description
`email`	String!	Required	Email address
`password`	String!	Required	Password
`given_name`	String	Optional	First name
`additional_name`	String	Optional	Middle name
`family_name`	String	Optional	Last name

Name	Type	Required	Description
`token`	String!	Required	Session token (Bearer)
`expires_at`	Int64!	Required	Expiry as Unix milliseconds

Example#

mutation Register($input: RegisterCustomerInput!) {
  registerCustomer(input: $input) {
    token
    expires_at
  }
}

{
  "input": {
    "email": "jan@example.nl",
    "password": "s3cur3Pa$$w0rd",
    "given_name": "Jan",
    "family_name": "de Vries"
  }
}

requestCustomerPasswordReset#

Send a password reset email to a customer.

Input: RequestCustomerPasswordResetInput!

Name	Type	Required	Description
`email`	String!	Required	The customer's email address

Name	Type	Required	Description
`is_successful`	Boolean!	Required	Whether the reset email was sent

Example#

mutation RequestReset($input: RequestCustomerPasswordResetInput!) {
  requestCustomerPasswordReset(input: $input) {
    is_successful
  }
}

{
  "input": {
    "email": "jan@example.nl"
  }
}

resetCustomerPassword#

Reset a customer password using a token received by email.

Input: ResetCustomerPasswordInput!

Name	Type	Required	Description
`token`	String!	Required	The reset token from the email link
`password`	String!	Required	The new password

Name	Type	Required	Description
`is_successful`	Boolean!	Required	Whether the password was reset

Example#

mutation ResetPassword($input: ResetCustomerPasswordInput!) {
  resetCustomerPassword(input: $input) {
    is_successful
  }
}

{
  "input": {
    "token": "rst_a1b2c3d4e5f6789012345678901234567890abcd",
    "password": "newS3cur3Pa$$w0rd"
  }
}

requestCustomerVerificationLink#

Send a new verification link to an unverified customer.

Input: RequestCustomerVerificationLinkInput!

Name	Type	Required	Description
`email`	String!	Required	The customer's email address

Name	Type	Required	Description
`is_successful`	Boolean!	Required	Whether the link was sent

Example#

mutation RequestVerification($input: RequestCustomerVerificationLinkInput!) {
  requestCustomerVerificationLink(input: $input) {
    is_successful
  }
}

{
  "input": {
    "email": "jan@example.nl"
  }
}

verifyCustomer#

Verify a customer account using a token received by email.

Input: VerifyCustomerInput!

Name	Type	Required	Description
`token`	String!	Required	The verification token from the email link

Name	Type	Required	Description
`token`	String!	Required	Session token (Bearer)
`expires_at`	Int64!	Required	Expiry as Unix milliseconds

Example#

mutation Verify($input: VerifyCustomerInput!) {
  verifyCustomer(input: $input) {
    token
    expires_at
  }
}

{
  "input": {
    "token": "vfy_b2c3d4e5f6a7890123456789012345678901bcde"
  }
}

Account#

updateAccount#

Update the authenticated account's profile.

Input: UpdateAccountInput!

Name	Type	Required	Description
`given_name`	String	Optional	First name
`additional_name`	String	Optional	Middle name
`family_name`	String	Optional	Last name

Returns: Account

Name	Type	Required	Description
`email`	String!	Required	Email address
`given_name`	String!	Required	First name
`additional_name`	String!	Required	Middle name
`family_name`	String!	Required	Last name

Example#

mutation UpdateAccount($input: UpdateAccountInput!) {
  updateAccount(input: $input) {
    account {
      given_name
      family_name
      email
    }
  }
}

{
  "input": {
    "given_name": "Jan",
    "family_name": "de Vries"
  }
}

reorder#

Reorder a previous order. Adds all items from the referenced order to a new cart.

Input: ReorderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order to reorder

Returns: Cart

Name	Type	Required	Description
`id`	ID!	Required	The ID of the cart
`number`	String!	Required	Cart number
`total`	Money!	Required	Total value
`subtotal`	Money!	Required	Total before discounts

Example#

mutation Reorder($input: ReorderInput!) {
  reorder(input: $input) {
    cart {
      id
      items {
        sku
        quantity
      }
    }
  }
}

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

setPasswordForAccount#

Change the password of the signed-in account by providing the current password and the new one. Returns the account.

Input: SetPasswordForAccountInput!

Name	Type	Required	Description
`password`	String!	Required	The current password of the account
`new_password`	String!	Required	The new password to set

Returns: SetPasswordForAccountPayload!

Name	Type	Required	Description
`account`	Account▾	Optional	The updated account

Example#

mutation SetPasswordForAccount($input: SetPasswordForAccountInput!) {
  setPasswordForAccount(input: $input) {
    account {
      email
      given_name
      family_name
      updated_at
    }
  }
}

{
  "input": {
    "password": "current-password-123",
    "new_password": "n3w-Str0ng-p4ssword!"
  }
}

Contact#

createContact#

Create a new contact.

Input: ContactInput!

Name	Type	Required	Description
`email`	String!	Required	Email address
`is_guest`	Boolean!	Required	Whether this is a guest contact (no password)
`given_name`	String!	Required	First name
`family_name`	String!	Required	Last name
`additional_name`	String	Optional	Middle name
`password`	String	Optional	Password (when not a guest)
`locale`	String	Optional	Locale (e.g. nl_NL)
`channel_id`	String	Optional	Channel to associate this contact with
`price_list_id`	String	Optional	Price list to attach

Returns: Contact

Name	Type	Required	Description
`id`	ID!	Required	The ID
`email`	String!	Required	Email address
`given_name`	String!	Required	First name
`family_name`	String	Optional	Last name

Example#

mutation CreateContact($input: ContactInput!) {
  createContact(input: $input) {
    contact {
      id
      email
      given_name
      family_name
    }
  }
}

{
  "input": {
    "email": "lisa@example.nl",
    "is_guest": true,
    "given_name": "Lisa",
    "family_name": "Jansen"
  }
}

updateContact#

Update an existing contact.

Input: UpdateContactInput!

Name	Type	Required	Description
`id`	String!	Required	The ID of the contact
`given_name`	String	Optional	First name
`additional_name`	String	Optional	Middle name
`family_name`	String	Optional	Last name
`locale`	String	Optional	Locale

Returns: Contact

Name	Type	Required	Description
`id`	ID!	Required	The ID
`email`	String!	Required	Email address
`given_name`	String!	Required	First name
`family_name`	String	Optional	Last name

Example#

mutation UpdateContact($input: UpdateContactInput!) {
  updateContact(input: $input) {
    contact {
      id
      given_name
      family_name
    }
  }
}

{
  "input": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "given_name": "Lisa",
    "family_name": "Jansen-de Boer"
  }
}

addBillingAddressToContact#

Add a billing address to a contact.

Input: AddBillingAddressToContactInput!

Name	Type	Required	Description
`contact_id`	String!	Required	The ID of the contact
`address`	AddressInput!▾	Required	The billing address

Returns: Contact

Name	Type	Required	Description
`id`	ID!	Required	The ID
`email`	String!	Required	Email address
`given_name`	String!	Required	First name
`family_name`	String	Optional	Last name

Example#

mutation AddBillingAddress($input: AddBillingAddressToContactInput!) {
  addBillingAddressToContact(input: $input) {
    contact {
      id
      addressing {
        billing {
          primary {
            address_line_1
            locality
            country_code
          }
        }
      }
    }
  }
}

{
  "input": {
    "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "address": {
      "address_line_1": "Keizersgracht 313",
      "locality": "Amsterdam",
      "postal_code": "1016 EE",
      "country_code": "NL"
    }
  }
}

addShippingAddressToContact#

Add a shipping address to a contact.

Input: AddShippingAddressToContactInput!

Name	Type	Required	Description
`contact_id`	String!	Required	The ID of the contact
`address`	AddressInput!▾	Required	The shipping address

Returns: Contact

Name	Type	Required	Description
`id`	ID!	Required	The ID
`email`	String!	Required	Email address
`given_name`	String!	Required	First name
`family_name`	String	Optional	Last name

Example#

mutation AddShippingAddress($input: AddShippingAddressToContactInput!) {
  addShippingAddressToContact(input: $input) {
    contact {
      id
      addressing {
        shipping {
          primary {
            address_line_1
            locality
            country_code
          }
        }
      }
    }
  }
}

{
  "input": {
    "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "address": {
      "address_line_1": "Herengracht 401",
      "locality": "Amsterdam",
      "postal_code": "1017 BP",
      "country_code": "NL"
    }
  }
}

addConsentsToContact#

Input: AddConsentsToContactInput!

Name	Type	Required	Description
`contact_id`	String!	Required	The ID of the contact
`consent_ids`	[ID]!	Required	IDs of the consents to register on the contact

Returns: AddConsentsToContactPayload!

Name	Type	Required	Description
`contact`	Contact▾	Optional	The updated contact

Example#

mutation AddConsentsToContact($input: AddConsentsToContactInput!) {
  addConsentsToContact(input: $input) {
    contact {
      id
      email
      name
      consents {
        is_consented
      }
    }
  }
}

{
  "input": {
    "contact_id": "cnt_5RwK9d",
    "consent_ids": ["cns_2NpX7e", "cns_8QjM3a"]
  }
}

addPhoneNumberToContact#

Add a phone number to a contact, either by referencing an existing phone number by ID or by supplying a new one. The number can be marked as the contact's primary phone number.

Input: AddPhoneNumberToContactInput!

Name	Type	Required	Description
`contact_id`	String!	Required	The ID of the contact
`phone_number_id`	String	Optional	The ID of an existing phone number to attach
`phone_number`	PhoneNumberInput▾	Optional	A new phone number to attach — used when no `phone_number_id` is given
`is_primary`	Boolean!	Required	Whether this is the contact's primary phone number

Returns: AddPhoneNumberToContactPayload!

Name	Type	Required	Description
`contact`	Contact▾	Optional	The updated contact

Example#

mutation AddPhoneNumberToContact($input: AddPhoneNumberToContactInput!) {
  addPhoneNumberToContact(input: $input) {
    contact {
      id
      name
      phone_numbers {
        primary {
          id
          country_code
          number
        }
      }
    }
  }
}

{
  "input": {
    "contact_id": "cnt_6XdF9s",
    "phone_number": {
      "country_code": "NL",
      "number": "+31612345678"
    },
    "is_primary": true
  }
}

blockContact#

Block a contact. The contact is flagged as blocked (is_blocked) on the contact record.

Input: BlockContactInput!

Name	Type	Required	Description
`contact_id`	ID!	Required	The ID of the contact to block

Returns: BlockContactPayload!

Name	Type	Required	Description
`contact`	Contact▾	Optional	The updated contact

Example#

mutation BlockContact($input: BlockContactInput!) {
  blockContact(input: $input) {
    contact {
      id
      email
      name
      is_blocked
    }
  }
}

{
  "input": {
    "contact_id": "cnt_x9k2mQ"
  }
}

removeConsentsFromContact#

Withdraw one or more consents (for example marketing opt-ins) from a contact by consent ID.

Input: RemoveConsentsFromContactInput!

Name	Type	Required	Description
`contact_id`	String!	Required	The ID of the contact
`consent_ids`	[ID]!	Required	IDs of the consents to remove from the contact

Returns: RemoveConsentsFromContactPayload!

Name	Type	Required	Description
`contact`	Contact▾	Optional	The updated contact

Example#

mutation RemoveConsentsFromContact($input: RemoveConsentsFromContactInput!) {
  removeConsentsFromContact(input: $input) {
    contact {
      id
      email
      name
      consents {
        is_consented
      }
    }
  }
}

{
  "input": {
    "contact_id": "cnt_5RwK9d",
    "consent_ids": ["cns_2NpX7e", "cns_8QjM3a"]
  }
}

setContactTag#

Tag a contact by setting an option for a tag key on the contact. Tags let you segment contacts by predefined keys and their options.

Input: SetContactTagInput!

Name	Type	Required	Description
`contact_id`	String!	Required	The ID of the contact to tag
`key_id`	String!	Required	The ID of the tag key
`option_id`	String!	Required	The ID of the option to set for the tag key

Returns: SetContactTagPayload!

Name	Type	Required	Description
`contact`	Contact▾	Optional	The updated contact

Example#

mutation SetContactTag($input: SetContactTagInput!) {
  setContactTag(input: $input) {
    contact {
      id
      name
      email
      updated_at
    }
  }
}

{
  "input": {
    "contact_id": "cnt_8kQw2p",
    "key_id": "key_4rTn8b",
    "option_id": "opt_7hFp3W"
  }
}

unblockContact#

Unblock a previously blocked contact, allowing them to place orders and sign in again.

Input: UnblockContactInput!

Name	Type	Required	Description
`contact_id`	ID!	Required	The ID of the contact to unblock

Returns: UnblockContactPayload!

Name	Type	Required	Description
`contact`	Contact▾	Optional	The unblocked contact

Example#

mutation UnblockContact($input: UnblockContactInput!) {
  unblockContact(input: $input) {
    contact {
      id
      email
      name
      is_blocked
    }
  }
}

{
  "input": {
    "contact_id": "cnt_9wR4kM"
  }
}

Wishlist#

createWishlist#

Create a new wishlist. Returns a token used in subsequent wishlist operations.

Input: CreateWishlistInput!

Name	Type	Required	Description
`label`	String!	Required	Display label for the wishlist
`expires_at`	Int64!	Required	Unix-ms timestamp at which the wishlist expires

Returns: Wishlist

Name	Type	Required	Description
`label`	String!	Required	Label
`token`	String!	Required	Token identifier
`items`	[WishlistItem!]!▾	Required	Items on the wishlist
`expires_at`	DateTime!	Required	Expiration date

Example#

mutation CreateWishlist($input: CreateWishlistInput!) {
  createWishlist(input: $input) {
    wishlist {
      token
      label
    }
  }
}

{
  "input": {
    "label": "Mijn verlanglijst",
    "expires_at": 1893456000000
  }
}

addItemToWishlist#

Add a product to a wishlist by SKU.

Input: AddItemToWishlistInput!

Name	Type	Required	Description
`token`	String!	Required	The wishlist token
`sku`	String!	Required	The SKU to add
`quantity`	Int!	Required	Quantity to add
`expires_at`	Int64!	Required	Unix-ms timestamp at which the wishlist expires
`meta_data`	JsonObject	Optional	Optional metadata

Returns: Wishlist

Name	Type	Required	Description
`label`	String!	Required	Label
`token`	String!	Required	Token identifier
`items`	[WishlistItem!]!▾	Required	Items on the wishlist
`expires_at`	DateTime!	Required	Expiration date

Example#

mutation AddToWishlist($input: AddItemToWishlistInput!) {
  addItemToWishlist(input: $input) {
    wishlist {
      token
      items {
        sku
        added_at
      }
    }
  }
}

{
  "input": {
    "token": "c9d0e1f2-a3b4-5678-90ab-cdef01234567",
    "sku": "BLK-HOODIE-M",
    "quantity": 1,
    "expires_at": 1893456000000
  }
}

removeItemFromWishlist#

Remove a product from a wishlist.

Input: RemoveItemFromWishlistInput!

Name	Type	Required	Description
`token`	String!	Required	The wishlist token
`sku`	String!	Required	The SKU to remove

Returns: Wishlist

Name	Type	Required	Description
`label`	String!	Required	Label
`token`	String!	Required	Token identifier
`items`	[WishlistItem!]!▾	Required	Items on the wishlist
`expires_at`	DateTime!	Required	Expiration date

Example#

mutation RemoveFromWishlist($input: RemoveItemFromWishlistInput!) {
  removeItemFromWishlist(input: $input) {
    wishlist {
      token
      items {
        sku
      }
    }
  }
}

{
  "input": {
    "token": "c9d0e1f2-a3b4-5678-90ab-cdef01234567",
    "sku": "BLK-HOODIE-M"
  }
}

updateWishlist#

Update the label of a wishlist.

Input: UpdateWishlistInput!

Name	Type	Required	Description
`token`	String!	Required	The wishlist token
`label`	String!	Required	New label
`expires_at`	Int64!	Required	Unix-ms timestamp at which the wishlist expires

Returns: Wishlist

Name	Type	Required	Description
`label`	String!	Required	Label
`token`	String!	Required	Token identifier
`items`	[WishlistItem!]!▾	Required	Items on the wishlist
`expires_at`	DateTime!	Required	Expiration date

Example#

mutation UpdateWishlist($input: UpdateWishlistInput!) {
  updateWishlist(input: $input) {
    wishlist {
      token
      label
    }
  }
}

{
  "input": {
    "token": "c9d0e1f2-a3b4-5678-90ab-cdef01234567",
    "label": "Verlanglijst voor Sint",
    "expires_at": 1893456000000
  }
}

deleteWishlist#

Delete a wishlist.

Input: DeleteWishlistInput!

Name	Type	Required	Description
`token`	String!	Required	The wishlist token

Returns: Wishlist

Name	Type	Required	Description
`label`	String!	Required	Label
`token`	String!	Required	Token identifier
`items`	[WishlistItem!]!▾	Required	Items on the wishlist
`expires_at`	DateTime!	Required	Expiration date

Example#

mutation DeleteWishlist($input: DeleteWishlistInput!) {
  deleteWishlist(input: $input) {
    wishlist {
      token
    }
  }
}

{
  "input": {
    "token": "c9d0e1f2-a3b4-5678-90ab-cdef01234567"
  }
}

Product viewing history#

createProductViewingHistory#

Create a new product viewing history list. Returns a token used in subsequent calls.

Input: CreateProductViewingHistoryInput!

Name	Type	Required	Description
`label`	String!	Required	Display label for the history list
`expires_at`	Int64!	Required	Unix-ms timestamp at which the history list expires

Name	Type	Required	Description
`productViewingHistory`	ProductViewingHistory!▾	Required	The created history list

Example#

mutation CreateHistory($input: CreateProductViewingHistoryInput!) {
  createProductViewingHistory(input: $input) {
    productViewingHistory {
      token
    }
  }
}

{
  "input": {
    "label": "Recently viewed",
    "expires_at": 1893456000000
  }
}

addItemToProductViewingHistory#

Record a product view.

Input: AddItemToProductViewingHistoryInput!

Name	Type	Required	Description
`token`	String!	Required	The viewing history token
`sku`	String!	Required	The SKU that was viewed
`expires_at`	Int64!	Required	Unix-ms timestamp at which the history list expires
`meta_data`	JsonObject	Optional	Optional metadata (e.g. referrer, campaign)

Name	Type	Required	Description
`productViewingHistory`	ProductViewingHistory!▾	Required	The updated history list

Example#

mutation RecordView($input: AddItemToProductViewingHistoryInput!) {
  addItemToProductViewingHistory(input: $input) {
    productViewingHistory {
      token
      items {
        sku
        viewed_at
      }
    }
  }
}

{
  "input": {
    "token": "b8c9d0e1-f2a3-4567-890a-bcdef0123456",
    "sku": "BLK-HOODIE-M",
    "expires_at": 1893456000000
  }
}

deleteProductViewingHistory#

Delete a product viewing history, identified by its token. Use this to clear the list of recently viewed products for a visitor.

Input: DeleteProductViewingHistoryInput!

Name	Type	Required	Description
`token`	String!	Required	The token of the product viewing history to delete

Returns: DeleteProductViewingHistoryPayload!

Name	Type	Required	Description
`success`	Boolean!	Required	Whether the viewing history was deleted successfully

Example#

mutation DeleteProductViewingHistory($input: DeleteProductViewingHistoryInput!) {
  deleteProductViewingHistory(input: $input) {
    success
  }
}

{
  "input": {
    "token": "pvh_7dKw3nRq"
  }
}

updateProductViewingHistory#

Update a product viewing history's label and expiry date. The history is identified by the visitor token it was created with.

Input: UpdateProductViewingHistoryInput!

Name	Type	Required	Description
`token`	String!	Required	The visitor token identifying the viewing history
`label`	String!	Required	Label for the viewing history (e.g. "recently-viewed")
`expires_at`	Int64!	Required	New expiry as a Unix timestamp in milliseconds

Returns: UpdateProductViewingHistoryPayload!

Name	Type	Required	Description
`productViewingHistory`	ProductViewingHistory▾	Optional	The updated viewing history

Example#

mutation UpdateProductViewingHistory($input: UpdateProductViewingHistoryInput!) {
  updateProductViewingHistory(input: $input) {
    productViewingHistory {
      token
      label
      expires_at
      items {
        viewed_at
        product {
          sku
          label
        }
      }
    }
  }
}

{
  "input": {
    "token": "pvh_9f3kLm",
    "label": "recently-viewed",
    "expires_at": 1782950400000
  }
}

Products#

createItemPreferences#

Create stock preferences for one or more SKUs in a warehouse — minimum, optimal and maximum quantities, reorder points and backorder rules that drive replenishment.

Input: CreateItemPreferencesInput!

Name	Type	Required	Description
`preferences`	[ItemPreferenceInput]!▾	Required	Stock preferences to create, one per SKU/warehouse combination

Returns: CreateItemPreferencesPayload!

Name	Type	Required	Description
`preferences`	[StockPreference]!▾	Required	The created stock preferences

Example#

mutation CreateItemPreferences($input: CreateItemPreferencesInput!) {
  createItemPreferences(input: $input) {
    preferences {
      id
      sku
      minimum_quantity
      optimal_quantity
      maximum_quantity
      reorder_point
      is_backorder_allowed
    }
  }
}

{
  "input": {
    "preferences": [
      {
        "sku": "TSHIRT-BLK-M",
        "warehouse_id": "wrh_3Kf7dQ",
        "business_id": "bsn_4Tk8vN",
        "is_restricted_to_single_position": false,
        "minimum_quantity": 10,
        "optimal_quantity": 50,
        "maximum_quantity": 100,
        "reorder_point": 15,
        "is_backorder_allowed": true
      }
    ]
  }
}

createProduct#

Create a product identified by its SKU, including catalog information, pricing, suppliers, inventory options, order units and optional bundle composition.

Input: ProductInput!

Name	Type	Required	Description
`sku`	String!	Required	Unique SKU identifying the product
`channel_id`	String	Optional	Restrict the product to a specific channel
`information`	ProductInformationInput▾	Optional	Catalog information for the product
`pricing`	[ProductPricingInput]▾	Optional	Selling prices for the product
`vat_rate`	Float	Optional	VAT rate as a percentage (e.g. 21)
`suppliers`	[SupplierInput]▾	Optional	Suppliers of this product
`options`	ProductOptionsInput▾	Optional	Inventory tracking requirements for the product
`bundle`	ProductBundleInput▾	Optional	Bundle composition when the product is a bundle of other SKUs
`units`	[UnitInput]▾	Optional	Order and receive units for the product

Returns: CreateProductPayload!

Name	Type	Required	Description
`product`	Product!▾	Required	The created product

Example#

mutation CreateProduct($input: ProductInput!) {
  createProduct(input: $input) {
    product {
      sku
      label
      brand
      slug
      gtin
      created_at
    }
  }
}

{
  "input": {
    "sku": "TSHIRT-BLK-M",
    "information": {
      "label": "Black T-shirt (M)",
      "gtin": ["8712345678906"],
      "slug": "black-t-shirt-m",
      "mpn": "TS-BLK-M",
      "brand": "Acme",
      "images": ["https://cdn.example.com/tshirt-blk-m.jpg"],
      "filters": [{ "key": "color", "value": "black" }],
      "i18n": [
        {
          "locale": "nl-NL",
          "label": "Zwart T-shirt (M)",
          "slug": "zwart-t-shirt-m",
          "filters": [{ "key": "kleur", "value": "zwart" }]
        }
      ]
    },
    "pricing": [{ "amount": 2499 }],
    "vat_rate": 21
  }
}

deleteProduct#

Permanently delete a product by SKU, optionally removing its inventory records and any bundle items that reference it.

Input: DeleteProductInput!

Name	Type	Required	Description
`sku`	String!	Required	The SKU of the product to delete
`remove_inventory`	Boolean!	Required	Whether to also remove the inventory records for this SKU
`remove_bundle_items`	Boolean!	Required	Whether to also remove bundle items that reference this product

Returns: DeleteProductPayload!

Name	Type	Required	Description
`is_successful`	Boolean!	Required	Whether the product was deleted successfully

Example#

mutation DeleteProduct($input: DeleteProductInput!) {
  deleteProduct(input: $input) {
    is_successful
  }
}

{
  "input": {
    "sku": "TSHIRT-BLK-M",
    "remove_inventory": true,
    "remove_bundle_items": false
  }
}

removeItemPreferences#

Delete stock preferences — the replenishment rules (minimum, optimal and maximum quantities) for SKUs in a warehouse — by their IDs.

Input: RemoveItemPreferencesInput!

Name	Type	Required	Description
`preferences`	[ID]!	Required	IDs of the item preferences to remove

Returns: RemoveItemPreferencesPayload!

Name	Type	Required	Description
`is_successful`	Boolean!	Required	Whether the preferences were removed successfully

Example#

mutation RemoveItemPreferences($input: RemoveItemPreferencesInput!) {
  removeItemPreferences(input: $input) {
    is_successful
  }
}

{
  "input": {
    "preferences": ["prf_3TnW8b", "prf_6JqX2d"]
  }
}

saveProduct#

Create or update a product identified by its SKU, including catalog information, pricing, suppliers, inventory options, order units and optional bundle composition.

Input: ProductInput!

Name	Type	Required	Description
`sku`	String!	Required	Unique SKU identifying the product
`channel_id`	String	Optional	Restrict the product to a specific channel
`information`	ProductInformationInput▾	Optional	Catalog information for the product
`pricing`	[ProductPricingInput]▾	Optional	Selling prices for the product
`vat_rate`	Float	Optional	VAT rate as a percentage (e.g. 21)
`suppliers`	[SupplierInput]▾	Optional	Suppliers of this product
`options`	ProductOptionsInput▾	Optional	Inventory tracking requirements for the product
`bundle`	ProductBundleInput▾	Optional	Bundle composition when the product is a bundle of other SKUs
`units`	[UnitInput]▾	Optional	Order and receive units for the product

Returns: CreateProductPayload!

Name	Type	Required	Description
`product`	Product!▾	Required	The saved product

Example#

mutation SaveProduct($input: ProductInput!) {
  saveProduct(input: $input) {
    product {
      sku
      label
      brand
      slug
      gtin
      updated_at
    }
  }
}

{
  "input": {
    "sku": "TSHIRT-BLK-M",
    "information": {
      "label": "Black T-shirt (M)",
      "gtin": ["8712345678906"],
      "slug": "black-t-shirt-m",
      "mpn": "TS-BLK-M",
      "brand": "Acme",
      "images": ["https://cdn.example.com/tshirt-blk-m.jpg"],
      "filters": [{ "key": "color", "value": "black" }],
      "i18n": [
        {
          "locale": "nl-NL",
          "label": "Zwart T-shirt (M)",
          "slug": "zwart-t-shirt-m",
          "filters": [{ "key": "kleur", "value": "zwart" }]
        }
      ]
    },
    "pricing": [{ "amount": 2499 }],
    "vat_rate": 21
  }
}

updateItemPreferences#

Update stock preferences for one or more items in a warehouse — minimum, optimal and maximum quantities, reorder point, backorder policy and position restrictions.

Input: UpdateItemPreferencesInput!

Name	Type	Required	Description
`preferences`	[ItemPreferenceUpdateInput]!▾	Required	The stock preferences to update

Returns: UpdateItemPreferencesPayload!

Name	Type	Required	Description
`preferences`	[StockPreference]!▾	Required	The updated stock preferences

Example#

mutation UpdateItemPreferences($input: UpdateItemPreferencesInput!) {
  updateItemPreferences(input: $input) {
    preferences {
      id
      sku
      minimum_quantity
      optimal_quantity
      maximum_quantity
      reorder_point
      is_backorder_allowed
      warehouse {
        id
        label
      }
    }
  }
}

{
  "input": {
    "preferences": [
      {
        "id": "stp_8Nc5tR",
        "warehouse_id": "wrh_2Km7dV",
        "is_restricted_to_single_position": false,
        "minimum_quantity": 10,
        "optimal_quantity": 50,
        "maximum_quantity": 100,
        "reorder_point": 15,
        "is_backorder_allowed": true
      }
    ]
  }
}

updateItemPrices#

Override the unit prices of specific items on an order. The new prices are reflected in the order totals.

Input: UpdateItemPricesInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`prices`	[ItemPricesInput]!▾	Required	The new prices per order item

Returns: UpdateItemPricesPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation UpdateItemPrices($input: UpdateItemPricesInput!) {
  updateItemPrices(input: $input) {
    order {
      id
      number
      subtotal {
        amount
        formatted
      }
      total {
        amount
        formatted
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "prices": [
      {
        "item_id": "itm_7GhQ2w",
        "price": 2250
      }
    ]
  }
}

updateProduct#

Update an existing product identified by SKU — its information, pricing, VAT rate, tracking options, bundle composition and order units.

Input: ProductUpdateInput!

Name	Type	Required	Description
`sku`	String!	Required	SKU of the product to update
`channel_id`	String	Optional	Channel to scope the update to
`information`	ProductInformationInput▾	Optional	Descriptive product information
`pricing`	[ProductPricingInput]▾	Optional	Prices of the product
`vat_rate`	Float	Optional	VAT rate as a percentage (e.g. 21)
`options`	ProductOptionsInput▾	Optional	Inventory tracking requirements
`bundle`	ProductBundleInput▾	Optional	Bundle composition when the product is a bundle
`units`	[UnitInput]▾	Optional	Order and receive units of the product

Returns: UpdateProductPayload!

Name	Type	Required	Description
`product`	Product!▾	Required	The updated product

Example#

mutation UpdateProduct($input: ProductUpdateInput!) {
  updateProduct(input: $input) {
    product {
      sku
      label
      brand
      slug
      gtin
      images
      updated_at
    }
  }
}

{
  "input": {
    "sku": "TSHIRT-BLK-M",
    "information": {
      "label": "Classic T-shirt Black M",
      "gtin": ["8712345678901"],
      "slug": "classic-t-shirt-black-m",
      "mpn": "CT-BLK-M",
      "brand": "Acme Apparel",
      "images": ["https://cdn.example.com/tshirt-black-m.jpg"],
      "filters": [
        { "key": "color", "value": "black" },
        { "key": "size", "value": "M" }
      ],
      "i18n": [
        {
          "locale": "nl-NL",
          "label": "Klassiek T-shirt Zwart M",
          "slug": "klassiek-t-shirt-zwart-m",
          "filters": []
        }
      ]
    },
    "vat_rate": 21,
    "pricing": [
      { "amount": 2499 }
    ]
  }
}

Inventory#

markItemsAsAllocated#

Mark specific order items as allocated, recording that inventory has been reserved for them so they can move on to fulfilment. Returns the updated order.

Input: MarkItemsAsAllocatedInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order whose items are allocated
`items`	[AllocatedItemInput]!▾	Required	The order items to mark as allocated

Returns: MarkItemsAsAllocatedPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation MarkItemsAsAllocated($input: MarkItemsAsAllocatedInput!) {
  markItemsAsAllocated(input: $input) {
    order {
      id
      number
      state
      status
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_9GtRfK",
    "items": [
      { "item_id": "itm_2mQx9k" },
      { "item_id": "itm_7bTn4w" }
    ]
  }
}

markItemsAsAvailable#

Mark order items as available at a specific inventory location, indicating stock is on hand for them at that location. Returns the updated order.

Input: MarkItemsAvailableInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order whose items are available
`items`	[AvailableItemInput]!▾	Required	The order items to mark as available

Returns: MarkItemsAvailablePayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation MarkItemsAsAvailable($input: MarkItemsAvailableInput!) {
  markItemsAsAvailable(input: $input) {
    order {
      id
      number
      state
      status
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_9GtRfK",
    "items": [
      { "item_id": "itm_2mQx9k", "location_id": "loc_3Fh7jP" },
      { "item_id": "itm_7bTn4w", "location_id": "loc_3Fh7jP" }
    ]
  }
}

markItemsAsDeallocated#

Mark order items as deallocated, releasing the inventory that was reserved for them. Returns the updated order.

Input: MarkItemsAsDeallocatedInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order whose items are deallocated
`items`	[DeallocatedItemInput]!▾	Required	The order items to mark as deallocated

Returns: MarkItemsAsDeallocatedPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation MarkItemsAsDeallocated($input: MarkItemsAsDeallocatedInput!) {
  markItemsAsDeallocated(input: $input) {
    order {
      id
      number
      state
      status
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_9GtRfK",
    "items": [
      { "item_id": "itm_2mQx9k" }
    ]
  }
}

markItemsAsMissing#

Report order items as missing during fulfilment, for example when stock cannot be found in the warehouse. Optionally reference a contra item that replaces the missing one. Returns the updated order.

Input: MarkItemsAsMissingInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order whose items are missing
`items`	[MissingItemInput]!▾	Required	The order items to mark as missing

Returns: MarkItemsAsMissingPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation MarkItemsAsMissing($input: MarkItemsAsMissingInput!) {
  markItemsAsMissing(input: $input) {
    order {
      id
      number
      state
      status
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_9GtRfK",
    "items": [
      { "item_id": "itm_2mQx9k", "contra_item_id": "itm_8cVp5z" }
    ]
  }
}

markItemsAsUnavailable#

Mark order items as unavailable, indicating stock is not on hand to fulfil them. Returns the updated order.

Input: MarkItemsAsUnavailableInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order whose items are unavailable
`items`	[UnavailableItemInput]!▾	Required	The order items to mark as unavailable

Returns: MarkItemsAsUnavailablePayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation MarkItemsAsUnavailable($input: MarkItemsAsUnavailableInput!) {
  markItemsAsUnavailable(input: $input) {
    order {
      id
      number
      state
      status
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_9GtRfK",
    "items": [
      { "item_id": "itm_2mQx9k" }
    ]
  }
}

removeInventoryFromProduct#

Remove inventory records from a product by their IDs. Returns the updated product.

Input: RemoveInventoryFromProductInput!

Name	Type	Required	Description
`sku`	String!	Required	The SKU of the product to remove inventory from
`ids`	[String]!	Required	IDs of the inventory records to remove

Returns: RemoveInventoryFromProductPayload!

Name	Type	Required	Description
`product`	Product▾	Optional	The updated product

Example#

mutation RemoveInventoryFromProduct($input: RemoveInventoryFromProductInput!) {
  removeInventoryFromProduct(input: $input) {
    product {
      sku
      label
      brand
      inventory {
        id
        quantity
      }
    }
  }
}

{
  "input": {
    "sku": "TSHIRT-BLUE-M",
    "ids": ["inv_7GhQ2w", "inv_9KpR4t"]
  }
}

Stock & supplies#

addOverage#

Register an overage on a supply — an item that was received but not expected, identified by SKU and the warehouse position where it was found.

Input: AddOverageInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the supply to register the overage on
`item`	AddOverageItemInput!▾	Required	The unexpected item that was received

Returns: AddOveragePayload!

Name	Type	Required	Description
`supply`	Supply▾	Optional	The updated supply

Example#

mutation AddOverage($input: AddOverageInput!) {
  addOverage(input: $input) {
    supply {
      id
      number
      status
      overages {
        sku
        position
      }
    }
  }
}

{
  "input": {
    "id": "sup_2WcN6j",
    "item": {
      "id": "ovg_4YtK1m",
      "sku": "TSHIRT-BLUE-M",
      "position": "A-03-12"
    }
  }
}

addSkuToSupplier#

Link a product SKU to a supplier, so the product can be purchased from that supplier.

Input: AddSkuToSupplierInput!

Name	Type	Required	Description
`sku`	String!	Required	The SKU of the product to link
`supplier_id`	ID!	Required	The ID of the supplier to link the SKU to

Returns: AddSkuToSupplierPayload!

Name	Type	Required	Description
`product`	Product!▾	Required	The linked product
`supplier`	Business!▾	Required	The supplier the SKU was linked to

Example#

mutation AddSkuToSupplier($input: AddSkuToSupplierInput!) {
  addSkuToSupplier(input: $input) {
    product {
      sku
      label
      brand
    }
    supplier {
      id
      name
      email
    }
  }
}

{
  "input": {
    "sku": "TSH-BLK-M",
    "supplier_id": "sup_6JvB3n"
  }
}

approveStockUpdateSubscription#

Confirm a stock update subscription (e.g. a back-in-stock notification) using the confirmation token that was sent to the subscriber.

Input: ApproveStockUpdateSubscriptionInput!

Name	Type	Required	Description
`token`	String!	Required	The confirmation token sent to the subscriber

Returns: ApproveStockUpdateSubscriptionPayload!

Name	Type	Required	Description
`is_successful`	Boolean!	Required	Whether the subscription was successfully approved

Example#

mutation ApproveStockUpdateSubscription($input: ApproveStockUpdateSubscriptionInput!) {
  approveStockUpdateSubscription(input: $input) {
    is_successful
  }
}

{
  "input": {
    "token": "sub_tok_4Zr8pWq1"
  }
}

createReorderNotificationSettings#

Configure scheduled reorder notifications for a warehouse. On the configured weekdays and times, the listed recipients receive an email with reorder advice for the selected businesses.

Input: CreateReorderNotificationSettingsInput!

Name	Type	Required	Description
`id`	String	Optional	Optional ID to assign to the settings record
`is_enabled`	Boolean!	Required	Whether the reorder notifications are active
`warehouse_id`	String!	Required	The ID of the warehouse to generate reorder advice for
`business_ids`	[String]!	Required	IDs of the businesses (suppliers/vendors) to include in the advice
`schedules`	[ReorderNotificationScheduleInput]!▾	Required	When the notification emails are sent
`recipients`	[ReorderNotificationRecipientInput]!▾	Required	Who receives the notification emails

Returns: CreateReorderNotificationSettingsPayload!

Name	Type	Required	Description
`reorder_notification`	ReorderNotification▾	Optional	The created reorder notification settings

Example#

mutation CreateReorderNotificationSettings($input: CreateReorderNotificationSettingsInput!) {
  createReorderNotificationSettings(input: $input) {
    reorder_notification {
      id
      is_enabled
      warehouse {
        id
        label
      }
      schedules {
        week_day
        hour
        minute
        timezone
      }
      recipients {
        email_address
        name
      }
      created_at
    }
  }
}

{
  "input": {
    "is_enabled": true,
    "warehouse_id": "wh_x9k2mQ",
    "business_ids": ["bus_7hFp3W"],
    "schedules": [
      {
        "week_day": 1,
        "hour": 8,
        "minute": 0,
        "time_zone": "Europe/Amsterdam"
      }
    ],
    "recipients": [
      {
        "email": "purchasing@example.com",
        "name": "Purchasing team"
      }
    ]
  }
}

createStockUpdateSubscription#

Subscribe an email address to a back-in-stock notification for a product. The subscriber is notified when the SKU becomes available again on the channel.

Input: CreateStockUpdateSubscriptionInput!

Name	Type	Required	Description
`channel_id`	String	Optional	The sales channel to watch stock on
`email`	String!	Required	Email address to notify when the product is back in stock
`sku`	String!	Required	SKU of the product to watch

Returns: CreateStockUpdateSubscriptionPayload!

Name	Type	Required	Description
`subscription`	StockNotificationSubscription▾	Optional	The created stock notification subscription

Example#

mutation CreateStockUpdateSubscription($input: CreateStockUpdateSubscriptionInput!) {
  createStockUpdateSubscription(input: $input) {
    subscription {
      email
      products {
        sku
        label
      }
      expires_at
      created_at
    }
  }
}

{
  "input": {
    "channel_id": "chn_4rTn8b",
    "email": "customer@example.com",
    "sku": "SKU-001"
  }
}

createSupply#

Start a supply (goods receipt) from one or more announcements. The settings control how received items are processed — plainly registered, distributed to positions, or matched against cross-dock orders or purchases.

Input: CreateSupplyInput!

Name	Type	Required	Description
`id`	String	Optional	Optional ID to assign to the supply
`announcement_ids`	[String]!	Required	The announcements (expected deliveries) this supply receives
`location_id`	String	Optional	The location where the goods are received
`due_at`	Int64	Optional	When the supply is due — Unix timestamp in milliseconds
`settings`	SupplySettingsInput!▾	Required	How received items are processed

Returns: CreateSupplyPayload!

Name	Type	Required	Description
`supply`	Supply▾	Optional	The created supply

Example#

mutation CreateSupply($input: CreateSupplyInput!) {
  createSupply(input: $input) {
    supply {
      id
      number
      state
      due_at
      announcements {
        id
        number
      }
      created_at
    }
  }
}

{
  "input": {
    "announcement_ids": ["ann_3vBn6L"],
    "location_id": "loc_9pDk1S",
    "due_at": 1767225600000,
    "settings": {
      "processing": "MATCH_PURCHASE"
    }
  }
}

removeReorderNotificationSettings#

Delete reorder notification settings by ID, stopping the associated replenishment notifications.

Input: RemoveReorderNotificationSettingsInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the reorder notification settings to remove

Returns: RemoveReorderNotificationSettingsPayload!

Name	Type	Required	Description
`success`	Boolean!	Required	Whether the settings were removed successfully

Example#

mutation RemoveReorderNotificationSettings($input: RemoveReorderNotificationSettingsInput!) {
  removeReorderNotificationSettings(input: $input) {
    success
  }
}

{
  "input": {
    "id": "rns_5QwZ8j"
  }
}

removeSkuFromSupplier#

Unlink a product SKU from a supplier, so the product can no longer be purchased from that supplier.

Input: RemoveSkuFromSupplierInput!

Name	Type	Required	Description
`sku`	String!	Required	The SKU of the product to unlink
`supplier_id`	ID!	Required	The ID of the supplier to remove the SKU from

Returns: RemoveSkuFromSupplierPayload!

Name	Type	Required	Description
`product`	Product!▾	Required	The unlinked product
`supplier`	Business!▾	Required	The supplier the SKU was removed from

Example#

mutation RemoveSkuFromSupplier($input: RemoveSkuFromSupplierInput!) {
  removeSkuFromSupplier(input: $input) {
    product {
      sku
      label
      brand
    }
    supplier {
      id
      name
      email
    }
  }
}

{
  "input": {
    "sku": "TSH-BLK-M",
    "supplier_id": "sup_6JvB3n"
  }
}

removeStockUpdateSubscription#

Remove a stock update subscription using its subscription token, stopping further stock update notifications.

Input: RemoveStockUpdateSubscriptionInput!

Name	Type	Required	Description
`token`	String!	Required	The token identifying the stock update subscription to remove

Returns: RemoveStockUpdateSubscriptionPayload!

Name	Type	Required	Description
`is_successful`	Boolean!	Required	Whether the subscription was removed successfully

Example#

mutation RemoveStockUpdateSubscription($input: RemoveStockUpdateSubscriptionInput!) {
  removeStockUpdateSubscription(input: $input) {
    is_successful
  }
}

{
  "input": {
    "token": "sub_tok_8fKq2Zr41"
  }
}

removeSupply#

Remove a supply record from inventory by its ID.

Input: RemoveSupplyInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the supply to remove

Returns: RemoveSupplyPayload!

Name	Type	Required	Description
`success`	Boolean!	Required	Whether the supply was removed successfully
`removed_supply_id`	String	Optional	The ID of the removed supply

Example#

mutation RemoveSupply($input: RemoveSupplyInput!) {
  removeSupply(input: $input) {
    success
    removed_supply_id
  }
}

{
  "input": {
    "id": "sup_9mKx4Tq"
  }
}

updateReorderNotificationSettings#

Update the reorder notification settings for a warehouse: enable or disable the notifications and set which businesses they cover, when they are sent and who receives them.

Input: UpdateReorderNotificationSettingsInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the reorder notification configuration
`is_enabled`	Boolean!	Required	Whether reorder notifications are enabled
`business_ids`	[String]!	Required	IDs of the businesses the notifications apply to
`schedules`	[ReorderNotificationScheduleInput]!▾	Required	When the notifications are sent
`recipients`	[ReorderNotificationRecipientInput]!▾	Required	Who receives the notifications

Returns: UpdateReorderNotificationSettingsPayload!

Name	Type	Required	Description
`reorder_notification`	ReorderNotification▾	Optional	The updated reorder notification configuration

Example#

mutation UpdateReorderNotificationSettings($input: UpdateReorderNotificationSettingsInput!) {
  updateReorderNotificationSettings(input: $input) {
    reorder_notification {
      id
      is_enabled
      schedules {
        week_day
        hour
        minute
        timezone
      }
      recipients {
        name
        email_address
      }
    }
  }
}

{
  "input": {
    "id": "ron_2xQm9V",
    "is_enabled": true,
    "business_ids": ["bus_7pLk3N"],
    "schedules": [
      { "week_day": 1, "hour": 8, "minute": 0, "time_zone": "Europe/Amsterdam" }
    ],
    "recipients": [
      { "email": "purchasing@example.com", "name": "Purchasing team" }
    ]
  }
}

updateSupply#

Update a supply (an incoming goods run in a warehouse): change its due date and how received items are processed and matched to orders, purchases or cross-dock flows.

Input: UpdateSupplyInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the supply to update
`due_at`	Int64!	Required	Due date as a Unix timestamp in milliseconds
`settings`	UpdateSupplySettingsInput!▾	Required	Processing settings for the supply

Returns: UpdateSupplyPayload!

Name	Type	Required	Description
`supply`	Supply▾	Optional	The updated supply

Example#

mutation UpdateSupply($input: UpdateSupplyInput!) {
  updateSupply(input: $input) {
    supply {
      id
      number
      status
      due_at
      settings {
        processing
      }
    }
  }
}

{
  "input": {
    "id": "sup_8mKd3W",
    "due_at": 1752537600000,
    "settings": {
      "processing": "MATCH_ORDER",
      "orders": {
        "order_by": "CREATED_AT",
        "filters": []
      }
    }
  }
}

Locations#

createLocation#

Create a physical location — such as a store, warehouse site or pickup point — including its address, opening hours and order cut-off times.

Input: CreateLocationInput!

Name	Type	Required	Description
`id`	String	Optional	Optional client-supplied ID for the location
`name`	String!	Required	Name of the location
`address_id`	String	Optional	ID of an existing address to link to the location
`address`	AddressInput▾	Optional	Address to create for the location (alternative to address_id)
`openings`	[LocationOpeningInput]!▾	Required	Opening hours per weekday
`cut_off_times`	[CutOffTimeInput]!▾	Required	Order cut-off time per weekday
`inventory_integration_id`	String	Optional	ID of the inventory management integration for this location

Returns: CreateLocationPayload!

Name	Type	Required	Description
`location`	Location▾	Optional	The created location

Example#

mutation CreateLocation($input: CreateLocationInput!) {
  createLocation(input: $input) {
    location {
      id
      name
      address {
        address_line_1
        locality
        postal_code
        country_code
      }
      created_at
    }
  }
}

{
  "input": {
    "name": "Groningen store",
    "address": {
      "country_code": "NL",
      "locality": "Groningen",
      "postal_code": "9711 LM",
      "thoroughfare": "Herestraat",
      "premise_number": 12
    },
    "openings": [
      {
        "weekday": 1,
        "windows": [{ "start": "09:00", "end": "18:00" }]
      }
    ],
    "cut_off_times": [
      { "weekday": 1, "time": "16:00" }
    ]
  }
}

updateLocation#

Update a location — its name, address, opening hours and carrier cut-off times.

Input: UpdateLocationInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the location to update
`name`	String!	Required	Name of the location
`address_id`	String	Optional	ID of an existing address to use for the location
`address`	AddressInput▾	Optional	The address of the location — alternative to `address_id`
`openings`	[LocationOpeningInput]!▾	Required	Opening hours per weekday
`cut_off_times`	[CutOffTimeInput]!▾	Required	Cut-off times per weekday for same-day processing

Returns: UpdateLocationPayload!

Name	Type	Required	Description
`location`	Location▾	Optional	The updated location

Example#

mutation UpdateLocation($input: UpdateLocationInput!) {
  updateLocation(input: $input) {
    location {
      id
      name
      address {
        address_line_1
        locality
        postal_code
        country_code
      }
      cut_off_times {
        day_of_week
        time
      }
    }
  }
}

{
  "input": {
    "id": "loc_4Wq8bZ",
    "name": "Warehouse Groningen",
    "address": {
      "address_line_1": "Industrieweg 12",
      "locality": "Groningen",
      "postal_code": "9723 AS",
      "country_code": "NL"
    },
    "openings": [
      {
        "weekday": 1,
        "windows": [
          { "start": "09:00", "end": "17:30" }
        ]
      }
    ],
    "cut_off_times": [
      {
        "weekday": 1,
        "time": "16:00"
      }
    ]
  }
}

Delivery & parcels#

addItemsToParcel#

Add order items to a parcel for shipping. When no parcel_id is given, the items are packed into a new parcel; the payload returns both the updated items and the affected parcels.

Input: AddItemsToParcelInput!

Name	Type	Required	Description
`parcel_id`	String	Optional	The ID of an existing parcel to add the items to — omit to create a new parcel
`items`	[String]!	Required	IDs of the items to add to the parcel

Returns: AddItemsToParcelPayload!

Name	Type	Required	Description
`items`	[ParcelItem]!▾	Required	The items that were added
`parcels`	[Parcel]!▾	Required	The affected parcels

Example#

mutation AddItemsToParcel($input: AddItemsToParcelInput!) {
  addItemsToParcel(input: $input) {
    items {
      id
      sku
      label
    }
    parcels {
      id
      number
      status
    }
  }
}

{
  "input": {
    "parcel_id": "prc_8LmV3q",
    "items": ["itm_7GhQ2w", "itm_9KpR4t"]
  }
}

addProviderOptionToItems#

Assign a carrier provider option (a specific carrier service, e.g. a signed or same-day delivery product) to a set of parcel items, so the resulting parcel is shipped with that carrier service.

Input: AddProviderOptionToItems!

Name	Type	Required	Description
`provider_option_id`	String!	Required	The ID of the carrier provider option to apply
`items`	[String]!	Required	The IDs of the items to apply the provider option to

Returns: AddProviderOptionToItemsPayload!

Name	Type	Required	Description
`items`	[ParcelItem]!▾	Required	The updated parcel items
`parcel`	Parcel▾	Optional	The parcel the items belong to
`delivery`	Delivery▾	Optional	The delivery the items are shipped with

Example#

mutation AddProviderOptionToItems($input: AddProviderOptionToItems!) {
  addProviderOptionToItems(input: $input) {
    items {
      id
      sku
      label
      progress
    }
    parcel {
      id
      number
      status
    }
    delivery {
      id
      number
      expected_at
    }
  }
}

{
  "input": {
    "provider_option_id": "pro_2WqK8d",
    "items": ["itm_7hRp2W", "itm_9kTn4B"]
  }
}

addShippingMethodToItems#

Assign a shipping method to a specific set of items on an order, leaving the other items untouched. Use this when different items of one order should ship with different methods.

Input: AddShippingMethodToItemsInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order the items belong to
`items`	[String]!	Required	The IDs of the order items to assign the shipping method to
`shipping_method_id`	String!	Required	The ID of the shipping method to apply

Returns: AddShippingMethodToItemsPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation AddShippingMethodToItems($input: AddShippingMethodToItemsInput!) {
  addShippingMethodToItems(input: $input) {
    order {
      id
      number
      status
      items {
        id
        sku
        label
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "items": ["itm_7hRp2W", "itm_9kTn4B"],
    "shipping_method_id": "shm_3DcF6a"
  }
}

addTrackTraceToItems#

Attach a track & trace number and tracking URL to a set of parcel items, so the shipment can be followed by the customer and in the fulfilment flow.

Input: AddTrackTraceToItemsInput!

Name	Type	Required	Description
`track_trace_url`	String!	Required	The carrier tracking URL for the shipment
`track_trace_number`	String!	Required	The track & trace number issued by the carrier
`items`	[String]!	Required	The IDs of the items the track & trace applies to

Returns: AddTrackTraceToItemsPayload

Name	Type	Required	Description
`parcels`	[Parcel!]!▾	Required	Parcels carrying the updated track & trace
`items`	[CollectionItem!]!▾	Required	Items the track & trace was attached to

Example#

mutation AddTrackTraceToItems($input: AddTrackTraceToItemsInput!) {
  addTrackTraceToItems(input: $input) {
    items {
      id
      sku
      label
      progress
    }
    parcels {
      id
      number
      status
      track_trace {
        number
        url
      }
    }
  }
}

{
  "input": {
    "track_trace_number": "3SABCD123456789",
    "track_trace_url": "https://tracking.example-carrier.com/3SABCD123456789",
    "items": ["itm_7hRp2W", "itm_9kTn4B"]
  }
}

createParcelForDelivery#

Create a parcel for a delivery and assign specific delivery items to it, so the parcel can be announced to a carrier and shipped.

Input: CreateParcelForDeliveryInput!

Name	Type	Required	Description
`delivery_id`	String!	Required	The ID of the delivery to create the parcel for
`items`	[String]!	Required	IDs of the delivery items to pack into the parcel

Returns: CreateParcelForDeliveryPayload

Name	Type	Required	Description
`parcels`	[Parcel!]!▾	Required	Parcels created for the delivery
`items`	[CollectionItem!]!▾	Required	Items assigned to the new parcel

Example#

mutation CreateParcelForDelivery($input: CreateParcelForDeliveryInput!) {
  createParcelForDelivery(input: $input) {
    parcel {
      id
      status
    }
  }
}

{
  "input": {
    "delivery_id": "dlv_8Fq2nW",
    "items": ["ditm_3Vp7kL", "ditm_6Jd4mX"]
  }
}

createShippingLabelForParcel#

Create a shipping label for an existing parcel. Optionally send the label straight to a connected label printer.

Input: CreateShippingLabelForParcelInput!

Name	Type	Required	Description
`parcel_id`	String!	Required	The ID of the parcel to create a shipping label for
`printer_id`	Int64	Optional	ID of the printer to send the label to directly

Returns: CreateShippingLabelForParcelPayload!

Name	Type	Required	Description
`parcel`	Parcel▾	Optional	The parcel including its new label

Example#

mutation CreateShippingLabelForParcel($input: CreateShippingLabelForParcelInput!) {
  createShippingLabelForParcel(input: $input) {
    parcel {
      id
      number
      status
      track_trace {
        url
        number
      }
      labels {
        id
        label_url
        tracking_code
      }
    }
  }
}

{
  "input": {
    "parcel_id": "prc_x9k2mQ",
    "printer_id": 42
  }
}

removeItemsFromParcel#

Remove items from a parcel, for example when repacking a shipment. Returns the updated parcel.

Input: RemoveItemsFromParcelInput!

Name	Type	Required	Description
`parcel_id`	String!	Required	The ID of the parcel to remove the items from
`items`	[String]!	Required	IDs of the items to remove from the parcel

Returns: RemoveItemsFromParcelPayload!

Name	Type	Required	Description
`parcel`	Parcel▾	Optional	The updated parcel

Example#

mutation RemoveItemsFromParcel($input: RemoveItemsFromParcelInput!) {
  removeItemsFromParcel(input: $input) {
    parcel {
      id
      number
      status
      items {
        id
        sku
      }
    }
  }
}

{
  "input": {
    "parcel_id": "prc_8LmV3q",
    "items": ["itm_7GhQ2w", "itm_9KpR4t"]
  }
}

setDeliveryStatusForItems#

Set the delivery status for one or more parcel items. Returns the updated items and the parcels they belong to.

Input: SetDeliveryStatusForItemsInput!

Name	Type	Required	Description
`status`	String!	Required	The delivery status to set on the items
`items`	[String]!	Required	IDs of the items to update

Returns: SetDeliveryStatusForItemsPayload!

Name	Type	Required	Description
`items`	[ParcelItem]!▾	Required	The updated items
`parcels`	[Parcel]!▾	Required	The parcels the items belong to

Example#

mutation SetDeliveryStatusForItems($input: SetDeliveryStatusForItemsInput!) {
  setDeliveryStatusForItems(input: $input) {
    items {
      id
      sku
      label
      progress
    }
    parcels {
      id
      number
      status
    }
  }
}

{
  "input": {
    "status": "DELIVERED",
    "items": ["itm_7GhQ2w", "itm_9KpR4t"]
  }
}

setMethodForDelivery#

Change the shipping method of an existing delivery, for example to switch a shipment to a different carrier service.

Input: SetMethodForDeliveryInput!

Name	Type	Required	Description
`delivery_id`	String!	Required	The ID of the delivery
`method_id`	String!	Required	The ID of the shipping method to set

Returns: SetMethodForDeliveryPayload!

Name	Type	Required	Description
`delivery`	Delivery▾	Optional	The updated delivery

Example#

mutation SetMethodForDelivery($input: SetMethodForDeliveryInput!) {
  setMethodForDelivery(input: $input) {
    delivery {
      id
      number
      status
      method {
        id
        name
      }
      expected_at
      updated_at
    }
  }
}

{
  "input": {
    "delivery_id": "dlv_4mKt8Z",
    "method_id": "shm_2xVb9L"
  }
}

setParcelStatus#

Set the status of a parcel, for example to mark it as delivered or ready to collect. Returns the updated parcel.

Input: SetParcelStatusInput!

Name	Type	Required	Description
`parcel_id`	String!	Required	The ID of the parcel
`status`	ParcelStatus!▾	Required	The status to set

Returns: SetParcelStatusPayload!

Name	Type	Required	Description
`parcel`	Parcel▾	Optional	The updated parcel

Example#

mutation SetParcelStatus($input: SetParcelStatusInput!) {
  setParcelStatus(input: $input) {
    parcel {
      id
      number
      status
      track_trace {
        url
        number
      }
    }
  }
}

{
  "input": {
    "parcel_id": "prc_8LmV3q",
    "status": "DELIVERED"
  }
}

setProviderOptionForDelivery#

Set the carrier (provider) option for a delivery, for example to switch a shipment to a different carrier service. Returns the updated delivery.

Input: SetProviderOptionForDeliveryInput!

Name	Type	Required	Description
`delivery_id`	String!	Required	The ID of the delivery
`provider_option_id`	String!	Required	The ID of the carrier option to use for the delivery
`provider_option_name`	String	Optional	Optional display name for the carrier option

Returns: SetProviderOptionForDeliveryPayload!

Name	Type	Required	Description
`delivery`	Delivery▾	Optional	The updated delivery

Example#

mutation SetProviderOptionForDelivery($input: SetProviderOptionForDeliveryInput!) {
  setProviderOptionForDelivery(input: $input) {
    delivery {
      id
      number
      status
      provider_option {
        id
        name
        carrier
      }
    }
  }
}

{
  "input": {
    "delivery_id": "dlv_6WqN8r",
    "provider_option_id": "pro_2XcJ5m",
    "provider_option_name": "DHL Same Day"
  }
}

setShippingAddressForDelivery#

Set the destination shipping address for a delivery. Provide a pickup point ID (spid), an existing address ID, or a full address object.

Input: SetShippingAddressForDeliveryInput!

Name	Type	Required	Description
`delivery_id`	String!	Required	The ID of the delivery
`spid`	String	Optional	Service point (pickup point) ID to deliver to
`address_id`	String	Optional	ID of an existing address to use
`address`	AddressInput▾	Optional	A new shipping address

Returns: SetShippingAddressForDeliveryPayload!

Name	Type	Required	Description
`delivery`	Delivery▾	Optional	The updated delivery

Example#

mutation SetShippingAddress($input: SetShippingAddressForDeliveryInput!) {
  setShippingAddressForDelivery(input: $input) {
    delivery {
      id
      number
      status
      to {
        address {
          address_line_1
          locality
          postal_code
          country_code
        }
      }
    }
  }
}

{
  "input": {
    "delivery_id": "dlv_5rT8nK",
    "address": {
      "address_line_1": "Keizersgracht 313",
      "locality": "Amsterdam",
      "postal_code": "1016 EE",
      "country_code": "NL",
      "given_name": "Jane",
      "family_name": "Doe"
    }
  }
}

Announcements#

addItemsToAnnouncement#

Add items to an inbound announcement, the notice of goods expected to arrive at a warehouse. Each item is identified by SKU and can carry a specification with cost, batch/serial numbers, weight and expiry.

Input: AddItemsToAnnouncementInput!

Name	Type	Required	Description
`announcement_id`	String!	Required	The ID of the announcement to add the items to
`items`	[AnnouncementItemInput]!▾	Required	The items to add to the announcement

Returns: AddItemsToAnnouncementPayload!

Name	Type	Required	Description
`announcement`	Announcement▾	Optional	The updated announcement

Example#

mutation AddItemsToAnnouncement($input: AddItemsToAnnouncementInput!) {
  addItemsToAnnouncement(input: $input) {
    announcement {
      id
      number
      status
      expected_at
      items {
        id
        sku
        status
      }
    }
  }
}

{
  "input": {
    "announcement_id": "ann_5RwT7k",
    "items": [
      {
        "sku": "TSHIRT-BLUE-M",
        "specification": {
          "cost": {
            "amount": 1250,
            "currency": "EUR"
          },
          "batch_number": "B-2026-114"
        }
      }
    ]
  }
}

createAnnouncement#

Announce an inbound shipment of goods to a warehouse location, for example a purchase delivery from a supplier or vendor. The announcement tells the receiving location what to expect and when.

Input: CreateAnnouncementInput!

Name	Type	Required	Description
`id`	String	Optional	Optional client-supplied ID for the announcement
`description`	String	Optional	Free-form description of the announced delivery
`currency`	Currency▾	Optional	ISO 4217 currency code for the announced goods
`expected_at`	Int64	Optional	Expected arrival time as a Unix timestamp in milliseconds
`buyer_id`	String!	Required	ID of the business buying / receiving the goods
`location_id`	String!	Required	ID of the location where the goods will arrive
`from`	AnnouncementFrom!▾	Required	The party sending the goods

Returns: CreateAnnouncementPayload!

Name	Type	Required	Description
`announcement`	Announcement▾	Optional	The created announcement

Example#

mutation CreateAnnouncement($input: CreateAnnouncementInput!) {
  createAnnouncement(input: $input) {
    announcement {
      id
      number
      state
      description
      expected_at
      created_at
    }
  }
}

{
  "input": {
    "buyer_id": "bsn_4Tk8vN",
    "location_id": "loc_9mB2xQ",
    "description": "Weekly replenishment from main supplier",
    "currency": "EUR",
    "expected_at": 1767187200000,
    "from": {
      "entity_id": "sup_6Pw3rD",
      "entity_type": "SUPPLIER"
    }
  }
}

removeItemsFromAnnouncement#

Remove items from an inbound announcement — the notice of goods expected to arrive at a warehouse. Returns the updated announcement.

Input: RemoveItemsFromAnnouncementInput!

Name	Type	Required	Description
`announcement_id`	String!	Required	The ID of the announcement to remove the items from
`item_ids`	[String]!	Required	IDs of the announcement items to remove

Returns: RemoveItemsFromAnnouncementPayload!

Name	Type	Required	Description
`announcement`	Announcement▾	Optional	The updated announcement

Example#

mutation RemoveItemsFromAnnouncement($input: RemoveItemsFromAnnouncementInput!) {
  removeItemsFromAnnouncement(input: $input) {
    announcement {
      id
      number
      status
      expected_at
      items {
        id
        sku
      }
    }
  }
}

{
  "input": {
    "announcement_id": "ann_5RwT7k",
    "item_ids": ["ani_2FdK9p", "ani_8MzL4v"]
  }
}

setBuyerForAnnouncement#

Change the buying business on an announcement — the inbound shipment notice for a warehouse location. Optionally update the receiving location at the same time.

Input: SetBuyerForAnnouncementInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the announcement
`buyer_id`	String!	Required	ID of the business buying / receiving the goods
`location_id`	String	Optional	ID of the location where the goods will arrive

Returns: SetBuyerForAnnouncementPayload!

Name	Type	Required	Description
`announcement`	Announcement▾	Optional	The updated announcement

Example#

mutation SetBuyerForAnnouncement($input: SetBuyerForAnnouncementInput!) {
  setBuyerForAnnouncement(input: $input) {
    announcement {
      id
      number
      state
      buyer {
        id
        name
      }
      updated_at
    }
  }
}

{
  "input": {
    "id": "ann_2Vw8kR",
    "buyer_id": "bsn_4Tk8vN",
    "location_id": "loc_9mB2xQ"
  }
}

setExpectedDateForAnnouncement#

Update the expected arrival date of an inbound announcement — the notice of goods expected to arrive at a warehouse.

Input: SetExpectedDateForAnnouncementInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the announcement
`expected_at`	Int64!	Required	Expected arrival date — Unix timestamp in milliseconds

Returns: SetExpectedDateForAnnouncementPayload!

Name	Type	Required	Description
`announcement`	Announcement▾	Optional	The updated announcement

Example#

mutation SetExpectedDateForAnnouncement($input: SetExpectedDateForAnnouncementInput!) {
  setExpectedDateForAnnouncement(input: $input) {
    announcement {
      id
      number
      status
      expected_at
      updated_at
    }
  }
}

{
  "input": {
    "id": "ann_5RwT7k",
    "expected_at": 1767225600000
  }
}

setSupplierForAnnouncement#

Set the supplier on an inbound stock announcement, identifying which business the announced goods are coming from.

Input: SetSupplierForAnnouncementInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the announcement
`supplier`	AnnouncementFrom!▾	Required	The supplying entity

Returns: SetSupplierForAnnouncementPayload!

Name	Type	Required	Description
`announcement`	Announcement▾	Optional	The updated announcement

Example#

mutation SetSupplier($input: SetSupplierForAnnouncementInput!) {
  setSupplierForAnnouncement(input: $input) {
    announcement {
      id
      number
      status
      supplier {
        id
        name
      }
      expected_at
    }
  }
}

{
  "input": {
    "id": "ann_3jP7wR",
    "supplier": {
      "entity_id": "bus_6mX2kQ",
      "entity_type": "SUPPLIER"
    }
  }
}

Picklists#

markPicklistItemAsCollected#

Mark a single item on a picklist as collected, registering the warehouse position (for example a collection slot or tote) where it was placed. Returns the updated picklist.

Input: MarkPicklistItemAsCollectedInput!

Name	Type	Required	Description
`picklist_id`	String!	Required	The ID of the picklist
`item_id`	String!	Required	The ID of the picklist item to mark as collected
`position`	String!	Required	The position where the item was collected (e.g. a slot or tote code)

Returns: MarkPicklistItemAsCollectedPayload!

Name	Type	Required	Description
`picklist`	Picklist▾	Optional	The updated picklist

Example#

mutation MarkPicklistItemAsCollected($input: MarkPicklistItemAsCollectedInput!) {
  markPicklistItemAsCollected(input: $input) {
    picklist {
      id
      number
      state
      items {
        id
        sku
        is_collected
      }
    }
  }
}

{
  "input": {
    "picklist_id": "pkl_x9k2mQ",
    "item_id": "pki_5nT3wY",
    "position": "A-01-03"
  }
}

markPicklistItemAsPicked#

Mark a single item on a picklist as picked, for example after it has been taken from its warehouse location. Returns the updated picklist.

Input: MarkPicklistItemAsPickedInput!

Name	Type	Required	Description
`picklist_id`	String!	Required	The ID of the picklist
`item_id`	String!	Required	The ID of the picklist item to mark as picked

Returns: MarkPicklistItemAsPickedPayload!

Name	Type	Required	Description
`picklist`	Picklist▾	Optional	The updated picklist

Example#

mutation MarkPicklistItemAsPicked($input: MarkPicklistItemAsPickedInput!) {
  markPicklistItemAsPicked(input: $input) {
    picklist {
      id
      number
      state
      items {
        id
        sku
        is_picked
      }
    }
  }
}

{
  "input": {
    "picklist_id": "pkl_x9k2mQ",
    "item_id": "pki_5nT3wY"
  }
}

markPicklistItemAsUnpicked#

Revert a picked picklist item back to unpicked, for example when the wrong item was scanned or the item needs to go back to its location. Returns the updated picklist.

Input: MarkPicklistItemAsUnpickedInput!

Name	Type	Required	Description
`picklist_id`	String!	Required	The ID of the picklist
`item_id`	String!	Required	The ID of the picklist item to mark as unpicked

Returns: MarkPicklistItemAsUnpickedPayload!

Name	Type	Required	Description
`picklist`	Picklist▾	Optional	The updated picklist

Example#

mutation MarkPicklistItemAsUnpicked($input: MarkPicklistItemAsUnpickedInput!) {
  markPicklistItemAsUnpicked(input: $input) {
    picklist {
      id
      number
      state
      items {
        id
        sku
        is_picked
      }
    }
  }
}

{
  "input": {
    "picklist_id": "pkl_x9k2mQ",
    "item_id": "pki_5nT3wY"
  }
}

markPicklistItemsAsCollected#

Mark multiple picklist items as collected in one call, registering the warehouse position (for example a collection slot or tote) where they were placed. Returns the updated picklist.

Input: MarkPicklistItemsAsCollectedInput!

Name	Type	Required	Description
`picklist_id`	String!	Required	The ID of the picklist
`items`	[CollectPicklistItemInput]!▾	Required	The picklist items to mark as collected
`position`	String!	Required	The position where the items were collected (e.g. a slot or tote code)

Returns: MarkPicklistItemsAsCollectedPayload!

Name	Type	Required	Description
`picklist`	Picklist▾	Optional	The updated picklist

Example#

mutation MarkPicklistItemsAsCollected($input: MarkPicklistItemsAsCollectedInput!) {
  markPicklistItemsAsCollected(input: $input) {
    picklist {
      id
      number
      state
      items {
        id
        sku
        is_collected
      }
    }
  }
}

{
  "input": {
    "picklist_id": "pkl_x9k2mQ",
    "items": [
      { "item_id": "pki_5nT3wY" },
      { "item_id": "pki_8cVp4z" }
    ],
    "position": "A-01-03"
  }
}

markPicklistItemsAsPicked#

Mark multiple picklist items as picked in one call, for example after they have been taken from their warehouse locations. Returns the updated picklist.

Input: MarkPicklistItemsAsPickedInput!

Name	Type	Required	Description
`picklist_id`	String!	Required	The ID of the picklist
`items`	[PickPicklistItemInput]!▾	Required	The picklist items to mark as picked

Returns: MarkPicklistItemsAsPickedPayload!

Name	Type	Required	Description
`picklist`	Picklist▾	Optional	The updated picklist

Example#

mutation MarkPicklistItemsAsPicked($input: MarkPicklistItemsAsPickedInput!) {
  markPicklistItemsAsPicked(input: $input) {
    picklist {
      id
      number
      state
      items {
        id
        sku
        is_picked
      }
    }
  }
}

{
  "input": {
    "picklist_id": "pkl_x9k2mQ",
    "items": [
      { "item_id": "pki_5nT3wY" },
      { "item_id": "pki_8cVp4z" }
    ]
  }
}

markPicklistItemsAsUnpicked#

Revert one or more items on a warehouse picklist back to the unpicked state, for example when an item was scanned by mistake or needs to be re-picked.

Input: MarkPicklistItemsAsUnpickedInput!

Name	Type	Required	Description
`picklist_id`	String!	Required	The ID of the picklist
`items`	[UnpickPicklistItemInput]!▾	Required	The picklist items to mark as unpicked

Returns: MarkPicklistItemsAsUnpickedPayload!

Name	Type	Required	Description
`picklist`	Picklist▾	Optional	The updated picklist

Example#

mutation MarkPicklistItemsAsUnpicked($input: MarkPicklistItemsAsUnpickedInput!) {
  markPicklistItemsAsUnpicked(input: $input) {
    picklist {
      id
      number
      status
      items {
        id
        sku
        position
        is_picked
      }
    }
  }
}

{
  "input": {
    "picklist_id": "pkl_7Hn3wQr",
    "items": [
      { "item_id": "itm_x9k2mQ" },
      { "item_id": "itm_4Tp8vLc" }
    ]
  }
}

setPicklistTag#

Set a tag on a picklist by picking an option for a tagging key, for example to mark a picklist for a specific carrier cut-off or picking zone. Returns the updated picklist.

Input: SetPicklistTagInput!

Name	Type	Required	Description
`picklist_id`	String!	Required	The ID of the picklist to tag
`key_id`	String!	Required	The ID of the tagging key
`option_id`	String!	Required	The ID of the option to set for the tagging key

Returns: SetPicklistTagPayload!

Name	Type	Required	Description
`picklist`	Picklist▾	Optional	The updated picklist

Example#

mutation SetPicklistTag($input: SetPicklistTagInput!) {
  setPicklistTag(input: $input) {
    picklist {
      id
      number
      state
      tags {
        id
        label
      }
    }
  }
}

{
  "input": {
    "picklist_id": "pkl_x9k2mQ",
    "key_id": "key_3Fp7Lx",
    "option_id": "opt_9RwB5n"
  }
}

Drawers#

closeDrawer#

Close a POS cash drawer, recording the counted (actual) amount and any skimmed amount. Returns the closed drawer together with a closing report.

Input: CloseDrawerInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the drawer to close
`user_id`	String!	Required	The ID of the user closing the drawer
`actual_amount`	Int64!	Required	Counted cash amount in cents
`skimmed_amount`	Int64!	Required	Amount removed (skimmed) from the drawer in cents

Returns: CloseDrawerPayload!

Name	Type	Required	Description
`drawer`	Drawer▾	Optional	The closed drawer
`report`	DrawerReport▾	Optional	The closing report for the drawer session

Example#

mutation CloseDrawer($input: CloseDrawerInput!) {
  closeDrawer(input: $input) {
    drawer {
      id
      label
      status
    }
    report {
      id
      expected_amount
      actual_amount
      skimmed_amount
      closing_amount
    }
  }
}

{
  "input": {
    "id": "drw_3Fh7kNp",
    "user_id": "usr_5tW2rVx",
    "actual_amount": 48250,
    "skimmed_amount": 30000
  }
}

createDrawer#

Create a cash drawer for a point-of-sale channel. A drawer tracks cash amounts across register sessions and can be opened and closed per shift.

Input: CreateDrawerInput!

Name	Type	Required	Description
`id`	String	Optional	Optional client-supplied ID for the drawer
`label`	String!	Required	Display label for the drawer (e.g. "Register 1")
`channel_id`	String!	Required	ID of the POS channel the drawer belongs to

Returns: CreateDrawerPayload!

Name	Type	Required	Description
`drawer`	Drawer▾	Optional	The created drawer

Example#

mutation CreateDrawer($input: CreateDrawerInput!) {
  createDrawer(input: $input) {
    drawer {
      id
      label
      status
      starting_amount
      expected_amount
      created_at
    }
  }
}

{
  "input": {
    "label": "Register 1",
    "channel_id": "chn_5Rw8kP"
  }
}

deleteDrawer#

Delete a POS cash drawer. Returns whether the deletion succeeded.

Input: DeleteDrawerInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the drawer to delete

Returns: DeleteDrawerPayload!

Name	Type	Required	Description
`is_successful`	Boolean!	Required	Whether the drawer was deleted

Example#

mutation DeleteDrawer($input: DeleteDrawerInput!) {
  deleteDrawer(input: $input) {
    is_successful
  }
}

{
  "input": {
    "id": "drw_x9k2mQ"
  }
}

depositIntoDrawer#

Deposit a cash amount into an open POS drawer, with a note explaining the deposit. The drawer's expected amount is increased accordingly.

Input: DepositIntoDrawerInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the drawer to deposit into
`deposit_id`	String	Optional	Optional client-supplied ID for the deposit (for idempotency)
`note`	String!	Required	Note explaining the deposit (e.g. "Change float top-up")
`amount`	Int64!	Required	Amount to deposit in cents

Returns: DepositIntoDrawerPayload!

Name	Type	Required	Description
`drawer`	Drawer▾	Optional	The updated drawer

Example#

mutation DepositIntoDrawer($input: DepositIntoDrawerInput!) {
  depositIntoDrawer(input: $input) {
    drawer {
      id
      label
      status
      expected_amount {
        amount
        formatted
      }
      updated_at
    }
  }
}

{
  "input": {
    "id": "drw_4kNp7Rc",
    "note": "Change float top-up",
    "amount": 5000
  }
}

openDrawer#

Open a POS cash drawer for a new session, recording the counted starting amount. Returns the opened drawer together with the session report.

Input: OpenDrawerInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the drawer to open
`user_id`	String!	Required	The ID of the user opening the drawer
`starting_amount`	Int64!	Required	Counted cash amount at the start of the session, in cents

Returns: OpenDrawerPayload!

Name	Type	Required	Description
`drawer`	Drawer▾	Optional	The opened drawer
`report`	DrawerReport▾	Optional	The report for the opened drawer session

Example#

mutation OpenDrawer($input: OpenDrawerInput!) {
  openDrawer(input: $input) {
    drawer {
      id
      label
      status
      starting_amount {
        amount
        formatted
      }
    }
    report {
      id
      start_at
      starting_amount {
        amount
        formatted
      }
    }
  }
}

{
  "input": {
    "id": "drw_3Fh7kNp",
    "user_id": "usr_5tW2rVx",
    "starting_amount": 15000
  }
}

updateDrawer#

Update the label of a point-of-sale cash drawer.

Input: UpdateDrawerInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the drawer to update
`label`	String!	Required	New display label for the drawer (e.g. "Register 1")

Returns: UpdateDrawerPayload!

Name	Type	Required	Description
`drawer`	Drawer▾	Optional	The updated drawer

Example#

mutation UpdateDrawer($input: UpdateDrawerInput!) {
  updateDrawer(input: $input) {
    drawer {
      id
      label
      status
      updated_at
    }
  }
}

{
  "input": {
    "id": "drw_3Vp9sK",
    "label": "Register 2"
  }
}

withdrawFromDrawer#

Withdraw cash from a POS drawer, recording the amount and a note (for example a bank deposit). Returns the drawer with its updated expected amount.

Input: WithdrawFromDrawerInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the drawer to withdraw from
`withdrawal_id`	String	Optional	Optional ID to reference this withdrawal
`note`	String!	Required	Reason for the withdrawal (e.g. "Cash deposit to bank")
`amount`	Int64!	Required	Amount to withdraw, in cents

Returns: WithdrawFromDrawerPayload!

Name	Type	Required	Description
`drawer`	Drawer▾	Optional	The drawer after the withdrawal

Example#

mutation WithdrawFromDrawer($input: WithdrawFromDrawerInput!) {
  withdrawFromDrawer(input: $input) {
    drawer {
      id
      label
      status
      expected_amount {
        amount
        currency
        formatted
      }
    }
  }
}

{
  "input": {
    "id": "drw_5hPx2S",
    "note": "Cash deposit to bank",
    "amount": 25000
  }
}

Returns (RMA)#

addTrackTraceToReturnItems#

Attach a track & trace number to a set of return items, so the inbound return shipment can be followed until it arrives back at the warehouse.

Input: AddTrackTraceToReturnItemsInput!

Name	Type	Required	Description
`track_trace_number`	String!	Required	The track & trace number issued by the carrier for the return shipment
`items`	[String]!	Required	The IDs of the return items the track & trace applies to

Returns: AddTrackTraceToReturnItemsPayload!

Name	Type	Required	Description
`items`	[CollectionItem]!▾	Required	The updated return items

Example#

mutation AddTrackTraceToReturnItems($input: AddTrackTraceToReturnItemsInput!) {
  addTrackTraceToReturnItems(input: $input) {
    items {
      id
      sku
      label
      status
      is_returned
    }
  }
}

{
  "input": {
    "track_trace_number": "3SABCD987654321",
    "items": ["itm_7hRp2W", "itm_9kTn4B"]
  }
}

attachPhotoToRma#

Attach a photo to an item on an RMA (return), identified by its SKU — for example to document the condition of a returned product.

Input: AttachPhotoToRmaInput!

Name	Type	Required	Description
`rma_id`	String!	Required	The ID of the RMA
`sku`	String!	Required	SKU of the RMA item to attach the photo to
`photo`	Upload!▾	Required	The photo file to upload

Returns: AttachPhotoToRmaPayload!

Name	Type	Required	Description
`rma`	Rma▾	Optional	The updated RMA

Example#

mutation AttachPhotoToRma($input: AttachPhotoToRmaInput!) {
  attachPhotoToRma(input: $input) {
    rma {
      id
      number
      status
      items {
        id
        is_received
      }
    }
  }
}

{
  "input": {
    "rma_id": "rma_6Yw3nBq",
    "sku": "SKU-001-BLK",
    "photo": null
  }
}

authorizeRmaItems#

Authorize or reject individual items on an RMA (return), optionally marking them as received and adding notes for the contact or vendor.

Input: AuthorizeRmaItemsInput!

Name	Type	Required	Description
`rma_id`	String!	Required	The ID of the RMA
`items`	[AuthorizeRmaItemInput]!▾	Required	The RMA items to update

Returns: AuthorizeRmaItemsPayload!

Name	Type	Required	Description
`rma`	Rma▾	Optional	The updated RMA

Example#

mutation AuthorizeRmaItems($input: AuthorizeRmaItemsInput!) {
  authorizeRmaItems(input: $input) {
    rma {
      id
      number
      status
      items {
        id
        status
        is_received
      }
    }
  }
}

{
  "input": {
    "rma_id": "rma_6Yw3nBq",
    "items": [
      {
        "id": "rmi_1cV8sLp",
        "status": "AUTHORIZED",
        "is_received": true,
        "vendor_note": "Item received in good condition"
      }
    ]
  }
}

createRma#

Create a new RMA (return merchandise authorisation) to register a customer return. The RMA starts empty — add the returned products with createRmaItems.

Input: CreateRmaInput!

Name	Type	Required	Description
`id`	String	Optional	Optional ID to assign to the RMA
`contact_id`	String	Optional	The contact returning the goods
`organisation_id`	String	Optional	The organisation returning the goods
`channel_id`	String	Optional	The sales channel the return belongs to
`due_at`	Int64	Optional	When the return is due — Unix timestamp in milliseconds
`status`	RmaStatus▾	Optional	Initial status of the RMA

Returns: CreateRmaPayload!

Name	Type	Required	Description
`rma`	Rma▾	Optional	The created RMA

Example#

mutation CreateRma($input: CreateRmaInput!) {
  createRma(input: $input) {
    rma {
      id
      number
      status
      due_at
      contact {
        id
        email
      }
      created_at
    }
  }
}

{
  "input": {
    "contact_id": "cnt_8kQw2p",
    "channel_id": "chn_4rTn8b",
    "due_at": 1767225600000,
    "status": "OPEN"
  }
}

createRmaItems#

Add returned products to an existing RMA. Each item links a SKU to the original order it was bought on, optionally with a return reason and a note from the customer.

Input: CreateRmaItemsInput!

Name	Type	Required	Description
`rma_id`	String!	Required	The ID of the RMA to add items to
`items`	[CreateRmaItemInput]!▾	Required	The products being returned

Returns: CreateRmaItemsPayload!

Name	Type	Required	Description
`rma`	Rma▾	Optional	The updated RMA including the new items

Example#

mutation CreateRmaItems($input: CreateRmaItemsInput!) {
  createRmaItems(input: $input) {
    rma {
      id
      number
      status
      items {
        id
        is_received
        contact_note
      }
      updated_at
    }
  }
}

{
  "input": {
    "rma_id": "rma_x9k2mQ",
    "items": [
      {
        "sku": "SKU-001",
        "order_id": "ord_5tGh7Y",
        "reason": "SIZE_TOO_SMALL",
        "contact_note": "Would like to exchange for a size L"
      }
    ]
  }
}

createRmaLabel#

Generate a return shipping label for an RMA through a shipping integration. The label is created for the selected carrier option and covers the returned items from the given orders.

Input: CreateRmaLabelInput!

Name	Type	Required	Description
`rma_id`	String!	Required	The ID of the RMA to create a label for
`id`	String	Optional	Optional ID to assign to the label
`integration_id`	String!	Required	The shipping integration that generates the label
`email`	String!	Required	Email address of the customer shipping the return
`option_id`	String!	Required	The carrier option to ship the return with
`meta_data`	JsonObject▾	Optional	Arbitrary metadata to attach to the label
`order_ids`	[String]!	Required	The orders whose items are covered by this return label

Returns: CreateRmaLabelPayload!

Name	Type	Required	Description
`rma`	Rma▾	Optional	The updated RMA

Example#

mutation CreateRmaLabel($input: CreateRmaLabelInput!) {
  createRmaLabel(input: $input) {
    rma {
      id
      number
      status
      provider_option {
        id
        name
        carrier
      }
      updated_at
    }
  }
}

{
  "input": {
    "rma_id": "rma_x9k2mQ",
    "integration_id": "int_2wEr9K",
    "email": "customer@example.com",
    "option_id": "opt_6yUj4N",
    "order_ids": ["ord_5tGh7Y"]
  }
}

deleteRma#

Permanently delete an RMA (return merchandise authorisation) by ID.

Input: DeleteRmaInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the RMA to delete

Returns: DeleteRmaPayload!

Name	Type	Required	Description
`is_successful`	Boolean!	Required	Whether the RMA was deleted successfully

Example#

mutation DeleteRma($input: DeleteRmaInput!) {
  deleteRma(input: $input) {
    is_successful
  }
}

{
  "input": {
    "id": "rma_6xPn4Tq"
  }
}

deleteRmaItems#

Remove one or more items from an RMA (return merchandise authorisation). Returns the updated RMA without the removed items.

Input: DeleteRmaItemsInput!

Name	Type	Required	Description
`rma_id`	String!	Required	The ID of the RMA to remove items from
`items`	[String]!	Required	IDs of the RMA items to remove

Returns: DeleteRmaItemsPayload!

Name	Type	Required	Description
`rma`	Rma▾	Optional	The updated RMA

Example#

mutation DeleteRmaItems($input: DeleteRmaItemsInput!) {
  deleteRmaItems(input: $input) {
    rma {
      id
      number
      status
      items {
        id
        is_received
      }
      updated_at
    }
  }
}

{
  "input": {
    "rma_id": "rma_6xPn4Tq",
    "items": ["rmi_9wLk2Vd", "rmi_3cHt7Jm"]
  }
}

reviewRma#

Review a return (RMA) by authorizing or rejecting the returned quantities per SKU, optionally with a note per decision.

Input: ReviewRmaInput!

Name	Type	Required	Description
`rma_id`	String!	Required	The ID of the RMA to review
`decisions`	[RmaDecision]!▾	Required	One decision per SKU being reviewed

Returns: ReviewRmaPayload!

Name	Type	Required	Description
`rma`	Rma▾	Optional	The reviewed RMA

Example#

mutation ReviewRma($input: ReviewRmaInput!) {
  reviewRma(input: $input) {
    rma {
      id
      number
      status
      updated_at
    }
  }
}

{
  "input": {
    "rma_id": "rma_7Hn3Pw",
    "decisions": [
      {
        "sku": "TSH-BLK-M",
        "quantity": 1,
        "status": "AUTHORIZED",
        "note": "Item received in original condition"
      }
    ]
  }
}

sendReturnEmail#

Send a return confirmation email to the customer for specific items of an order.

Input: SendReturnEmailInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`item_ids`	[String]!	Required	The IDs of the returned order items to include in the email

Returns: SendReturnEmailPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The order the email was sent for

Example#

mutation SendReturnEmail($input: SendReturnEmailInput!) {
  sendReturnEmail(input: $input) {
    order {
      id
      number
      status
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "item_ids": ["itm_4Fq8Zw"]
  }
}

setProviderOptionForRma#

Set the carrier (provider) option a return (RMA) will be shipped back with. Returns the updated RMA.

Input: SetProviderOptionForRmaInput!

Name	Type	Required	Description
`rma_id`	String!	Required	The ID of the RMA
`provider_option`	ProviderOptionOnRmaInput!▾	Required	The carrier option to use for the return shipment

Returns: SetProviderOptionForRmaPayload!

Name	Type	Required	Description
`rma`	Rma▾	Optional	The updated RMA

Example#

mutation SetProviderOptionForRma($input: SetProviderOptionForRmaInput!) {
  setProviderOptionForRma(input: $input) {
    rma {
      id
      number
      status
      provider_option {
        id
        name
        carrier
      }
    }
  }
}

{
  "input": {
    "rma_id": "rma_7Hn3Pw",
    "provider_option": {
      "id": "pro_2XcJ5m",
      "name": "PostNL Standard Return",
      "integration_id": "int_4Yt8vN"
    }
  }
}

setReturnMethodForRma#

Assign a return method to an RMA (return merchandise authorisation), determining how the customer sends the items back.

Input: SetReturnMethodForRmaInput!

Name	Type	Required	Description
`rma_id`	String!	Required	The ID of the RMA
`return_method_id`	String!	Required	The ID of the return method to use

Returns: SetReturnMethodForRmaPayload!

Name	Type	Required	Description
`rma`	Rma▾	Optional	The updated RMA

Example#

mutation SetReturnMethod($input: SetReturnMethodForRmaInput!) {
  setReturnMethodForRma(input: $input) {
    rma {
      id
      number
      status
      return_method {
        id
        name
        carrier
      }
    }
  }
}

{
  "input": {
    "rma_id": "rma_4tW8nP",
    "return_method_id": "rtm_9xK2mQ"
  }
}

startItemReturnProcess#

Start the return process for one or more items on an order. Optionally pass a contra_id per item to link the return to a contra (compensating) item.

Input: StartItemReturnProcessInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order the items belong to
`location_id`	String	Optional	Location where the return is processed
`items`	[ItemReturnProcessInput]!▾	Required	The items to return

Returns: StartItemReturnProcessPayload!

Name	Type	Required	Description
`items`	[CollectionItem]!▾	Required	The items with the return process started

Example#

mutation StartItemReturn($input: StartItemReturnProcessInput!) {
  startItemReturnProcess(input: $input) {
    items {
      id
      sku
      label
      status
      is_returned
    }
  }
}

{
  "input": {
    "order_id": "ord_2kV8mT",
    "location_id": "loc_5nB4wJ",
    "items": [
      { "id": "itm_7hK3mR" }
    ]
  }
}

updateRma#

Update an RMA (return merchandise authorisation): change its status, the linked contact or organisation, the return address, or the due date. Only the fields you provide are changed.

Input: UpdateRmaInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the RMA to update
`status`	RmaStatus▾	Optional	New status for the RMA
`address_id`	String	Optional	ID of the return address
`contact_id`	String	Optional	ID of the contact the RMA belongs to
`organisation_id`	String	Optional	ID of the organisation the RMA belongs to
`due_at`	Int64	Optional	Due date as a Unix timestamp in milliseconds

Returns: UpdateRmaPayload!

Name	Type	Required	Description
`rma`	Rma▾	Optional	The updated RMA

Example#

mutation UpdateRma($input: UpdateRmaInput!) {
  updateRma(input: $input) {
    rma {
      id
      number
      status
      due_at
      items {
        id
        reason
        is_received
      }
    }
  }
}

{
  "input": {
    "id": "rma_6tYw4J",
    "status": "OPEN",
    "due_at": 1751932800000
  }
}

updateRmaItems#

Update items on an RMA, for example to change the return reason or the customer note per item.

Input: UpdateRmaItemsInput!

Name	Type	Required	Description
`rma_id`	String!	Required	The ID of the RMA the items belong to
`items`	[UpdateRmaItemInput]!▾	Required	Items to update

Returns: UpdateRmaItemsPayload!

Name	Type	Required	Description
`rma`	Rma▾	Optional	The RMA with the updated items

Example#

mutation UpdateRmaItems($input: UpdateRmaItemsInput!) {
  updateRmaItems(input: $input) {
    rma {
      id
      number
      status
      items {
        id
        reason
        status
        contact_note
      }
    }
  }
}

{
  "input": {
    "rma_id": "rma_6tYw4J",
    "items": [
      {
        "id": "rmi_2cVb8L",
        "reason": "SIZE_TOO_SMALL",
        "contact_note": "Fits too tight, I need one size up"
      }
    ]
  }
}

Reservations#

createReservation#

Reserve stock in a warehouse for a customer. The reservation claims the requested quantities of each SKU for a business and sales channel until it expires.

Input: CreateReservationInput!

Name	Type	Required	Description
`id`	String	Optional	Optional ID to assign to the reservation
`notes`	String	Optional	Free-form notes on the reservation
`customer`	SetReservationContactInput!▾	Required	The customer the stock is reserved for — pass an existing contact ID or a new contact
`channel_id`	String!	Required	The sales channel the reservation is made through
`warehouse_id`	String!	Required	The warehouse to reserve stock in
`business_id`	String!	Required	The business the stock is reserved for
`expires_at`	Int64!	Required	When the reservation expires — Unix timestamp in milliseconds
`items`	[ReservationItemInput]!▾	Required	The SKUs and quantities to reserve

Returns: CreateReservationPayload!

Name	Type	Required	Description
`reservation`	Reservation▾	Optional	The created reservation

Example#

mutation CreateReservation($input: CreateReservationInput!) {
  createReservation(input: $input) {
    reservation {
      id
      number
      notes
      items {
        quantity
      }
      expires_at
      created_at
    }
  }
}

{
  "input": {
    "customer": {
      "contact_id": "cnt_8kQw2p"
    },
    "channel_id": "chn_4rTn8b",
    "warehouse_id": "wh_x9k2mQ",
    "business_id": "bus_7hFp3W",
    "expires_at": 1767225600000,
    "items": [
      { "sku": "SKU-001", "quantity": 2 }
    ],
    "notes": "Hold for pickup on Friday"
  }
}

removeReservation#

Remove a stock reservation by its ID, releasing the items it holds at the warehouse.

Input: RemoveReservationInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the reservation to remove

Returns: RemoveReservationPayload!

Name	Type	Required	Description
`success`	Boolean!	Required	Whether the reservation was removed successfully

Example#

mutation RemoveReservation($input: RemoveReservationInput!) {
  removeReservation(input: $input) {
    success
  }
}

{
  "input": {
    "id": "res_x9k2mQ"
  }
}

setContactForReservation#

Set the customer on a stock reservation — either by referencing an existing contact by ID or by supplying a new contact to create.

Input: SetContactForReservationInput!

Name	Type	Required	Description
`reservation_id`	String!	Required	The ID of the reservation
`customer`	SetReservationContactInput!▾	Required	The customer to set on the reservation — pass an existing contact ID or a new contact

Returns: SetContactForReservationPayload!

Name	Type	Required	Description
`reservation`	Reservation▾	Optional	The updated reservation

Example#

mutation SetContactForReservation($input: SetContactForReservationInput!) {
  setContactForReservation(input: $input) {
    reservation {
      id
      number
      contact {
        id
        name
        email
      }
      expires_at
      updated_at
    }
  }
}

{
  "input": {
    "reservation_id": "rsv_3Np7dK",
    "customer": {
      "contact_id": "cnt_8kQw2p"
    }
  }
}

setNotesForReservation#

Set the notes on a stock reservation. The notes replace any previously set notes.

Input: SetNotesForReservationInput!

Name	Type	Required	Description
`reservation_id`	String!	Required	The ID of the reservation
`notes`	String!	Required	The notes to set on the reservation

Returns: SetNotesForReservationPayload!

Name	Type	Required	Description
`reservation`	Reservation▾	Optional	The updated reservation

Example#

mutation SetNotesForReservation($input: SetNotesForReservationInput!) {
  setNotesForReservation(input: $input) {
    reservation {
      id
      number
      notes
      expires_at
      updated_at
    }
  }
}

{
  "input": {
    "reservation_id": "rsv_6bNc3F",
    "notes": "Customer will collect the items on Friday."
  }
}

setReferencingNumberForReservation#

Set or update the external referencing number on a stock reservation, so you can link the reservation to a record in your own system (e.g. a quote or order number).

Input: SetReferencingNumberForReservationInput!

Name	Type	Required	Description
`reservation_id`	String!	Required	The ID of the reservation to update
`referencing_number`	String!	Required	Your external reference number to attach to the reservation

Returns: SetReferencingNumberForReservationPayload!

Name	Type	Required	Description
`reservation`	Reservation▾	Optional	The updated reservation

Example#

mutation SetReferencingNumber($input: SetReferencingNumberForReservationInput!) {
  setReferencingNumberForReservation(input: $input) {
    reservation {
      id
      number
      referencing_number
      expires_at
      items {
        quantity
      }
    }
  }
}

{
  "input": {
    "reservation_id": "rsv_8kQ2mX",
    "referencing_number": "QUOTE-2026-0042"
  }
}

Services#

createService#

Define a new service — such as gift wrapping, customisation or assembly — that can be offered on order items. The schema describes the configuration options a customer can choose when adding the service.

Input: CreateServiceInput!

Name	Type	Required	Description
`id`	ID	Optional	Optional ID to assign to the service
`name`	String!	Required	Service name (default locale)
`description`	String!	Required	Description shown to the customer
`instruction`	String!	Required	Instruction for the warehouse on how to perform the service
`i18n`	[InternationalizationInput]!▾	Required	Localised name, description and instruction per locale
`type`	ServiceType!▾	Required	The kind of service
`priority`	Int	Optional	Execution priority relative to other services
`schema`	JsonObject!▾	Required	JSON schema describing the configurable options of the service

Returns: CreateServicePayload!

Name	Type	Required	Description
`service`	Service▾	Optional	The created service

Example#

mutation CreateService($input: CreateServiceInput!) {
  createService(input: $input) {
    service {
      id
      name
      type
      priority
      version
      created_at
    }
  }
}

{
  "input": {
    "name": "Gift wrapping",
    "description": "Have your order wrapped as a present",
    "instruction": "Wrap the item in the branded gift paper and add a ribbon",
    "i18n": [
      {
        "locale": "nl-NL",
        "name": "Cadeauverpakking",
        "description": "Laat je bestelling inpakken als cadeau",
        "instruction": "Verpak het artikel in het cadeaupapier en voeg een lint toe"
      }
    ],
    "type": "GIFTWRAP",
    "priority": 1,
    "schema": {
      "type": "object",
      "properties": {
        "message": { "type": "string", "title": "Gift message" }
      }
    }
  }
}

markServiceTaskAsFailed#

Mark a service task on an order item (e.g. engraving, assembly or another value-added service) as failed, indicating the task could not be completed.

Input: MarkServiceTaskAsFailedInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the service task to mark as failed

Returns: MarkServiceTaskAsFailedPayload!

Name	Type	Required	Description
`task`	ServiceItemTask▾	Optional	The updated service task

Example#

mutation MarkServiceTaskAsFailed($input: MarkServiceTaskAsFailedInput!) {
  markServiceTaskAsFailed(input: $input) {
    task {
      id
      status
      started_at
      ended_at
      service {
        id
        name
      }
      order_item {
        id
        sku
      }
    }
  }
}

{
  "input": {
    "id": "tsk_9Bv4nRe"
  }
}

markServiceTaskAsFinished#

Mark a service task on an order item (e.g. engraving, assembly or another value-added service) as finished, recording when work on the task was completed.

Input: MarkServiceTaskAsFinishedInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the service task to mark as finished

Returns: MarkServiceTaskAsFinishedPayload!

Name	Type	Required	Description
`task`	ServiceItemTask▾	Optional	The updated service task

Example#

mutation MarkServiceTaskAsFinished($input: MarkServiceTaskAsFinishedInput!) {
  markServiceTaskAsFinished(input: $input) {
    task {
      id
      status
      started_at
      ended_at
      service {
        id
        name
      }
      order_item {
        id
        sku
      }
    }
  }
}

{
  "input": {
    "id": "tsk_9Bv4nRe"
  }
}

markServiceTaskAsStarted#

Mark a service task on an order item (e.g. engraving, assembly or another value-added service) as started, recording when work on the task began.

Input: MarkServiceTaskAsStartedInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the service task to mark as started

Returns: MarkServiceTaskAsStartedPayload!

Name	Type	Required	Description
`task`	ServiceItemTask▾	Optional	The updated service task

Example#

mutation MarkServiceTaskAsStarted($input: MarkServiceTaskAsStartedInput!) {
  markServiceTaskAsStarted(input: $input) {
    task {
      id
      status
      started_at
      service {
        id
        name
      }
      order_item {
        id
        sku
      }
    }
  }
}

{
  "input": {
    "id": "tsk_9Bv4nRe"
  }
}

removeService#

Delete a service definition — such as gift wrapping or installation — by its ID.

Input: RemoveServiceInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the service to remove

Returns: RemoveServicePayload!

Name	Type	Required	Description
`is_successful`	Boolean!	Required	Whether the service was removed successfully

Example#

mutation RemoveService($input: RemoveServiceInput!) {
  removeService(input: $input) {
    is_successful
  }
}

{
  "input": {
    "id": "svc_6HrT3m"
  }
}

sortServices#

Reorder the services (e.g. gift wrapping, assembly, customisation) by passing their IDs in the desired priority order.

Input: SortServicesInput!

Name	Type	Required	Description
`ids`	[ID]!	Required	Service IDs in the desired order — the position in the array determines the priority

Returns: SortServicesPayload!

Name	Type	Required	Description
`services`	[Service]!▾	Required	The services in their new order

Example#

mutation SortServices($input: SortServicesInput!) {
  sortServices(input: $input) {
    services {
      id
      name
      type
      priority
    }
  }
}

{
  "input": {
    "ids": ["srv_x9k2mQ", "srv_4bT7nW", "srv_8pL3vD"]
  }
}

updateService#

Update a service (such as gift wrapping, assembly or customisation): its name, description, instruction, translations, priority and configuration schema.

Input: UpdateServiceInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the service to update
`name`	String!	Required	Name of the service
`description`	String!	Required	Description of the service
`instruction`	String!	Required	Instruction shown when the service is applied
`i18n`	[InternationalizationInput]!▾	Required	Translations per locale
`priority`	Int	Optional	Priority used to order services
`schema`	JsonObject!	Required	JSON schema describing the configuration options for the service

Returns: UpdateServicePayload!

Name	Type	Required	Description
`service`	Service▾	Optional	The updated service

Example#

mutation UpdateService($input: UpdateServiceInput!) {
  updateService(input: $input) {
    service {
      id
      name
      type
      description
      instruction
      priority
      updated_at
    }
  }
}

{
  "input": {
    "id": "svc_4nRt7X",
    "name": "Gift wrapping",
    "description": "Wrap the item in festive gift paper",
    "instruction": "Add a personal message of up to 120 characters",
    "i18n": [
      {
        "locale": "nl-NL",
        "name": "Cadeauverpakking",
        "description": "Verpak het artikel in feestelijk cadeaupapier",
        "instruction": "Voeg een persoonlijk bericht toe van maximaal 120 tekens"
      }
    ],
    "priority": 10,
    "schema": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 120 } } }
  }
}

Projects#

createProject#

Create a project — a time-boxed container for orders tied to an audience, such as a B2B ordering window — with an optional organisation, shipping addresses and metadata.

Input: CreateProjectInput!

Name	Type	Required	Description
`id`	String	Optional	Optional client-supplied ID for the project
`audience_id`	String!	Required	ID of the audience the project belongs to
`name`	String!	Required	Name of the project
`description`	String	Optional	Description of the project
`organisation_id`	String	Optional	ID of the organisation the project is for
`shipping`	[CreateProjectShippingAddressInput]▾	Optional	Shipping addresses available within the project
`metadata`	JsonObject▾	Optional	Arbitrary metadata for the project
`starts_at`	Int64!	Required	Project start as a Unix timestamp in milliseconds
`ends_at`	Int64!	Required	Project end as a Unix timestamp in milliseconds

Returns: CreateProjectPayload!

Name	Type	Required	Description
`project`	Project▾	Optional	The created project

Example#

mutation CreateProject($input: CreateProjectInput!) {
  createProject(input: $input) {
    project {
      id
      number
      name
      description
      starts_at
      ends_at
      audience {
        id
        name
      }
    }
  }
}

{
  "input": {
    "audience_id": "aud_2Hn6tW",
    "name": "Spring staff uniforms 2026",
    "description": "Ordering window for spring uniforms",
    "organisation_id": "org_7Lp4cV",
    "starts_at": 1772323200000,
    "ends_at": 1774915200000
  }
}

deleteProject#

Permanently delete a project by ID.

Input: DeleteProjectInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the project to delete

Returns: DeleteProjectPayload!

Name	Type	Required	Description
`is_successful`	Boolean!	Required	Whether the project was deleted successfully

Example#

mutation DeleteProject($input: DeleteProjectInput!) {
  deleteProject(input: $input) {
    is_successful
  }
}

{
  "input": {
    "id": "prj_2mKq8Wx"
  }
}

updateProject#

Update an existing project's details, such as its name, description, linked organisation, shipping addresses and start/end dates. Only the fields you provide are changed.

Input: UpdateProjectInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the project to update
`name`	String	Optional	New name for the project
`description`	String	Optional	New description
`organisation_id`	String	Optional	ID of the organisation the project belongs to
`shipping`	[CreateProjectShippingAddressInput]▾	Optional	Shipping addresses for the project
`metadata`	JsonObject	Optional	Arbitrary JSON metadata to store on the project
`starts_at`	Int64	Optional	Project start as a Unix timestamp in milliseconds
`ends_at`	Int64	Optional	Project end as a Unix timestamp in milliseconds

Returns: UpdateProjectPayload!

Name	Type	Required	Description
`project`	Project▾	Optional	The updated project

Example#

mutation UpdateProject($input: UpdateProjectInput!) {
  updateProject(input: $input) {
    project {
      id
      number
      name
      description
      starts_at
      ends_at
    }
  }
}

{
  "input": {
    "id": "prj_k2Bv9Q",
    "name": "Office refurbishment 2026",
    "description": "Furniture and fittings for the new Amsterdam office",
    "starts_at": 1767225600000,
    "ends_at": 1782950400000
  }
}

updateProjectContacts#

Replace the set of contacts linked to a project. The provided list of contact IDs becomes the project's full contact list.

Input: UpdateProjectContactsInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the project
`contacts`	[String]!	Required	IDs of the contacts to link to the project

Returns: UpdateProjectContactsPayload!

Name	Type	Required	Description
`project`	Project▾	Optional	The updated project

Example#

mutation UpdateProjectContacts($input: UpdateProjectContactsInput!) {
  updateProjectContacts(input: $input) {
    project {
      id
      number
      name
      contacts {
        id
        name
        email
      }
    }
  }
}

{
  "input": {
    "id": "prj_k2Bv9Q",
    "contacts": ["cnt_8dHw2K", "cnt_5rTz7P"]
  }
}

Agreements#

createAgreement#

Create a payment agreement — such as a down payment, post-paid or cash-on-delivery arrangement — with one or more conditions that define how and when amounts become due.

Input: CreateAgreementInput!

Name	Type	Required	Description
`id`	ID	Optional	Optional client-supplied ID for the agreement
`is_default_enabled`	Boolean!	Required	Whether the agreement is enabled by default
`enabled_rule_set_id`	ID	Optional	ID of a rule set that determines when the agreement is enabled
`type`	AgreementType!▾	Required	The kind of agreement
`conditions`	[AgreementConditionInput]!▾	Required	Payment conditions that make up the agreement
`name`	String!	Required	Name of the agreement
`instruction`	String	Optional	Instruction text shown to the customer
`description`	String	Optional	Description of the agreement
`i18n`	[InternationalizationInput]!▾	Required	Localized name, description and instruction per locale

Returns: CreateAgreementPayload!

Name	Type	Required	Description
`agreement`	Agreement▾	Optional	The created agreement

Example#

mutation CreateAgreement($input: CreateAgreementInput!) {
  createAgreement(input: $input) {
    agreement {
      id
      name
      type
      is_default_enabled
      conditions {
        type
        amount
        is_percentage
      }
      created_at
    }
  }
}

{
  "input": {
    "name": "30% down payment",
    "type": "DOWN_PAYMENT",
    "is_default_enabled": true,
    "conditions": [
      {
        "type": "DOWN_PAYMENT",
        "amount": 30,
        "is_percentage": true
      }
    ],
    "i18n": [
      {
        "locale": "nl-NL",
        "name": "30% aanbetaling",
        "description": "Betaal 30% vooraf, de rest bij levering.",
        "instruction": "Voldoe de aanbetaling om de bestelling te bevestigen."
      }
    ]
  }
}

removeAgreement#

Delete an agreement by its ID. Returns whether the removal succeeded.

Input: RemoveAgreementInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the agreement to remove

Returns: RemoveAgreementPayload!

Name	Type	Required	Description
`is_success`	Boolean!	Required	Whether the agreement was removed successfully

Example#

mutation RemoveAgreement($input: RemoveAgreementInput!) {
  removeAgreement(input: $input) {
    is_success
  }
}

{
  "input": {
    "id": "agr_3KpN9v"
  }
}

removeAgreementTemplateForCart#

Remove the agreement template that was set on a cart, so no agreement is generated from it for that cart.

Input: RemoveAgreementTemplateForCartInput!

Name	Type	Required	Description
`cart_id`	String!	Required	The ID of the cart

Returns: RemoveAgreementTemplateForCartPayload!

Name	Type	Required	Description
`cart`	Cart▾	Optional	The updated cart

Example#

mutation RemoveAgreementTemplateForCart($input: RemoveAgreementTemplateForCartInput!) {
  removeAgreementTemplateForCart(input: $input) {
    cart {
      id
      number
      total {
        amount
        formatted
      }
      updated_at
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a"
  }
}

removeAgreementTemplateForOrder#

Remove the agreement template that was set on an order, so no agreement is generated from it for that order.

Input: RemoveAgreementTemplateForOrderInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order

Returns: RemoveAgreementTemplateForOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation RemoveAgreementTemplateForOrder($input: RemoveAgreementTemplateForOrderInput!) {
  removeAgreementTemplateForOrder(input: $input) {
    order {
      id
      number
      status
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ"
  }
}

setAgreementTemplateForCart#

Attach an agreement template to a cart, so the customer is asked to accept the agreement during checkout.

Input: SetAgreementTemplateForCartInput!

Name	Type	Required	Description
`cart_id`	ID!	Required	The ID of the cart
`agreement_id`	ID!	Required	The ID of the agreement template to attach

Returns: SetAgreementTemplateForCartPayload!

Name	Type	Required	Description
`cart`	Cart▾	Optional	The updated cart

Example#

mutation SetAgreementTemplateForCart($input: SetAgreementTemplateForCartInput!) {
  setAgreementTemplateForCart(input: $input) {
    cart {
      id
      number
      total {
        amount
        formatted
      }
      updated_at
    }
  }
}

{
  "input": {
    "cart_id": "72fca344-2a6f-4c3e-b4ca-029920b2522a",
    "agreement_id": "agr_5Tk9Wn"
  }
}

setAgreementTemplateForOrder#

Attach an agreement template to an order, so the customer is asked to accept the agreement as part of the order.

Input: SetAgreementTemplateForOrderInput!

Name	Type	Required	Description
`order_id`	ID!	Required	The ID of the order
`agreement_id`	ID!	Required	The ID of the agreement template to attach

Returns: SetAgreementTemplateForOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation SetAgreementTemplateForOrder($input: SetAgreementTemplateForOrderInput!) {
  setAgreementTemplateForOrder(input: $input) {
    order {
      id
      number
      status
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "agreement_id": "agr_5Tk9Wn"
  }
}

setAgreementsForOrder#

Set the payment agreements for an order, such as a down payment, post-paid terms, cash on delivery or marketplace settlement. Each agreement defines an amount (or percentage) and when it becomes due.

Input: SetAgreementsForOrderInput!

Name	Type	Required	Description
`order_id`	ID!	Required	The ID of the order
`agreements`	[AgreementInput]!▾	Required	The payment agreements to set on the order

Returns: SetAgreementsForOrderPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The updated order

Example#

mutation SetAgreementsForOrder($input: SetAgreementsForOrderInput!) {
  setAgreementsForOrder(input: $input) {
    order {
      id
      number
      total {
        amount
        formatted
      }
      status
      updated_at
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "agreements": [
      {
        "type": "DOWN_PAYMENT",
        "Amount": 30,
        "due_after": 1767225600000,
        "is_percentage": true
      },
      {
        "type": "POST_PAID",
        "Amount": 70,
        "due_after": 1769904000000,
        "is_percentage": true
      }
    ]
  }
}

updateAgreement#

Update an existing payment agreement — for example post-paid or down-payment terms — including its conditions, name, instruction and translations.

Input: UpdateAgreementInput!

Name	Type	Required	Description
`id`	ID!	Required	The ID of the agreement to update
`is_default_enabled`	Boolean!	Required	Whether the agreement is enabled by default
`enabled_rule_set_id`	ID	Optional	ID of the rule set that determines when the agreement is enabled
`conditions`	[AgreementConditionInput]!▾	Required	The payment conditions of the agreement
`type`	AgreementType!▾	Required	The kind of agreement
`name`	String!	Required	Name of the agreement
`instruction`	String	Optional	Instruction shown to the customer
`description`	String	Optional	Description of the agreement
`i18n`	[InternationalizationInput]!▾	Required	Translations of the agreement per locale

Returns: UpdateAgreementPayload!

Name	Type	Required	Description
`agreement`	Agreement▾	Optional	The updated agreement

Example#

mutation UpdateAgreement($input: UpdateAgreementInput!) {
  updateAgreement(input: $input) {
    agreement {
      id
      name
      type
      is_default_enabled
      updated_at
    }
  }
}

{
  "input": {
    "id": "agr_5Kp2vX",
    "is_default_enabled": true,
    "type": "POST_PAID",
    "name": "Pay after delivery",
    "instruction": "You will receive an invoice after your order has been delivered.",
    "conditions": [
      {
        "type": "POST_PAID",
        "amount": 100,
        "is_percentage": true
      }
    ],
    "i18n": [
      {
        "locale": "nl-NL",
        "name": "Betalen na levering",
        "description": "Betaal binnen 14 dagen na levering.",
        "instruction": "Je ontvangt een factuur nadat je bestelling is geleverd."
      }
    ]
  }
}

Business#

addIntegrationToBusiness#

Link an integration to a business, for either purchase or order processing. The business then uses that integration for the given flow.

Input: AddIntegrationToBusinessInput!

Name	Type	Required	Description
`business_id`	String!	Required	The ID of the business to link the integration to
`integration_id`	String!	Required	The ID of the integration to link
`type`	BusinessIntegrationType!▾	Required	The flow the integration is used for

Returns: AddIntegrationToBusinessPayload!

Name	Type	Required	Description
`business`	Business▾	Optional	The updated business

Example#

mutation AddIntegrationToBusiness($input: AddIntegrationToBusinessInput!) {
  addIntegrationToBusiness(input: $input) {
    business {
      id
      type
      name
      email
      integrations {
        type
      }
    }
  }
}

{
  "input": {
    "business_id": "bus_4TnW8p",
    "integration_id": "int_2QkX5r",
    "type": "PURCHASE"
  }
}

removeIntegrationFromBusiness#

Unlink an integration from a business, so the business no longer uses it for its purchase or order flow.

Input: RemoveIntegrationFromBusinessInput!

Name	Type	Required	Description
`business_id`	String!	Required	The ID of the business to unlink the integration from
`integration_id`	String!	Required	The ID of the integration to unlink

Returns: RemoveIntegrationFromBusinessPayload!

Name	Type	Required	Description
`business`	Business▾	Optional	The updated business

Example#

mutation RemoveIntegrationFromBusiness($input: RemoveIntegrationFromBusinessInput!) {
  removeIntegrationFromBusiness(input: $input) {
    business {
      id
      type
      name
      integrations {
        type
      }
    }
  }
}

{
  "input": {
    "business_id": "bus_4TnW8p",
    "integration_id": "int_2QkX5r"
  }
}

Addresses & phone numbers#

createAddress#

Create a standalone address record that can later be linked to contacts, organisations, orders or locations. The response includes validation results for the submitted address.

Input: AddressInput!

Name	Type	Required	Description
`country_code`	String	Optional	ISO 3166-1 alpha-2 country code (e.g. NL, DE)
`administrative_area`	String	Optional	State, province or region
`locality`	String	Optional	City or town
`dependent_locality`	String	Optional	Neighbourhood or district within the locality
`postal_code`	String	Optional	Postal / ZIP code
`sorting_code`	String	Optional	Postal sorting code (used in some countries)
`address_line_1`	String	Optional	Full first line of the address
`address_line_2`	String	Optional	Second address line
`address_line_3`	String	Optional	Third address line
`thoroughfare`	String	Optional	Street name
`premise_number`	PremiseNumber	Optional	House number — string or integer
`premise_number_suffix`	String	Optional	Apartment/unit suffix (e.g. A, 2B)
`organisation`	String	Optional	Company or organisation name at this address
`given_name`	String	Optional	First name on address
`additional_name`	String	Optional	Middle name(s) on address
`family_name`	String	Optional	Last name on address
`override`	Boolean	Optional	Skip address validation and store the address as-is

Returns: CreateAddressPayload!

Name	Type	Required	Description
`address`	Address▾	Optional	The created address

Example#

mutation CreateAddress($input: AddressInput!) {
  createAddress(input: $input) {
    address {
      id
      address_line_1
      locality
      postal_code
      country_code
      is_valid
      errors
    }
  }
}

{
  "input": {
    "country_code": "NL",
    "locality": "Groningen",
    "postal_code": "9712 HM",
    "thoroughfare": "Oude Boteringestraat",
    "premise_number": 44,
    "given_name": "Emma",
    "family_name": "de Vries"
  }
}

createPhoneNumber#

Create a phone number record that can be linked to contacts, organisations or orders. The number is parsed and returned in both international and national formats.

Input: PhoneNumberInput!

Name	Type	Required	Description
`country_code`	String	Optional	ISO 3166-1 alpha-2 country code used to parse national numbers (e.g. NL)
`number`	String!	Required	The phone number, in international (+31612345678) or national format

Returns: CreatePhoneNumberPayload!

Name	Type	Required	Description
`phone_number`	PhoneNumber▾	Optional	The created phone number

Example#

mutation CreatePhoneNumber($input: PhoneNumberInput!) {
  createPhoneNumber(input: $input) {
    phone_number {
      id
      country_code
      number
      national
      type
    }
  }
}

{
  "input": {
    "country_code": "NL",
    "number": "0612345678"
  }
}

Emails#

sendCancellationEmail#

Send a cancellation confirmation email to the customer for specific items of an order.

Input: SendCancellationEmailInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order
`item_ids`	[String]!	Required	The IDs of the cancelled order items to include in the email

Returns: SendCancellationEmailPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The order the email was sent for

Example#

mutation SendCancellationEmail($input: SendCancellationEmailInput!) {
  sendCancellationEmail(input: $input) {
    order {
      id
      number
      status
      is_cancelled
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ",
    "item_ids": ["itm_4Fq8Zw", "itm_9Lp2Vc"]
  }
}

sendQuotationEmail#

Send a quotation email for an order to the customer.

Input: SendQuotationEmailInput!

Name	Type	Required	Description
`order_id`	String!	Required	The ID of the order to send the quotation for

Returns: SendQuotationEmailPayload!

Name	Type	Required	Description
`order`	Order▾	Optional	The order the quotation was sent for

Example#

mutation SendQuotationEmail($input: SendQuotationEmailInput!) {
  sendQuotationEmail(input: $input) {
    order {
      id
      number
      status
      total {
        amount
        formatted
      }
    }
  }
}

{
  "input": {
    "order_id": "ord_x9k2mQ"
  }
}

Files#

uploadFile#

Upload a single file and store it at the given path. The file itself is sent as a multipart upload (GraphQL multipart request); the variables carry the path and visibility.

Input: UploadFileInput!

Name	Type	Required	Description
`file`	FileUpload!▾	Required	The file to upload

Returns: UploadFilePayload!

Name	Type	Required	Description
`uploaded_file`	File▾	Optional	The stored file

Example#

mutation UploadFile($input: UploadFileInput!) {
  uploadFile(input: $input) {
    uploaded_file {
      id
      filename
      url
      mime
      is_public
      created_at
    }
  }
}

{
  "input": {
    "file": {
      "is_public": true,
      "path": "/products/images",
      "file": null
    }
  }
}

uploadFiles#

Upload multiple files in a single request. Each file is sent as a multipart upload (GraphQL multipart request) with its own path and visibility.

Input: UploadFilesInput!

Name	Type	Required	Description
`files`	[FileUpload]!▾	Required	The files to upload

Returns: UploadFilesPayload!

Name	Type	Required	Description
`uploaded_files`	[File]!▾	Required	The stored files, in the same order as the input

Example#

mutation UploadFiles($input: UploadFilesInput!) {
  uploadFiles(input: $input) {
    uploaded_files {
      id
      filename
      url
      mime
      is_public
    }
  }
}

{
  "input": {
    "files": [
      { "is_public": true, "path": "/products/images", "file": null },
      { "is_public": false, "path": "/invoices", "file": null }
    ]
  }
}