API specification
Basic info about the Provisioning API available operations, endpoints, headers, rate limits, and error handling
Commerce Layer Provisioning API is a fast REST API 100% compliant with the JSON API specification (v1.0). It supports compound documents, sparse fieldsets, resource linking, filtering, sorting, pagination, and more. To learn more about how to leverage those features, the basic CRUD actions syntax and payloads you can refer to the Core API documentation:
All the strings passed to the API must be UTF-8 encoded.
Base endpoint
All API requests must be made over HTTPS to the following base endpoint:
Headers
Include the following HTTP request headers when making calls to the Provisioning API endpoints:
Header | Required | Details |
---|---|---|
| Must be | |
| Must be | |
| Must be | |
| Must be |
Where {{your_access_token}}
is the access token you get by authenticating to the Provisioning API.
API versioning
The Accept-Version header is optional and will be used to manage future versioning. When different versions of the Provisioning API are available you'll be able to request a specific one just by changing it as follows:
Where {{version}}
is the unique progressive number that identifies the version you want to use.
The latest version of the Provisioning API is v1 — use v1
as the Accept-Version header to make your calls.
Rate limits
The requests you perform to the Provisioning API are currently subject to the same rate limits as the uncacheable requests to the Core API in live mode and differentiated by limit type.
GET
requests
GET
requestsLimit type | Max number of requests | Time window |
---|---|---|
Average | 1000 (to all endpoints) | 1 min |
Burst | 250 (per endpoint) | 10 secs |
POST
requests
POST
requestsLimit type | Max number of requests | Time window |
---|---|---|
Average | 200 (to all endpoints) | 1 min |
Burst | 50 (per endpoint) | 10 secs |
The Core API /oauth/token
endpoint you need to use for authentication is subject to stricter limits (max 30 reqs / 1 min).
IP addresses that exceed the rates above will be blocked until the frequency of the specific call drops below the allowed limit.
Errors
Commerce Layer Provisioning API uses HTTP response codes to show the success or failure of an API request.
Codes in the
2xx
range indicate success.Codes in the
4xx
range indicate an error that failed given the information provided (e.g. bad request, failed validation, or authentication issues).Codes in the
5xx
range indicate an unhandled error (these are rare and should never happen).
For a complete list of all the possible error codes, messages, and descriptions please refer to the related section of the Core API documentation.
Correct error handling is important. We recommend writing code that gracefully handles all possible API exceptions.
Last updated