Create an order

About orders

An order is a customer's request to purchase one or more products and have them delivered via a specified method. With the Delivery Gateway backend integration, you can create orders, assign all the relevant information to them, and manage them throughout the order's lifecycle.

An order requires the following data:

• A reference ID: an automatically generated ID assigned by your system.
• When the order was created.
• The total price of the order. You must specify both the net and gross values.
• The items included in the order.

Order items

You can pass extensive information about items in a given order to the Merchant API. The OrderItemInput type allows assigning different identifiers such as a name, a reference ID or an SKU. You can specify categories for your items (for example, "Electronics"), and variants (for example, 128 GB or 256 GB smartphone models).

Global identifiers

Delivery Gateway enables the use of global identifier standards in your orders: for example, GTIN, EAN, or ISBN. These are available under the globalIdentifiers field of the upsertOrder mutation.

Item price

Item price is calculated from the unit price and quantity of each item. The unit price consists of the net price, gross price, and the VAT value. You can calculate the total price of items from the unit price and quantity of each item. When setting a quantity, you can select the unit: piece, kilogramm, liter, or other.

Create an order

Create and update orders with the upsertOrder mutation.

Part 1: Assign an ID

First, assign the order an ID and set the time of its creation:

• Generate an ID and pass it to referenceId.
• Pass the time in Y-m-d\TH:i:sP format to createdAt.

GraphQL mutation

mutation {
  upsertOrder(
    input: {
      referenceId: "123456",
      createdAt: $date
    }
  )
}

Part 2: Add items

Add the items to the order. If you have multiple items, include them as an array. Each item must have a name, a unit price, a quantity, and a total price.

• The unit field sets the unit price. The net and gross subfields both require an amount and a currency and you also need to specify the VAT in the vat subfield.
• The quantity field requires count which takes a float, and type which defines the measurement. In addition to the pre-defined values, you can set it to OTHER and specify ta custom type with the typeOther field.
• The total, like the unit prices, requires both a net and a gross amount. The total price should be calculated as the unit price multiplied by the item quantity.

GraphQL mutation

mutation (
    $netPrice: # calculated net price of order
    $grossPrice: # calculated gross price of order
){
  upsertOrder(
    input: {
      referenceId: "123456",
      createdAt: "2025-12-10\\CET16:17:52+01:00",
      items: {
        name: "HAL-9000"
        unit: {
          net: {
            amount: 55000,
            currency: HUF
          },
          vat: 27,
          gross: {
            amount: 69850,
            currency: HUF
          }
        }
        quantity: {
          count: 1,
          type: PIECE
        }
        total: {
          net: {
            amount: $netPrice
            currency: HUF
          },
          gross: {
            amount: $grossPrice
            currency: HUF
          }          
        }
        isShipping: true,
        isPayment: true,
        isDiscount: false
      },
    }
  )
}

Part 3: Calculate the total

The final total price of the order is set in the total field. This also requires a net and a gross subfields. You can calculate the total price by adding all unit price totals.

GraphQL mutation

mutation (
    $netPrice: # calculated net price of order
    $grossPrice: # calculated gross price of order
    $totalnetPrice: # a calculated total net price of all items
    $totalgrossPrice: # a calculated total gross price of all items
){
  upsertOrder(
    input: {
      referenceId: "123456",
      createdAt: "2025-12-10\\CET16:17:52+01:00",
      total: {
        net: {
          amount: 55000,
          currency: HUF
        }
        gross: {
          amount: 69850,
          currency: HUF
        }
      },
      items: [{
        name: "HAL-9000"
        unit: {
          net: {
            amount: 55000,
            currency: HUF
          },
          vat: 27,
          gross: {
            amount: 69850,
            currency: HUF
          }
        }
        quantity: {
          count: 1,
          type: PIECE
        }
        total: {
          net: {
            amount: $netPrice
            currency: HUF
          },
          gross: {
            amount: $grossPrice
            currency: HUF
          }          
        }
        isShipping: true,
        isPayment: true,
        isDiscount: false
      },
      ]
    }
  )
}

Assign a customer and a session to an order

The upsertOrder mutation allows assigning a customer ID and a session ID to an order, allowing your system to easily associate an order with a registered customer.

You need a sessionId and a customerId:

• The sessionId field is automatically generated by the Delivery Gateway API when initializing a session.
• The customerId is generated by your own system.

GraphQL mutation

mutation {
  upsertOrder(
    input: {
      referenceId: "123456",
      createdAt: $date,
      customerId: "efgh4567",
      sessionId: "asdf-efht-1345-2346"
    }
  )
}