# Merchant REST API

## Usage

This is an authenticated API that is intended to be used by a merchant to retrieve or configure data within Okendo. It is **not** intended to be used on-site or in any client-side code and doing so will put your data at risk. For public and client-side use, see the [storefront-rest-api](https://docs.okendo.io/on-site/storefront-rest-api "mention").

## Basics

This API is organised around REST with resource-based CRUD operations. Parameters for GET requests should be provided in the query string whereas POST/PUT request parameters should be provided as JSON in the body. JSON is also used for responses, including errors.

## Authentication

Authentication to the API is performed via HTTP Basic Auth. The username is your Okendo User ID and the password is a unique, 32-character string. Both your username and password can be found in the integration settings section of the Okendo app. An example authorisation header is provided below:

`Basic MDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAwOldlTG92ZVRoYXRZb3VUb29rVGhlVGltZVRvRG9UaGlz`

All requests must be made over HTTPS.

## Pagination

When listing large amounts of data, not all of it can be returned in a single request. We use pagination to break data up into reasonably sized chunks. When listing a resource, the response may include a `nextUrl` property to indicate that another page of results is available:

```json
{
    "reviews": [],
    "nextUrl": "/reviews..."
}
```

Append the `nextUrl` to the base path and make a GET request to that URL to retrieve the next page of results. Repeat this process until you have all the results you need or there are no more pages of results (there will be no `nextUrl`).

## Rate Limiting

This API allows a consistent rate of 2 requests per second, with a small burst capacity above that. Exceeding this limit will result in requests failing with an HTTP 429 (Too Many Requests) error code.

## Versioning

Versioning is done via an HTTP header containing the required version. New versions of the API are released periodically. Provide the `okendo-api-version` header with a valid value in all requests. Valid versions:

* 2025-02-01