To get started, generate client credentials (client ID and client secret) in the Business Center portal. This is self-service — no manual approval is required.

Once you have credentials, call the token endpoint https://auth.pj.nu/oauth2/token to get an access token:

curl --request POST \
  --url https://auth.pj.nu/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=<your-client-id> \
  --data client_secret=<your-client-secret> \
  --data grant_type=client_credentials

This request will respond with an access token:

{
  "access_token": "<JWT-access-token>",
  "expires_in": 86399,
  "scope": "",
  "token_type": "bearer"
}

You can use this token by putting it in the Authorization header attached to your GraphQL request. Some queries and mutations require specific features to be enabled on your account, which are documented in the API reference.

If authentication fails, the error response follows the RFC7807 format:

{
  "title": "Unsupported grant type",
  "status": 400,
  "detail": "Unsupported grant type: invalid_grant_type"
}

The Insights API is a GraphQL API served over HTTPS. For more information about GraphQL visit https://graphql.org.

When making GraphQL queries, you can use HTTP POST or GET methods. A standard POST request should use the application/json content type, and include a JSON-encoded body of the following form:

{
  "query": "...",
  "variables": { "myVariable": "someValue", ... }
}

GraphQL response status codes differ from REST API status codes. A GraphQL API can return a 200 response code in cases where a REST API would return 4xx or 5xx. The response body will in that case contain some errors (see errors for more details). See the below example for the basic structure of the response:

{
  "data": { ... },
  "errors": [ ... ]
}

If there are no errors, the errors field will not be present in the response. When errors do occur, each error includes a message and an extension code:

{
  "errors": [
    {
      "message": "Access denied. Missing feature INSIGHTS_API_CLICK_AND_COST for shop id x.",
      "path": ["..."],
      "extensions": {
        "code": "FORBIDDEN"
      }
    }
  ],
  "data": null
}

The API includes an interactive GraphQL explorer at https://api.pj.nu/insights/graphql. Open it in a browser to explore the full schema, build queries, and run them in real time.

To authenticate, click the Connection Settings icon (cogwheel) next to the endpoint URL and add an Authorization header with your Bearer token:

Authorization: Bearer <your-access-token>

Generate a token using the authentication request shown above, then paste it in. The explorer uses schema introspection to autocomplete fields and show inline documentation as you build your query.

Reports are generated asynchronously. The general flow is:

1. Call requestShopOfferInventoryReport (or another report mutation) to queue the report.
2. Poll shopReports until the report state is CREATED.
3. Call createReportLinks to get a signed download URL.
4. Download and decompress the .csv.gz file from the signed URL.

Signed URLs expire after a short period, so download promptly after generating them. Reports are stored for 90 days and can also be viewed in Business Center.