Skip to main content

GraphQL Overview

The GraphQL API provides a typed alternative to the REST API.

GraphQL is a data query and manipulation language that allows specifying what data is to be retrieved ("declarative data fetching") or modified.

It is available at:

POST/gql/v1
  • Authentication: add Authorization: Bearer <token> header for all data operations
  • Introspection: allowed without authentication (schema fetch only)

Headers​

All secured operations require the Authorization header:

{
  "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}

Take a look at the authentication guide for details on obtaining an access token.

Quick start (cURL)​

curl -X POST https://api.axro.com/gql/v1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "query": "query { products(page:1, limit:5) { totalPages products { productNumber brand stock } } }"
  }'

Queries​

products​

List products with filtering and pagination.

All arguments are optional.

NameTypeRequiredDescription
formatstring❌Response format: 'json' (default) or 'xml' (BMEcat 2005 format)
product_numberstring❌Filter by single or comma-separated AXRO product numbers (e.g., 'CANL055BK' or 'CANL055BK,CANL056WH')
oemstring❌Filter by single or comma-separated OEM numbers (e.g., '3016C002' or '3016C002,CF540A')
eanstring❌Filter by single or comma-separated EAN numbers (e.g., '4549292124699' or '4549292124699,4549292124706')
brandstring❌Filter by single or comma-separated brand names (e.g., 'HP,Canon,Epson')
categorystring❌Filter by single or comma-separated category IDs (e.g., '50593,50638')
pagestring❌Page number for pagination (default: 1)
limitstring❌Number of items per page (default: 100)

Example Request​

query {
  products(page: 1, limit: 10, brand: "HP") {
    totalPages
    products {
      productNumber
      ean
      brand
      stock
      stock
      price { fromQuantity toQuantity price }
      title { enGb deDe }
      category { id en de }
      modifiedAt
    }
  }
}

Example Response​

{
  "data": {
    "products": {
      "totalPages": 120,
      "products": [
        {
          "productNumber": "CANT7260C",
          "brand": "Canon",
          "oemNumber": "6944B002",
          "stock": 0,
          "price": [],
          "title": {
            "enGb": "Canon Toner C-EXV45 / 6944B002 Cyan (6944B002/6944B002AA)",
            "deDe": "Canon Toner C-EXV45 / 6944B002 Cyan (6944B002/6944B002AA)"
          },
          "category": {
            "id": 51158,
            "de": "Kopiertoner",
            "en": "Copy toner"
          },
          "modifiedAt": "2025-09-29 20:46:01+00:00"
        }
      ]
    }
  }
}

categories​

List all available categories.

Example Request​

query {
  categories { 
    id 
    de 
    en 
  }
}

Example Response​

{
  "data": {
    "categories": [
      {
        "id": 83104,
        "de": "SD-Karten",
        "en": "SD cards"
      },
      {
        "id": 83170,
        "de": "Autorennbahnen",
        "en": "Car racetracks"
      }
    ]
  }
}

brands​

List available brands for the current user (after applying visibility rules).

Example Request​

query { 
  brands { 
    brands 
  } 
}

Example Response​

{
  "data": {
    "brands": {
      "brands": [
        "Acer",
        "IBM",
        "Utax"
      ]
    }
  }
}

userInfo​

Basic info about the current user.

Example Request​

query {
  userInfo {
    email
    customer { 
      company 
    }
    billingAddress { 
      company 
      street 
      zip 
      city 
      country 
    }
  }
}

Example Response​

{
  "data": {
    "userInfo": {
      "email": "user@example.com",
      "customer": {
        "company": "Example Corp"
      },
      "billingAddress": {
        "company": "Example Corp",
        "department": "Purchasing",
        "street": "123 Example St",
        "zip": "10001",
        "city": "New York",
        "country": "US"
      }
    }
  }
}

billingAddress​

Retrieve the billing address for the current user.

Example Request​

query {
  billingAddress { 
    company 
    department 
    street 
    zip 
    city 
    country 
  }
}

Example Response​

{
  "data": {
    "billingAddress": {
      "company": "Example Corp",
      "department": "Accounting",
      "street": "456 Bill St",
      "zip": "10002",
      "city": "New York",
      "country": "US"
    }
  }
}

shippingAddresses​

List shipping addresses for the current user.

Example Request​

query {
  shippingAddresses {
    id 
    company 
    department 
    street 
    zip 
    city 
    country 
    phone 
    email 
    status 
    info
  }
}

Example Response​

{
  "data": {
    "shippingAddresses": [
      {
        "id": "7284adc6-db5f-55c1-9511-4d12b3a356f1",
        "company": "Example Corp",
        "department": "Logistics",
        "street": "123 Shipping Ln",
        "zip": "10001",
        "city": "New York",
        "country": "US",
        "email": "logistics@example.com",
        "phone": "+15551234",
        "status": "WAITING_APPROVAL",
        "info": "Please wait for approval."
      }
    ]
  }
}

orderList​

List orders for the current customer (via information service).

Response includes:

  • orders: [OrderItem]
  • totalPages: Int
  • error: String (nullable) — present on 400 responses; other errors appear as top-level GraphQL errors

Example Request​

query { 
  orderList(page: 1) { 
    totalPages 
    orders { 
      orderNumber 
      date 
      commission 
      currency 
      orderTotal 
      orderSource 
    } 
  } 
}

Example Response​

{
  "data": {
    "orderList": {
      "orders": [
        {
          "orderNumber": "522214",
          "date": "2025-08-19",
          "commission": "25310133",
          "currency": "EUR",
          "orderTotal": 247326,
          "orderSource": "Webshop"
        }
      ],
      "totalPages": 1,
      "error": null
    }
  }
}

orderDetails​

Retrieve order details by order number.

Response includes:

  • orderNumber: String
  • order: OrderDetailMessage
  • error: String (nullable) — present on 400 responses; other errors appear as top-level GraphQL errors

Example Request​

query {
  orderDetails(orderNumber: "1234567") {
    orderNumber
    order {
      invoiceNumber 
      date 
      commission 
      currency 
      orderTotal 
      orderSource 
      carrier
      shippingAddress { 
        company 
        street 
        zip 
        city 
      }
      billingAddress { 
        company 
        street 
        zip 
        city 
      }
      items { 
        productNumber 
        orderNumber 
        oemNumber 
        quantity 
        total 
      },
      "error": null
    }
  }
}

Example Response​

{
  "data": {
    "orderDetails": {
      "orderNumber": "123456",
      "order": {
        "invoiceNumber": "654321",
        "date": "2025-08-19",
        "commission": "25310133",
        "currency": "EUR",
        "orderTotal": 3080,
        "orderSource": "online",
        "shippingAddress": {
          "company": "AXRO GmbH",
          "street": "Schnackenburgallee 183-201",
          "zip": "22525",
          "city": "Hamburg"
        },
        "billingAddress": {
          "company": "AXRO GmbH",
          "street": "Schnackenburgallee 183-201",
          "zip": "22525",
          "city": "Hamburg"
        },
        "items": [
          {
            "productNumber": "EPSET20692",
            "orderNumber": "123456",
            "oemNumber": "c13s020692",
            "quantity": 1,
            "total": 2785
          },
          {
            "productNumber": "FR_AUTO_MD",
            "orderNumber": "123456",
            "oemNumber": "FR_AUTO_MD",
            "quantity": 1,
            "total": 295
          }
        ]
      }
    }
  }
}

shipmentList​

List shipments (tolerant to missing tracking data; empty strings if not available).

Arguments (all optional):

NameTypeRequiredDescription
pageInt❌Page number for pagination (default: 1)
orderNumberString❌Filter shipments by a specific order number

Response includes:

  • shipments: [ShipmentItem]
  • totalPages: Int
  • error: String (nullable) — present on 400 responses; other errors appear as top-level GraphQL errors

Example Request​

query {
  shipmentList(page: 1, orderNumber: "123456") {
    totalPages
    shipments {
      shipmentNumber 
      company 
      commission 
      status 
      date 
      shippingDate 
      trackingUrl 
      trackingCode 
      carrier
    }
  }
}

Example Response​

{
  "data": {
    "shipmentList": {
      "shipments": [
        {
          "shipmentNumber": "123456",
          "company": "AXRO GmbH",
          "commission": "25310133",
          "status": "OnTheWay",
          "date": "20.08.2025",
          "shippingDate": "19.08.2025",
          "trackingUrl": "https://www.ups.com/track?loc=en_GB&tracknum=1234567890",
          "trackingCode": "1234567890",
          "carrier": "UPS"
        }
      ],
      "totalPages": 1,
      "error": null
    }
  }
}

shipmentDetails​

Retrieve shipment details by shipment number.

Response includes:

  • shipmentNumber: String
  • shipment: ShipmentDetailMessage
  • error: String (nullable) — present on 400 responses; other errors appear as top-level GraphQL errors

Example Request​

query {
  shipmentDetails(shipmentNumber: "654321") {
    shipmentNumber
    shipment {
      orderNumbers
      invoiceNumber
      shipmentNumber
      shippingDate
      items { 
        productNumber 
        orderNumber 
        oemNumber 
        commission 
        quantity 
        total 
      }
    }
  }
}

Example Response​

{
  "data": {
    "shipmentDetails": {
      "shipmentNumber": "654321",
      "shipment": {
        "orderNumbers": [
          "111111"
        ],
        "invoiceNumber": "123456",
        "shipmentNumber": "654321",
        "shippingDate": "2025-08-19",
        "items": [
          {
            "productNumber": "EPSET20692",
            "orderNumber": "111111",
            "oemNumber": "c13s020692",
            "commission": "25310133",
            "quantity": 1,
            "total": 2785
          },
          {
            "productNumber": "FR_AUTO_MD",
            "orderNumber": "111111",
            "oemNumber": "FR_AUTO_MD",
            "commission": "25310133",
            "quantity": 1,
            "total": 295
          }
        ]
      },
      "error": null
    }
  }
}

trackingHistory​

Retrieve tracking history by shipment number. The response includes:

  • shipmentNumber: String
  • history: JSON (preserves dynamic keys like tracking codes and state indices)
  • error: String (nullable) — present if the service rejects the request or an error occurs

Example Request​

query {
  trackingHistory(shipmentNumber: "567517") {
    shipmentNumber
    history
  }
}

Example Response (success)​

{
  "data": {
    "trackingHistory": {
      "shipmentNumber": "123456",
      "history": {
        "00340434111111199160": {
          "states": {
            "0": {
              "time": "2025-08-18T13:34:00+02:00",
              "event": "Delivered successfully",
              "phase": "Delivery",
              "location": { "place": "" },
              "timezone": "Etc/GMT-2",
              "event_key": "H10",
              "phase_key": "H",
              "carrier_name": "DHL",
              "additional_info": []
            }
          },
          "estimatedDeliveryDate": {
            "date": "2025-08-18 14:35:00.000000",
            "timezone_type": 3,
            "timezone": "Europe/Berlin"
          },
          "delivered": true
        }
      },
      "error": null
    }
  }
}

Example Response (error)​

{
  "data": {
    "trackingHistory": {
      "shipmentNumber": "123456",
      "history": {},
      "error": "shipmentNumber does not belong to customerNumber"
    }
  }
}

Mutations​

shippingCreate​

Create a shipping address or validate without saving.

Arguments:

  • input: { company, department, firstname?, lastname?, street, zip, city, country, phone?, email? }
  • check: Boolean = false — if true, validates/normalizes without saving (no id in response)

Returns:

  • On success: suggestion (check=true) or created ShippingAddressInfo
  • On error: { error: true, status: Int, body: JSON } from the REST layer
NameTypeRequiredDescription
companystring✅Company name (max 35 chars)
departmentstring✅Department name (max 35 chars)
firstnamestring❌Contact first name
lastnamestring❌Contact last name
streetstring✅Street and number (max 35 chars)
zipstring✅ZIP/Postal code
citystring✅City (max 35 chars)
countrystring✅Country code (ISO 3166-1 alpha-2)
phonestring❌Phone number in format +4912345678 (+ and 5-20 digits)
emailstring❌Email address

Example Request (check=false)​

mutation createShipping {
  shippingCreate(
    input: {
      company: "Example Corp
      firstname: "John"
      lastname: "Doe"
      department: "Warehouse"
      street: "123 Shipping St"
      zip: "10001"
      city: "New York"
      country: "US"
      phone: "+4940123456"
      email: "test@example.com"
    }
    check: false
  )
}

Example Response​

{
  "data": {
    "shippingCreate": {
      "id": "95867100-43d3-5416-8729-74722012aef1",
      "company": "Example Corp",
      "department": "Warehouse",
      "firstname": "John",
      "lastname": "Doe",
      "street": "123 Shipping St",
      "zip": "10001",
      "city": "New York",
      "country": "US",
      "phone": "+4940123456",
      "email": "test@example.com",
      "status": "WAITING_APPROVAL",
      "info": "Please wait for approval."
    }
  }
}

Example Request (check=true)​

mutation createShipping {
  shippingCreate(
    input: {
      company: "Example Corp"
      department: "Warehouse"
      street: "Ballindamm 40"
      zip: ""
      city: ""
      country: "DE"
    }
    check: true
  )
}

Example Response​

{
  "data": {
    "shippingCreate": {
      "company": "Example Corp",
      "department": "Warehouse",
      "street": "Ballindamm 40",
      "zip": "20095",
      "city": "Hamburg",
      "country": "DE",
      "phone": null,
      "email": null,
      "status": "CHECK_ONLY",
      "info": "Suggested validated/normalized address. Not saved."
    }
  }
}

shippingUpdate​

Update a shipping address by ID (follows same permission rules as REST).

Arguments:

  • id: String!
  • input: { phone?, email? }

Example Request​

mutation updateShipping {
  shippingUpdate(
    id: "95867100-43d3-5416-8729-74722012aef1"
    input: { 
      phone: "+4940123456", 
      email: "test@example.com" 
    }
  )
}

Example Response​

{
  "data": {
    "shippingUpdate": {
      "id": "95867100-43d3-5416-8729-74722012aef1",
      "company": "Example Corp",
      "department": "Warehouse",
      "firstname": "John",
      "lastname": "Doe",
      "street": "123 Shipping St",
      "zip": "10001",
      "city": "New York",
      "country": "US",
      "phone": "+4940123456",
      "email": "test@example.com",
      "status": "USABLE",
      "info": "Can be used for shipping."
    }
  }
}

orderCreate​

Create/prepare an order, optionally placing it immediately.

Arguments:

  • order: { shippingAddressId: String!, cart: [{ productNumber: String!, quantity: Int! }]!, customReference?, additionalInformation? }
  • place: Boolean = false — if true, places the order with ?place=1

Example Request​

mutation createOrder {
  orderCreate(
    order: {
      shippingAddressId: "6f0c76f6-5af3-4a47-9a58-6e3f0a361234"
      cart: [ 
        { 
          productNumber: "CANL055BK",
          quantity: 2 
        },
        { 
          productNumber: "HP303A",
          quantity: 1 
        }
      ]
      customReference: "PO-1234"
      additionalInformation: "Leave at front desk"
    }
    place: true
  )
}

Example Response​

{
  "data": {
    "orderCreate": {
      "shipping_address": {
        "id": "ff81b118-1d53-5ebf-b99e-063c60ce9c2e",
        "company": "Acme Inc.",
        "department": "Office",
        "firstname": "John",
        "lastname": "Doe",
        "street": "123 Main St",
        "zip": "10001",
        "city": "New York",
        "country": "US",
        "email": "test@example.com",
        "phone": "+15551234"
      },
      "billing_address": {
        "company": "Acme Inc.",
        "department": "Accounting",
        "street": "123 Main St",
        "zip": "10001",
        "city": "New York",
        "country": "US"
      },
      "cart": [
        {
          "product_number": "CANL055BK",
          "quantity": 2,
          "difference": 0,
          "unit_price": 1000,
          "uhg_unit": 1200,
          "uhg_total": 1200,
          "sub_total": 2200
        },
        {
          "product_number": "HP303A",
          "quantity": 1,
          "difference": 0,
          "unit_price": 1000,
          "uhg_unit": 1200,
          "uhg_total": 1200,
          "sub_total": 2200
        }
      ],
      "toll": 295,
      "freight_costs": 490,
      "grand_total": 2985,
      "custom_reference": "PO-1234",
      "additional_information": "Leave at front desk",
      "order_placed": true,
      "place_order_url": "Order placed"
    }
  }
}

Tips​

  • Introspection is allowed without a token, but running real queries and mutations requires Authorization: Bearer <token>.
  • Field names in GraphQL use camelCase (e.g., productNumber, totalPages, enGb, deDe).