Skip to main content

Getting started

The Pickware GraphQL API uses GraphQL over HTTPS. Every request — queries and mutations — is an HTTP POST to the GraphQL endpoint with a JSON body containing a query string and, optionally, a variables object and an operationName. GET is not supported; use POST even for read-only queries. The path segment after /api/graphql/ is the schema version the request is executed against. Every request must carry a bearer access token; see Authentication.

POST https://<your-pickware-api-domain>/api/graphql/2026-06-unstable
Content-Type: application/json

The Endpoint field on a token's detail page in the Pickware ERP administration shows the full GraphQL endpoint URL, ready to copy. The token endpoint, /api/oauth/token, is on the same domain.

Create a token​

In the Pickware ERP administration, open Settings → GraphQL API tokens and create a token with the products scope set to Read: the first query below needs products:read. Use Download .env in the dialog that follows to save the access key and the secret access key as pickware-graphql.env; the secret is shown only once. Authentication walks through the form.

Run your first query​

This query fetches the first five products and their pagination cursors. See the generated products query, Product type, and ProductFilterInput reference for all available fields and filters.

query FirstProducts {
  products(first: 5) {
    edges {
      cursor
      node {
        id
        productNumber
        gtin
        name
        physicalStock
        availableStock
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Minimal curl example​

Load the credentials from the downloaded pickware-graphql.env into your shell. It defines PICKWARE_GRAPHQL_ACCESS_KEY and PICKWARE_GRAPHQL_SECRET_ACCESS_KEY:

set -a; source pickware-graphql.env; set +a

Exchange them for an access token and keep the response's access_token value in a variable. Authentication covers this exchange in full, along with the access token lifetime and the scopes a token needs.

PICKWARE_GRAPHQL_ACCESS_TOKEN=$(curl --silent https://<your-pickware-api-domain>/api/oauth/token \
  --request POST \
  --header "Content-Type: application/json" \
  --data "{
    \"grant_type\": \"client_credentials\",
    \"client_id\": \"$PICKWARE_GRAPHQL_ACCESS_KEY\",
    \"client_secret\": \"$PICKWARE_GRAPHQL_SECRET_ACCESS_KEY\"
  }" | jq --raw-output .access_token)

Then send the query with that access token as a bearer token:

curl https://<your-pickware-api-domain>/api/graphql/2026-06-unstable \
  --request POST \
  --header "Authorization: Bearer $PICKWARE_GRAPHQL_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"query":"query FirstProducts { products(first: 5) { edges { node { id productNumber gtin name physicalStock availableStock } } pageInfo { hasNextPage endCursor } } }"}'

Using a GraphQL client library​

The curl example shows that the wire protocol is plain JSON over HTTPS, so any HTTP client works. For real integrations a GraphQL client is usually a better fit — it handles variable encoding, response typing, retries, and (with a generated SDK) schema-aware autocomplete. Some well-established options:

Pair any of these with a code generator (for example GraphQL Code Generator) to get types and helpers derived from the schema. Introspection is disabled on the production endpoint, so point the generator at the schema file instead: the SDL of 2026-06-unstable can be downloaded at https://pickware.dev/docs/schemas/2026-06-unstable/schema.graphql.

Pagination​

List fields use cursor-based pagination. Pass first to limit the page size and after with the endCursor from the previous response to fetch the next page. The shared PageInfo type describes the pagination metadata returned by connection fields.

For synchronization jobs, continue with Working with lists.