---
title: Request Structure
slug: devdocs/request-structure
docTags: 
createdAt: 2026-10-16T12:03:51.923Z
---

Every request is a `POST` to the GraphQL endpoint.

```text
POST https://sandbox.expressoft.eu/connect/api/interopgql
Authorization: Bearer <token>
Content-Type: application/json
```

```json
{
  "query": "<query or mutation>",
  "variables": {}
}
```

`variables` carries the arguments of the operation.

## Entry points

The queries start at `customers`, `loyalty`, `order` and `organization`. The mutations start at `customer` and `organization`.

| Entry point                              | Used for                                                                     |
| ---------------------------------------- | ---------------------------------------------------------------------------- |
| `customers.customer`                     | Customers, with their loyalty data                                           |
| `order.orders`                           | Orders and receipts, with the points of each receipt                         |
| `loyalty.promotion`                      | Promotions                                                                   |
| `organization`                           | Reference data: currencies, VAT categories, organizations, marketing actions |
| `customer.*` (mutation)                  | Create, update and delete customers and their addresses                      |
| `organization.createGiftCard` (mutation) | Create a gift card                                                           |

## Lists and paging

Lists that return a connection use **cursors**. They accept `first`, `after`, `last` and `before`, and return `totalCount`, `pageInfo` and `items`.

```graphql
customers {
  customer(first: 30, after: $after) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    items {
      publicKey
    }
  }
}
```

To read the next page, send the `endCursor` of the previous page as `after`. Stop when `hasNextPage` is `false`.

`orderBy` takes a sort value. For customers: `FIRST_NAME`, `FIRST_NAME_DESC`, `LAST_NAME`, `LAST_NAME_DESC`.

:::BlockQuote
ℹ️ **INFO**
Lists return active records by default. For example `customers.customer` returns active customers and sorts them by first name.
:::

## Mutation results

Every mutation returns the same wrapper:

```graphql
result { publicKey }
errorCode
errorMessage
errorData
```

`errorCode` is `null` when the operation succeeds. See **Errors & Troubleshooting**.

## Common mistakes

| Mistake                                  | What happens                                                    |
| ---------------------------------------- | --------------------------------------------------------------- |
| `GET` request on the endpoint            | 404                                                             |
| No `Authorization` header                | 401                                                             |
| Basic authentication instead of Bearer   | 401                                                             |
| Unknown field or wrong type in the query | HTTP 200 with an `errors` array at the top level                |
| `orders` without order keys or a period  | The request is rejected. See **Points Balance & Transactions**. |