# 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](/on-site/storefront-rest-api.md).

## 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.okendo.io/merchant-rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.