Connection

Check that your API key works and see which scopes it carries.

Test the connection

GET /ping

Any valid API key, no scope needed.

Confirms that your API key is valid and returns the name, environment and scopes of your API client. Needs no particular scope. This is the only endpoint that answers without the data wrapper.

Example request

curl "https://shop.example.com/api/v1/ping" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json"

Responses

200 OK The key is valid.

{
  "client": {
    "name": "Example App",
    "environment": "live",
    "scopes": [
      "orders.write",
      "customers.read"
    ]
  },
  "server_time": "2026-10-14T14:05:00+02:00"
}

Response fields

Field	Type	Required	Description
`client`	object	required
`name`	string	required	Name of your API client as set by the shop operator.
`environment`	string	required	Whether the key belongs to a live or a test client. one of: `live`, `test`
`scopes`	array of string	required	Scopes granted to the key. If a scope you need is missing, ask the shop operator.
`server_time`	string (date-time)	required	Current server time with time zone offset.

Error responses

401 Unauthorized The API key is missing, malformed, wrong, paused, expired or revoked. The body is always the same and never names the reason.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key.",
    "details": []
  }
}

404 Not Found The path does not exist, the API is not enabled on this system, the order does not belong to the shop of your API client, or the customer, address or label value is not known to your API client.

{
  "error": {
    "code": "not_found",
    "message": "The requested resource does not exist.",
    "details": []
  }
}

429 Too Many Requests Too many requests. Either your API client used up its requests per minute (message Too many requests., with all rate limit headers), or too many failed authentications came in a short time (message Too many authentication attempts., only Retry-After). Both carry the code rate_limited.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "details": []
  }
}

500 Internal Server Error An unexpected error occurred on our side. Retry later.

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred.",
    "details": []
  }
}

All error codes: error code reference.