Getting started
The Pickware GraphQL API uses GraphQL over HTTPS and is served by the Shopware 6 shop itself. Every request, queries and mutations alike, is an HTTP POST to the shop's 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.
POST https://<your-shop-domain>/api/graphql
Content-Type: application/json
<your-shop-domain> is the domain the shop's administration runs on; the Endpoint field on a token's detail page shows the full URL, ready to copy. The path carries no version: the endpoint serves the schema that ships with the installed Pickware version, see Versioning. Every request must carry a bearer access token, see Authentication.
Create a token
In the Shopware administration, open Settings → System → Integrations, switch to the GraphQL API tokens tab, 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 at the shop's token endpoint 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-shop-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-shop-domain>/api/graphql \
--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:
- Node / TypeScript:
graphql-requestfor a minimal client,@urql/corefor caching and React/Vue bindings, or Apollo Client when you also want normalized caching. - PHP:
softonic/graphql-clientfor a Guzzle-based HTTP client, orgmostafa/php-graphql-clientfor fluent query building. - Python:
gql(sync and asyncio transports, schema-aware) or the lighterpython-graphql-client.
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 in production shops, 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/on-premises/schema.graphql. Versioning tells you which schema your Pickware version serves.
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.