---
title: Setup Queries - Reference Catalog
slug: devdocs/setup-queries-reference-catalog
docTags: 
createdAt: 2026-10-16T12:03:50.790Z
---

Use these queries to read the reference data you need before you place an order. Every request is a `POST` to the GraphQL endpoint, with `Authorization: Bearer <token>`.

Run them in this order when you set up an integration:

1. Locations and price lists: **Get Locations**, **Get Sale Price Categories**.
2. Products: **Get Products by Sale Price Category** or **Get Products by Product Category**.
3. Addresses: **Get Counties and Cities by Country**, **Get Streets by County**.
4. Customers and companies: **Get Customer Categories**, **Get Company Categories**, **Get Customers with Addresses**.

## Pagination

List fields that return a connection (`customer`, `products`, `streets`, `country`, `companies`, `orders`, and others) accept cursor arguments: `first`, `after`, `last`, and `before`. They return `totalCount`, `pageInfo`, and `items`.

**Query**

```graphql
query GetCustomersPage($first: Int, $after: String) {
  customers {
    customer(first: $first, after: $after, orderBy: LAST_NAME) {
      totalCount
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
      items {
        publicKey
        firstName
        lastName
        mobilePhone
      }
    }
  }
}
```

**Variables**

```json
{
  "first": 50,
  "after": null
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "query GetCustomersPage($first: Int, $after: String) { customers { customer(first: $first, after: $after, orderBy: LAST_NAME) { totalCount pageInfo { hasNextPage hasPreviousPage startCursor endCursor } items { publicKey firstName lastName mobilePhone } } } }", "variables": {"first": 50, "after": null}}'
```

:::hint{type="info"}
To get the next page, send the `endCursor` of the previous response as `after`. Repeat until `hasNextPage` is `false`. The examples below omit the cursor arguments to stay short.
:::

## Get Customers with Addresses

Returns customers with their saved addresses, ordered by last name.

**Query**

```graphql
query getCustomers {
  customers {
    customer(orderBy: LAST_NAME) {
      totalCount
      items {
        publicKey
        firstName
        lastName
        mobilePhone
        addresses {
          publicKey
          streetName
          streetNumber
          buildingNumber
          staircase
          floor
          intercom
          landmark
          roomNumber
        }
      }
    }
  }
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "query getCustomers { customers { customer(orderBy: LAST_NAME) { totalCount items { publicKey firstName lastName mobilePhone addresses { publicKey streetName streetNumber buildingNumber staircase floor intercom landmark roomNumber } } } } }"}'
```

**Response**

```json
{
  "data": {
    "customers": {
      "customer": {
        "totalCount": 2,
        "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"
              }
            ]
          },
          {
            "publicKey": "00000000-0000-0000-0000-000000000002",
            "firstName": "John",
            "lastName": "Roe",
            "mobilePhone": "0700000002",
            "addresses": []
          }
        ]
      }
    }
  }
}
```

## Get Customer Categories

Returns the customer categories. Use a category `publicKey` when you create a customer.

**Query**

```graphql
query getCustomerCategories {
  customers {
    customerCategories {
      publicKey
      name
    }
  }
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "query getCustomerCategories { customers { customerCategories { publicKey name } } }"}'
```

**Response**

```json
{
  "data": {
    "customers": {
      "customerCategories": [
        {
          "publicKey": "00000000-0000-0000-0000-000000000021",
          "name": "Gold customers"
        },
        {
          "publicKey": "00000000-0000-0000-0000-000000000022",
          "name": "Silver customers"
        }
      ]
    }
  }
}
```

## Get Counties and Cities by Country

Returns the counties, cities, and districts of a country. The country is filtered by name (the example uses `Romania`).

**Query**

```graphql
query getCountiesAndCities {
  organization {
    country (name: "Romania") {
      totalCount
      items {
        publicKey
        name
        county (orderBy: NAME) {
          totalCount
          items {
            publicKey
            name
            city (orderBy: NAME) {
              totalCount
              items {
                publicKey
                name
                districts {
                  publicKey
                  name
                }
              }
            }
          }
        }
      }
    }
  }
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "query getCountiesAndCities { organization { country (name: \"Romania\") { totalCount items { publicKey name county (orderBy: NAME) { totalCount items { publicKey name city (orderBy: NAME) { totalCount items { publicKey name districts { publicKey name } } } } } } } } }"}'
```

**Response**

```json
{
  "data": {
    "organization": {
      "country": {
        "totalCount": 1,
        "items": [
          {
            "publicKey": "00000000-0000-0000-0000-000000000031",
            "name": "Romania",
            "county": {
              "totalCount": 42,
              "items": [
                {
                  "publicKey": "00000000-0000-0000-0000-000000000032",
                  "name": "Alba",
                  "city": {
                    "totalCount": 12,
                    "items": [
                      {
                        "publicKey": "00000000-0000-0000-0000-000000000033",
                        "name": "Abrud",
                        "districts": []
                      }
                    ]
                  }
                }
              ]
            }
          }
        ]
      }
    }
  }
}
```

## Get Streets by County

Returns the streets of a county and city. Pass the `publicKey` values from the previous query.

**Query**

```graphql
query getStreets ($county: Guid, $city: Guid)
{
  organization {
    streets(county: $county city:$city orderBy: NAME) {
      items {
        publicKey
        name
        active
        startNumber
        endNumber
        city {
          publicKey
          name
        }
        district {
          publicKey
          name
        }
      }
    }
  }
}
```

**Variables**

```json
{
  "county": "<countyKey>",
  "city": "<cityKey>"
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "query getStreets ($county: Guid, $city: Guid) { organization { streets(county: $county city:$city orderBy: NAME) { items { publicKey name active startNumber endNumber city { publicKey name } district { publicKey name } } } } }", "variables": {"county": "<countyKey>", "city": "<cityKey>"}}'
```

**Response**

```json
{
  "data": {
    "organization": {
      "streets": {
        "items": [
          {
            "publicKey": "00000000-0000-0000-0000-000000000041",
            "name": "Sample Street",
            "active": true,
            "startNumber": 1,
            "endNumber": 9999,
            "city": {
              "publicKey": "00000000-0000-0000-0000-000000000042",
              "name": "Sector 1"
            },
            "district": null
          }
        ]
      }
    }
  }
}
```

:::hint{type="info"}
Use the street `publicKey` as `streetKey` when you add a customer address.
:::

## Get Locations

Returns the locations, with their availability and preparation time.

**Query**

```graphql
query getLocation
{
  organization {
    locations
    {
      name
      publicKey
      active
      city {
        publicKey
        name
      }
      county {
        publicKey
        name
      }
      country {
        publicKey
        name
      }
      available
      preparationMinutes
    }
  }
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "query getLocation { organization { locations { name publicKey active city { publicKey name } county { publicKey name } country { publicKey name } available preparationMinutes } } }"}'
```

**Response**

```json
{
  "data": {
    "organization": {
      "locations": [
        {
          "name": "Downtown Restaurant",
          "publicKey": "00000000-0000-0000-0000-000000000051",
          "active": true,
          "city": {
            "publicKey": "00000000-0000-0000-0000-000000000042",
            "name": "Sector 1"
          },
          "county": {
            "publicKey": "00000000-0000-0000-0000-000000000052",
            "name": "Bucuresti"
          },
          "country": {
            "publicKey": "00000000-0000-0000-0000-000000000031",
            "name": "Romania"
          },
          "available": true,
          "preparationMinutes": 40
        }
      ]
    }
  }
}
```

## Get Sale Price Categories

Returns the price lists (sale price categories). You need one when you read prices and when you create an order.

**Query**

```graphql
{
  products {
    salePriceCategories {
      publicKey
      name
    }
  }
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "{ products { salePriceCategories { publicKey name } } }"}'
```

**Response**

```json
{
  "data": {
    "products": {
      "salePriceCategories": [
        {
          "publicKey": "00000000-0000-0000-0000-000000000061",
          "name": "Standard price list"
        },
        {
          "publicKey": "00000000-0000-0000-0000-000000000062",
          "name": "Delivery"
        }
      ]
    }
  }
}
```

## Get Products by Sale Price Category

Returns the products of a price list, with the price from that list.

**Query**

```graphql
query getProducts ($salePriceCategory: Guid!) {
  products {
    products(salePriceCategory: $salePriceCategory) {
      items {
        publicKey
        name
        productCategory {
          publicKey
          name
        }
        measureUnit
        salePrice
      }
    }
  }
}
```

**Variables**

```json
{
  "salePriceCategory": "<salePriceCategoryKey>"
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "query getProducts ($salePriceCategory: Guid!) { products { products(salePriceCategory: $salePriceCategory) { items { publicKey name productCategory { publicKey name } measureUnit salePrice } } } }", "variables": {"salePriceCategory": "<salePriceCategoryKey>"}}'
```

**Response**

```json
{
  "data": {
    "products": {
      "products": {
        "items": [
          {
            "publicKey": "00000000-0000-0000-0000-000000000071",
            "name": "Margherita Pizza",
            "productCategory": {
              "publicKey": "00000000-0000-0000-0000-000000000072",
              "name": "Pizza"
            },
            "measureUnit": "portion",
            "salePrice": 32.5
          }
        ]
      }
    }
  }
}
```

## Get Products by Product Category

Returns the products of a product category, with the price from a price list and the stock status for one location.

**Query**

```graphql
query getProductsPerCategories ($salePriceCategory: Guid!, $location: Guid!, $productCategory: Guid)
{
  products {
    productCategories(productCategory: $productCategory) {
      publicKey
      name
      active
      products(salePriceCategory: $salePriceCategory) {
        totalCount
        items {
          publicKey
          name
          code
          measureUnit
          salePrice
          outOfStock(location: $location)
        }
      }
    }
  }
}
```

**Variables**

```json
{
  "salePriceCategory": "<salePriceCategoryKey>",
  "location": "<locationKey>",
  "productCategory": "<productCategoryKey>"
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "query getProductsPerCategories ($salePriceCategory: Guid!, $location: Guid!, $productCategory: Guid) { products { productCategories(productCategory: $productCategory) { publicKey name active products(salePriceCategory: $salePriceCategory) { totalCount items { publicKey name code measureUnit salePrice outOfStock(location: $location) } } } } }", "variables": {"salePriceCategory": "<salePriceCategoryKey>", "location": "<locationKey>", "productCategory": "<productCategoryKey>"}}'
```

**Response**

```json
{
  "data": {
    "products": {
      "productCategories": [
        {
          "publicKey": "00000000-0000-0000-0000-000000000072",
          "name": "Desserts",
          "active": true,
          "products": {
            "totalCount": 1,
            "items": [
              {
                "publicKey": "00000000-0000-0000-0000-000000000081",
                "name": "Apple pie",
                "code": "252",
                "measureUnit": "portion",
                "salePrice": 18.9,
                "outOfStock": false
              }
            ]
          }
        }
      ]
    }
  }
}
```

:::hint{type="info"}
`outOfStock(location: ...)` is resolved per location. Always pass the `locationKey` of the location that prepares the order.
:::

## Get Company Categories

Returns the company categories. Use a category `publicKey` when you create a company.

**Query**

```graphql
query getCompanyCategories
{
  organization {
    companyCategories {
      publicKey
      name
      active
    }
  }
}
```

**cURL**

```bash
curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "query getCompanyCategories { organization { companyCategories { publicKey name active } } }"}'
```

**Response**

```json
{
  "data": {
    "organization": {
      "companyCategories": [
        {
          "publicKey": "00000000-0000-0000-0000-000000000091",
          "name": "Customers",
          "active": true
        },
        {
          "publicKey": "00000000-0000-0000-0000-000000000092",
          "name": "Suppliers",
          "active": true
        }
      ]
    }
  }
}
```