Hakuna API (v2.0)

Download OpenAPI specification:Download

This document refers to v2.0 of the API, live after August 2023. This version allows you to notify Hakuna about your orders without having to manage any Hakuna-related data, or connections between products and protection plans. In case of any questions or feedback, please reach out to support@hellohakuna.com.

About this API

Hakuna's REST APIs use standard HTTP verbs, authentication, response codes, and JSON-encoded requests and responses.

Authentication

Hakuna uses API keys to authenticate requests. You can manage your API keys in your Merchant Console. Authentication is handled via bearer auth passing API key passed in the HTTP Authorization header.

curl https://api.hellohakuna.com/<ENDPOINT> \
-H "Authorization: Bearer <API_KEY>"

Versioning

We regularly update the Hakuna API as we release new features. Please pass the Hakuna-Version header on all API requests:

curl https://api.hellohakuna.com/<ENDPOINT> \
-H "Authorization: Bearer <API_KEY>" \
-H "Hakuna-Version: v2.0"

The current version of the Hakuna API is v2.0. If you omit the version header, your request will default to the earliest supported version of the API, which is currently v1.1.

Idempotent requests

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. When publishing an event, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of publishing the same event twice. To perform an idempotent request, pass the Hakuna-Idempotency-Key header with the request:

curl https://api.hellohakuna.com/<ENDPOINT> \
-H "Authorization: Bearer <API_KEY>" \
-H "Hakuna-Version: v2.0" \
-H "Hakuna-Idempotency-Key: fb8c6b4b-e1a6-4853-95ca-218fdcad20ae"

Environments Hakuna has two environments available: sandbox and production. Each environment has a unique URL and requires a unique API key.

Sandbox environment: https://api.hellohakuna.com/sandbox/

Production environment: https://api.hellohakuna.com/

Note: Before testing, please reach out to support@hellohakuna.com for setting up test cases, including connections between products and protection plans.

ERP integration

Endpoints to integrate with a merchant's ERP system

Publish event

You can publish order related event

SecuritybearerAuth
Request
Request Body schema: application/json
required

An event from accepted list

type
required
string

A type of event

required
object

A payload of event

Responses
201

Event has been accepted

400

The request was unacceptable due to invalid parameters.

401

Access token is missing or invalid

post/events
Request samples
application/json
{
  • "type": "order_placed",
  • "payload": {
    }
}
Response samples
application/json

An information about event

{
  • "event_id": "evt-7c1784a1-d96b-4ec6-b515-8dc4a5433cbe"
}

Retrieve plan and product line items connections for a given order

Retrieve plan and product line items connections by specifying the ID

SecuritybearerAuth
Request
query Parameters
order_id
required
string

The identifier of the Order in the merchant's system

Example: order_id=order-364587
Responses
200

A list of plan and product line items connections

401

Access token is missing or invalid

404

The requested resource doesn't exist.

get/order_plan_connections
Response samples
application/json

Plan connections

{
  • "order_id": "order-364587",
  • "plan_connections": [
    ]
}

E-commerce integration

Endpoints to integrate with a merchant's e-commerce system

Match protection plan for given product data

Match protection plan for given product data

SecuritybearerAuth
Request
query Parameters
product_id
required
string

The identifier of the product in the merchant's system

Example: product_id=prd-iphone14
product_brand
required
string

The product brand

Example: product_brand=Apple
product_title
required
string

The product title

Example: product_title=iPhone 14
product_category
required
string

The product category in merchant's system

Example: product_category=smartphones
product_price_amount
required
string

The product price amount in cents

Example: product_price_amount=112900
product_price_currency
required
string

The price currency three-letter code (ISO_4217 format).

Value: "eur"
Example: product_price_currency=eur
user_session_id
required
string

The identifier of the user session in the merchant's system

Example: user_session_id=f4f78677-31ea-4fea-9d91-5fdd91119aa8
Responses
200

Matched protection plans

401

Access token is missing or invalid

404

The requested resource doesn't exist.

get/plans
Response samples
application/json

Response with matched plans

{
  • "product": {
    },
  • "plans": [
    ]
}

Retrieve plan and product line item connections for a given cart

Retrieve plan and product line items connections by specifying the cart ID

SecuritybearerAuth
Request
query Parameters
cart_id
required
string

The identifier of the cart in the merchant's system

Example: cart_id=cart-123
user_session_id
required
string

The identifier of the user session in the merchant's system

Example: user_session_id=f4f78677-31ea-4fea-9d91-5fdd91119aa8
Responses
200

A list of plan and product line items connections

401

Access token is missing or invalid

404

The requested resource doesn't exist.

get/cart_plan_connections
Response samples
application/json

Plan connections

{
  • "cart_id": "cart-123",
  • "plan_connections": [
    ]
}

Notifies Hakuna about cart updates

Notify Hakuna about cart updates and identify cart management actions required for a given cart

SecuritybearerAuth
Request
Request Body schema: application/json
required

A cart update

cart_id
required
string

The identifier of the cart in the merchant's system.

user_session_id
required
string

The identifier of the user session in the merchant's system

cart_currency
required
string

The currency of the items in the cart in three-letter code (ISO_4217 format).

Value: "eur"
required
Array of objects

A list of line item objects, each containing information about an item in the cart.

Responses
201

Cart update has been accepted

400

The request was unacceptable due to invalid parameters.

401

Access token is missing or invalid

post/cart_updates
Request samples
application/json

An event describing a placed order

{
  • "cart_id": "cart-123",
  • "user_session_id": "f4f78677-31ea-4fea-9d91-5fdd91119aa8",
  • "cart_currency": "eur",
  • "line_items": [
    ]
}
Response samples
application/json

Accepted cart updated and required actions

{
  • "cart_id": "cart-123",
  • "user_session_id": "f4f78677-31ea-4fea-9d91-5fdd91119aa8",
  • "actions": [
    ]
}

Notifies Hakuna about successful checkout

Notifies Hakuna about successful checkout

SecuritybearerAuth
Request
Request Body schema: application/json
required

A successful checkout data

cart_id
required
string

The identifier of the cart in the merchant's system.

user_session_id
required
string

The identifier of the user session in the merchant's system

order_id
required
string

The unique identifier of the placed order for the cart

Responses
201

Cart checkout has been accepted

400

The request was unacceptable due to invalid parameters.

401

Access token is missing or invalid

post/cart_checkout
Request samples
application/json

Cart checkout data

{
  • "cart_id": "cart-123",
  • "user_session_id": "f4f78677-31ea-4fea-9d91-5fdd91119aa8",
  • "order_id": "ord-123"
}
Response samples
application/json

Accepted cart checkout data

{
  • "cart_id": "cart-123",
  • "user_session_id": "f4f78677-31ea-4fea-9d91-5fdd91119aa8",
  • "order_id": "ord-123"
}