Place Order - Integration Flow

27 min

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 QueriesSetup Queries.

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

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"
}

cURL

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

{
  "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"
              }
            ]
          }
        ]
      }
    }
  }
}

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

Step 2: Add the customer (if not found)

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>"
}

cURL

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

{
  "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
          }
        }
      }
    }
  }
}

ℹ️ 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

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>"
}

cURL

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

{
  "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

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>"
}

cURL

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

{
  "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

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>"
}

cURL

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

{
  "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

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>"
}

cURL

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

{
  "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
      }
    }
  }
}

ℹ️ 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.

🔶 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.

ℹ️ 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).

💡 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	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	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

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>"
  ]
}

cURL

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

{
  "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"
                }
              }
            ]
          }
        ]
      }
    }
  }
}

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