Using the API


Hakuna uses API keys to authenticate requests.
API keys carry many privileges such as creating and managing Orders, so it is important to keep them private and secure. They should live primarily in your backend. Do not hardcode or share API keys (particularly in your source version control system).
Authentication is handled via HTTP headers, and the Authorization header.
curl<ENDPOINT> \
-H "Authorization: Bearer <API_KEY>"


Hakuna has two environments available: sandbox and production. The environments have separate URLs and require the associated API key, which you can find in the Merchant Console. The URLs are: - Sandbox API - Production API

Managing API keys

In the Hakuna Merchant Console, you will be able to generate or revoke API keys for both production and sandbox environments. Be aware that any changes to existing API keys will be reflected immediately and could cause unwanted side effects.

API Version

Hakuna makes updates to the APIs on a regular basis, as we release new features. To allow you to update your integration when you are ready, we allow for a Hakuna-Version header to be passed on all API requests.
If you omit the version header, your request will default to the earliest supported version of the API, which is currently v1.1.
curl<ENDPOINT> \
-H "Hakuna-Version: v1.2"

API Responses

Status Codes

The following table summarizes the HTTP response codes you may receive from the Hakuna REST API.
Bad Request
Entity Not Found

Error Responses

Hakuna uses conventional HTTP response codes to indicate the success or failure of an API request. HTTP codes in the 2XX range indicate a successful request, whereas codes in the 4XX range indicate a failed request, usually due to invalid inputs or operations.
The format of the payload for all errors is common. When an unsuccessful request occurs, you will receive a payload in the following format:
"error": {
"error_code": "supported_error_code",
"validation_errors": []
All error payloads will contain a unique error_code which you can use to identify the error. In case of a badly formed request, Hakuna will also return additional validation_errors.
The following error_codes are supported:
  • invalid_request_parameters – If one of the required parameters in a request is missing or invalid. Human readable error messages are returned in validation_errors field.
  • product_unsupported – If you try to create an Offer for an unsupported product.
  • location_unsupported – If you try to create an Order for unsupported customer address location (country code).
  • cancel_decline – If you try to cancel an Order that can not be cancelled anymore (e.g., Order is already fulfilled or cancelled).