---
title: Place Order - Integration Flow
slug: devdocs/place-order-integration-flow
docTags: 
createdAt: 2026-10-16T12:03:50.919Z
---

Follow these steps to create an order. Each response returns a `publicKey` that you use in the next step. Keep these keys:

| **Key**              | **Where to find it**                                      |
| -------------------- | --------------------------------------------------------- |
| `customerKey`        | `data.customer.create.result.publicKey`                   |
| `customerAddressKey` | `data.customer.createAddress.result.publicKey`            |
| `companyKey`         | `data.organization.createCompany.result.publicKey`        |
| `companyAddressKey`  | `data.organization.createCompanyAddress.result.publicKey` |
| `orderKey`           | `data.deliveryOrder.create.result.publicKey`              |

Get `locationKey`, `salePriceCategoryKey`, product keys, and `streetKey` from the **[Setup Queries](docId\:c2JJKRVgIJ2tYkey9Sdrl)**.

:::hint{type="info"}
Always check `errorCode` and `errorMessage` in the result of each mutation. HTTP 200 doesn't mean the operation succeeded.
:::

## Step 1: Find the customer

Search by first name, last name, and phone. If `items` is an empty array, the customer doesn't exist yet: go to Step 2.

**Query**

```graphql
query getCustomerBasedOnName ($firstName: String, $lastName: String, $phone: String) {
  customers {
    customer(firstName: $firstName, lastName: $lastName, phone: $phone) {
      items {
        publicKey
        firstName
        lastName
        mobilePhone
        addresses {
          publicKey
          streetName
          streetNumber
          buildingNumber
          staircase
          floor
          intercom
          landmark
          roomNumber
        }
      }
    }
  }
}
```

**Variables**

```json
{
  "firstName": "Jane",
  "lastName": "Doe",
  "phone": "0700000001"
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "query getCustomerBasedOnName ($firstName: String, $lastName: String, $phone: String) { customers { customer(firstName: $firstName, lastName: $lastName, phone: $phone) { items { publicKey firstName lastName mobilePhone addresses { publicKey streetName streetNumber buildingNumber staircase floor intercom landmark roomNumber } } } } }", "variables": {"firstName": "Jane", "lastName": "Doe", "phone": "0700000001"}}'
```

**Response**

```json
{
  "data": {
    "customers": {
      "customer": {
        "items": [
          {
            "publicKey": "00000000-0000-0000-0000-000000000001",
            "firstName": "Jane",
            "lastName": "Doe",
            "mobilePhone": "0700000001",
            "addresses": [
              {
                "publicKey": "00000000-0000-0000-0000-000000000011",
                "streetName": "Sample Street",
                "streetNumber": "12",
                "buildingNumber": "B",
                "staircase": "1",
                "floor": "3",
                "intercom": "30",
                "landmark": "Next to the park",
                "roomNumber": "9"
              }
            ]
          }
        ]
      }
    }
  }
}
```

:::BlockQuote
⚠️ **WARNING**
Always search first. A duplicate customer splits the order history of the same person.
:::

## Step 2: Add the customer (if not found)

**Query**

```graphql
mutation addCustomer ($customerCategory: Guid!, $firstName: String!, $lastName: String!, $phone: String!) {
  customer {
    create(
      payload: {
        category: $customerCategory
        firstName: $firstName
        lastName: $lastName
        mobilePhone: $phone
      }
    ) {
      result {
        publicKey
        firstName
        lastName
        active
        mobilePhone
        category {
          publicKey
          name
          active
        }
      }
    }
  }
}
```

**Variables**

```json
{
  "firstName": "Jane",
  "lastName": "Doe",
  "phone": "0700000001",
  "customerCategory": "<customerCategoryKey>"
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "mutation addCustomer ($customerCategory: Guid!, $firstName: String!, $lastName: String!, $phone: String!) { customer { create( payload: { category: $customerCategory firstName: $firstName lastName: $lastName mobilePhone: $phone } ) { result { publicKey firstName lastName active mobilePhone category { publicKey name active } } } } }", "variables": {"firstName": "Jane", "lastName": "Doe", "phone": "0700000001", "customerCategory": "<customerCategoryKey>"}}'
```

**Response**

```json
{
  "data": {
    "customer": {
      "create": {
        "result": {
          "publicKey": "00000000-0000-0000-0000-000000000001",
          "firstName": "Jane",
          "lastName": "Doe",
          "active": true,
          "mobilePhone": "0700000001",
          "category": {
            "publicKey": "00000000-0000-0000-0000-000000000021",
            "name": "Gold customers",
            "active": true
          }
        }
      }
    }
  }
}
```

:::BlockQuote
ℹ️ **INFO**
Take the `customerCategory` key from **Get Customer Categories**.
:::

## Step 3: Add the customer address

The address fields in this example are literal values from the tested request. Replace them with the real address. Take `streetKey` from **Get Streets by County**.

**Query**

```graphql
mutation addCustomerAddress ($customerKey: Guid!, $streetKey: Guid!) {
  customer {
    createAddress(
      payload: {
        customerKey: $customerKey
        streetKey: $streetKey
        streetNumber: "15"
        buildingNumber: "1E"
        staircase: "A"
        floor: "1"
        roomNumber: "5"
        intercom: "5C"
        landmark: "Next to metro station"
      }
    ) {
      result {
        publicKey
        streetName
        streetNumber
        buildingNumber
        staircase
        floor
        intercom
        landmark
        roomNumber
        active
        city {
          publicKey
          name
        }
      }
    }
  }
}
```

**Variables**

```json
{
  "customerKey": "<customerKey>",
  "streetKey": "<streetKey>"
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "mutation addCustomerAddress ($customerKey: Guid!, $streetKey: Guid!) { customer { createAddress( payload: { customerKey: $customerKey streetKey: $streetKey streetNumber: \"15\" buildingNumber: \"1E\" staircase: \"A\" floor: \"1\" roomNumber: \"5\" intercom: \"5C\" landmark: \"Next to metro station\" } ) { result { publicKey streetName streetNumber buildingNumber staircase floor intercom landmark roomNumber active city { publicKey name } } } } }", "variables": {"customerKey": "<customerKey>", "streetKey": "<streetKey>"}}'
```

**Response**

```json
{
  "data": {
    "customer": {
      "createAddress": {
        "result": {
          "publicKey": "00000000-0000-0000-0000-000000000011",
          "streetName": "Sample Street",
          "streetNumber": "15",
          "buildingNumber": "1E",
          "staircase": "A",
          "floor": "1",
          "intercom": "5C",
          "landmark": "Next to metro station",
          "roomNumber": "5",
          "active": true,
          "city": {
            "publicKey": "00000000-0000-0000-0000-000000000042",
            "name": "Sector 1"
          }
        }
      }
    }
  }
}
```

## Step 4: Add the company (company invoices only)

Skip Steps 4 and 5 if the order isn't invoiced to a company. The company fields in this example are literal values from the tested request. Replace them with the real company data.

**Query**

```graphql
mutation addCompany ($companyCategory:Guid!){
  organization{
    createCompany(
      payload:
      {name: "My Test Company 2"
      fiscalAttribute: "RO"
      fiscalCode: "12332166"
      registrationCode: "98765664"
      category: $companyCategory}
    )
    {
      result{
        publicKey
        name
        fiscalAttribute
        fiscalCode
        registrationCode

      }
    }

  }
}
```

**Variables**

```json
{
  "companyCategory": "<companyCategoryKey>"
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "mutation addCompany ($companyCategory:Guid!){ organization{ createCompany( payload: {name: \"My Test Company 2\" fiscalAttribute: \"RO\" fiscalCode: \"12332166\" registrationCode: \"98765664\" category: $companyCategory} ) { result{ publicKey name fiscalAttribute fiscalCode registrationCode } } } }", "variables": {"companyCategory": "<companyCategoryKey>"}}'
```

**Response**

```json
{
  "data": {
    "organization": {
      "createCompany": {
        "result": {
          "publicKey": "00000000-0000-0000-0000-000000000101",
          "name": "My Test Company 2",
          "fiscalAttribute": "RO",
          "fiscalCode": "12332166",
          "registrationCode": "98765664"
        }
      }
    }
  }
}
```

## Step 5: Add the company address (company invoices only)

Take `cityKey` from **Get Counties and Cities by Country**.

**Query**

```graphql
mutation addCompanyAddress ($companyKey: Guid!, $cityKey:Guid!){
  organization{
    createCompanyAddress(
      payload:
      {
        companyKey:$companyKey
        cityKey: $cityKey
        streetName: "Berzei"
        streetNumber: "12"
      }
    )
    {
      result{
        publicKey
        city {
          publicKey
          name
        }
        streetName
        streetNumber
      }
    }
  }
}
```

**Variables**

```json
{
  "companyKey": "<companyKey>",
  "cityKey": "<cityKey>"
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "mutation addCompanyAddress ($companyKey: Guid!, $cityKey:Guid!){ organization{ createCompanyAddress( payload: { companyKey:$companyKey cityKey: $cityKey streetName: \"Berzei\" streetNumber: \"12\" } ) { result{ publicKey city { publicKey name } streetName streetNumber } } } }", "variables": {"companyKey": "<companyKey>", "cityKey": "<cityKey>"}}'
```

**Response**

```json
{
  "data": {
    "organization": {
      "createCompanyAddress": {
        "result": {
          "publicKey": "00000000-0000-0000-0000-000000000111",
          "city": {
            "publicKey": "00000000-0000-0000-0000-000000000042",
            "name": "Sector 1"
          },
          "streetName": "Berzei",
          "streetNumber": "12"
        }
      }
    }
  }
}
```

## Step 6: Add the order

The example orders two products and invoices a company. `deliveryFee`, `customerComments` and the quantities are literal values from the tested request.

**Query**

```graphql
mutation addOrder ($customerKey:Guid!, $customerAddressKey:Guid!, $locationKey:Guid!, $salePriceCategoryKey:Guid!, $product1Key:Guid!, $product2Key:Guid!, $product1salePrice:Decimal!, $product2salePrice:Decimal!, $companyKey: Guid!, $companyAddressKey: Guid!) {
  deliveryOrder {
    create(
      payload: {
        attendedOrder: true
        customerKey: $customerKey
        customerAddressKey: $customerAddressKey
        locationKey: $locationKey
        salePriceCategoryKey: $salePriceCategoryKey
        customerComments: "No allergies"
        deliveryFee: 10
        orders: [
          {
            productKey: $product1Key
            quantity: 4
            salePrice: $product1salePrice
          }
          {
            productKey: $product2Key
            quantity: 1
            salePrice: $product2salePrice
          }
        ]
        invoice: {
          clientType: COMPANY
          clientKey: $companyKey
          clientAddressKey: $companyAddressKey
        }
      }
    ) {
      result {
        publicKey
        createdOn
        location {
          publicKey
          name
          preparationMinutes
        }
        customer {
          publicKey
          firstName
          lastName
          mobilePhone
          category {
            name
          }
          addresses {
            publicKey
            streetName
            streetNumber
            buildingNumber
            staircase
            floor
            intercom
            landmark
            roomNumber
          }
        }
      }
      errorCode
      errorMessage
    }
  }
}
```

**Variables**

```json
{
  "customerKey": "<customerKey>",
  "customerAddressKey": "<customerAddressKey>",
  "locationKey": "<locationKey>",
  "salePriceCategoryKey": "<salePriceCategoryKey>",
  "product1Key": "<chosenProduct1Key>",
  "product1salePrice": 32.5,
  "product2Key": "<chosenProduct2Key>",
  "product2salePrice": 18.9,
  "companyKey": "<companyKey>",
  "companyAddressKey": "<companyAddressKey>"
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "mutation addOrder ($customerKey:Guid!, $customerAddressKey:Guid!, $locationKey:Guid!, $salePriceCategoryKey:Guid!, $product1Key:Guid!, $product2Key:Guid!, $product1salePrice:Decimal!, $product2salePrice:Decimal!, $companyKey: Guid!, $companyAddressKey: Guid!) { deliveryOrder { create( payload: { attendedOrder: true customerKey: $customerKey customerAddressKey: $customerAddressKey locationKey: $locationKey salePriceCategoryKey: $salePriceCategoryKey customerComments: \"No allergies\" deliveryFee: 10 orders: [ { productKey: $product1Key quantity: 4 salePrice: $product1salePrice } { productKey: $product2Key quantity: 1 salePrice: $product2salePrice } ] invoice: { clientType: COMPANY clientKey: $companyKey clientAddressKey: $companyAddressKey } } ) { result { publicKey createdOn location { publicKey name preparationMinutes } customer { publicKey firstName lastName mobilePhone category { name } addresses { publicKey streetName streetNumber buildingNumber staircase floor intercom landmark roomNumber } } } errorCode errorMessage } } }", "variables": {"customerKey": "<customerKey>", "customerAddressKey": "<customerAddressKey>", "locationKey": "<locationKey>", "salePriceCategoryKey": "<salePriceCategoryKey>", "product1Key": "<chosenProduct1Key>", "product1salePrice": 32.5, "product2Key": "<chosenProduct2Key>", "product2salePrice": 18.9, "companyKey": "<companyKey>", "companyAddressKey": "<companyAddressKey>"}}'
```

**Response**

```json
{
  "data": {
    "deliveryOrder": {
      "create": {
        "result": {
          "publicKey": "00000000-0000-0000-0000-000000000121",
          "createdOn": "2026-01-15T10:30:00.000",
          "location": null,
          "customer": {
            "publicKey": "00000000-0000-0000-0000-000000000001",
            "firstName": "Jane",
            "lastName": "Doe",
            "mobilePhone": "0700000001",
            "category": {
              "name": "Gold customers"
            },
            "addresses": [
              {
                "publicKey": "00000000-0000-0000-0000-000000000011",
                "streetName": "Sample Street",
                "streetNumber": "15",
                "buildingNumber": "1E",
                "staircase": "A",
                "floor": "1",
                "intercom": "5C",
                "landmark": "Next to metro station",
                "roomNumber": "5"
              }
            ]
          }
        },
        "errorCode": null,
        "errorMessage": null
      }
    }
  }
}
```

:::BlockQuote
ℹ️ **INFO**
Prices come from the price list you pass as `salePriceCategoryKey`. Use the `salePrice` returned by **Get Products by Sale Price Category** or **Get Products by Product Category**.
:::

:::BlockQuote
🔶 **TO CONFIRM (remove before publishing)**
In the tested response `result.location` is `null` even though the mutation asks for the location. Confirm whether this is expected.
:::

:::BlockQuote
ℹ️ **INFO**
`invoice` is optional. Leave it out when the order doesn't need an invoice client. When you send it, `clientType` is `COMPANY` (with the company key and the company address key, as in this example) or `CUSTOMER` (with the customer key and the customer address key).
:::

:::BlockQuote
💡 **TIP**
Send a `key` of your own in the order to make the call safe to repeat. If an order with this `key` already exists, the mutation returns the `DuplicateKey` error instead of creating a second order.
:::

### Fields of the order

These are the fields of `DeliveryOrderCreateInputType`. Only `customerKey` and `salePriceCategoryKey` are required, and `orders` can't be empty for a real order.

| Field                  | Type                        | Required | Default | Description                                                                                                                                                              |
| ---------------------- | --------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `channelType`          | `Short`                     | no       |         | Sales channel type ID.                                                                                                                                                   |
| `key`                  | `Guid`                      | no       |         | Optional client-supplied idempotency key. If a delivery order with this key already exists, the mutation returns the DuplicateKey error instead of creating a new order. |
| `attendedOrder`        | `Boolean`                   | no       | `true`  | TRUE when order must be confirmed by any system user                                                                                                                     |
| `customerKey`          | `Guid!`                     | yes      |         | Customer public key.                                                                                                                                                     |
| `customerAddressKey`   | `Guid`                      | no       |         | Customer address public key.                                                                                                                                             |
| `locationKey`          | `Guid`                      | no       |         | Fulfillment location public key.                                                                                                                                         |
| `callCenterKey`        | `Guid`                      | no       |         | Call center public key (if applicable).                                                                                                                                  |
| `salePriceCategoryKey` | `Guid!`                     | yes      |         | Sale price category used for this order.                                                                                                                                 |
| `customerComments`     | `String`                    | no       |         | Comments from the customer.                                                                                                                                              |
| `deliveryFee`          | `Decimal`                   | no       |         | Custom delivery fee override.                                                                                                                                            |
| `deliveryTime`         | `DateTime`                  | no       |         | Requested delivery time (null or UTC datetime).                                                                                                                          |
| `subtotalDiscount`     | `SubtotalDiscountInputType` | no       |         | Order-level discount.                                                                                                                                                    |
| `serviceChargeFee`     | `Decimal`                   | no       |         | Service charge fee amount.                                                                                                                                               |
| `orders`               | `[OrderProductInputType]!`  | no       | `[]`    | List of products/items in the order.                                                                                                                                     |
| `payments`             | `[OrderPaymentInputType]`   | no       | `[]`    | Payment methods used for the order.                                                                                                                                      |
| `invoice`              | `OrderInvoiceInputType`     | no       |         | Invoice billing details (if requested).                                                                                                                                  |

### Products of the order

Each item of `orders` is an `OrderProductInputType`.

| Field                | Type                        | Required | Default | Description                                                             |
| -------------------- | --------------------------- | -------- | ------- | ----------------------------------------------------------------------- |
| `productKey`         | `Guid!`                     | yes      |         | Product public key.                                                     |
| `quantity`           | `Decimal!`                  | yes      |         | Quantity ordered.                                                       |
| `salePrice`          | `Decimal!`                  | yes      |         | Unit price with VAT.                                                    |
| `discountAmount`     | `Decimal`                   | no       |         | Discount amount applied to item.                                        |
| `preparation`        | `String`                    | no       |         | Preparation instructions/comments.                                      |
| `voucherKey`         | `Guid`                      | no       |         | Voucher key applied to this item.                                       |
| `promotionKey`       | `Guid`                      | no       |         | Promotion key applied.                                                  |
| `promotionGroupKey`  | `Guid`                      | no       |         | single or multiple products belong on the same promotion unit / context |
| `isPromotionBenefit` | `Boolean`                   | no       |         | Indicates if this item is a benefit of a promotion.                     |
| `bundle`             | `OrderBundleInputType`      | no       |         | order budle content items                                               |
| `addon`              | `OrderAddonInputType`       | no       |         | order addons content                                                    |
| `packaging`          | `ProductPackagingInputType` | no       |         | Packaging details for the item.                                         |

### Payments

Each item of `payments` is an `OrderPaymentInputType`. `paymentKey` is the key of a payment method (see **Schema Reference**, Organization reference data).

| Field            | Type                            | Required | Default | Description                                                                     |
| ---------------- | ------------------------------- | -------- | ------- | ------------------------------------------------------------------------------- |
| `paymentKey`     | `Guid!`                         | yes      |         | Payment method public key.                                                      |
| `paymentAmount`  | `Decimal!`                      | yes      |         | Payment amount.                                                                 |
| `processed`      | `Boolean`                       | no       | `false` | Indicates if payment was already processed by external gateway (default false). |
| `cardPayment`    | `OrderPaymentCardInputType`     | no       |         | Card transaction details (if applicable).                                       |
| `ticketPayments` | `[OrderPaymentTicketInputType]` | no       | `[]`    | Meal ticket details (if applicable).                                            |

### Invoice

| Field              | Type                 | Required | Default | Description                               |
| ------------------ | -------------------- | -------- | ------- | ----------------------------------------- |
| `clientType`       | `InvoiceClientType!` | yes      |         | Target client type (Customer or Company). |
| `clientKey`        | `Guid!`              | yes      |         | Target client public key.                 |
| `clientAddressKey` | `Guid!`              | yes      |         | Target client address public key.         |

`clientType` accepts `CUSTOMER` and `COMPANY`. The other enums of the order are in **Schema Reference**.

## Step 7: Read the order

`orderKey` is a list, even for one order. Send it as an array.

**Query**

```graphql
query getOrder ($customerKey: Guid, $orderKey: [Guid]) {
  order {
    orders(customer: $customerKey publicKey:$orderKey) {

      items {
        publicKey
        createdOn
        closedOn
        location {
          publicKey
          name
        }
        customer {
          publicKey
          firstName
          lastName
        }
        orders {
          productKey
          quantity
          salePrice
          product {
            publicKey
            name
          }
        }
      }
    }
  }
}
```

**Variables**

```json
{
  "customerKey": "<customerKey>",
  "orderKey": [
    "<orderKey>"
  ]
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "query getOrder ($customerKey: Guid, $orderKey: [Guid]) { order { orders(customer: $customerKey publicKey:$orderKey) { items { publicKey createdOn closedOn location { publicKey name } customer { publicKey firstName lastName } orders { productKey quantity salePrice product { publicKey name } } } } } }", "variables": {"customerKey": "<customerKey>", "orderKey": ["<orderKey>"]}}'
```

**Response**

```json
{
  "data": {
    "order": {
      "orders": {
        "items": [
          {
            "publicKey": "00000000-0000-0000-0000-000000000121",
            "createdOn": "2026-01-15T10:30:00.000",
            "closedOn": null,
            "location": {
              "publicKey": "00000000-0000-0000-0000-000000000051",
              "name": "Downtown Restaurant"
            },
            "customer": {
              "publicKey": "00000000-0000-0000-0000-000000000001",
              "firstName": "Jane",
              "lastName": "Doe"
            },
            "orders": [
              {
                "productKey": "00000000-0000-0000-0000-000000000071",
                "quantity": 4,
                "salePrice": 32.5,
                "product": {
                  "publicKey": "00000000-0000-0000-0000-000000000071",
                  "name": "Margherita Pizza"
                }
              }
            ]
          }
        ]
      }
    }
  }
}
```

:::BlockQuote
💡 **TIP**
To follow the order after you create it, use **Webhooks** instead of polling `Get Order`.
:::