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.
Hakuna's REST APIs use standard HTTP verbs, authentication, response codes, and JSON-encoded requests and responses.
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>"
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.
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"
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.
You can publish order related event
Event has been accepted
The request was unacceptable due to invalid parameters.
Access token is missing or invalid
{- "type": "order_placed",
- "payload": {
- "order_id": "ord-123",
- "placed_at": "2022-02-20T00:00:00.000Z",
- "order_currency": "eur",
- "cart_id": "cart-123",
- "customer": {
- "first_name": "Max",
- "last_name": "Mustermann",
- "email": "max.mustermann@example.com"
}, - "customer_billing_address": {
- "address_line_1": "Musterstrasse",
- "address_line_2": "1",
- "city": "Musterstadt",
- "country": "de",
- "zip": "123456"
}, - "line_items": [
- {
- "id": "line-item-id-3311",
- "quantity": 1,
- "price_amount": 112900,
- "product_id": "prd-iphone14",
- "product_title": "iPhone 14",
- "product_brand": "Apple",
- "product_category": "electronics"
}, - {
- "id": "line-item-id-3322",
- "quantity": 1,
- "price_amount": 8464,
- "product_id": "pl-prd-hakuna",
- "product_title": "Hakuna.care protection",
- "product_brand": "Hakuna",
- "custom_properties": {
- "product_reference": "prd-iphone14"
}
}, - {
- "id": "line-item-id-4411",
- "quantity": 1,
- "price_amount": 1200,
- "product_id": "prd-bb-32",
- "product_title": "Silikon Case iPhone 14",
- "product_brand": "Apple"
}
]
}
}
An information about event
{- "event_id": "evt-7c1784a1-d96b-4ec6-b515-8dc4a5433cbe"
}
Retrieve plan and product line items connections by specifying the ID
A list of plan and product line items connections
Access token is missing or invalid
The requested resource doesn't exist.
Plan connections
{- "order_id": "order-364587",
- "plan_connections": [
- {
- "product_line_item_id": "line-item-id-3311",
- "plan_line_item_id": "line-item-id-3322"
}, - {
- "product_line_item_id": "line-item-id-4411",
- "plan_line_item_id": null
}
]
}
Match protection plan for given product data
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). 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 |
Matched protection plans
Access token is missing or invalid
The requested resource doesn't exist.
Response with matched plans
{- "product": {
- "id": "prd-iphone14",
- "category": "smartphones",
- "title": "iPhone 14",
- "brand": "Apple",
- "price_amount": 112900,
- "price_currency": "eur"
}, - "plans": [
- {
- "merchant_product_id": "pl-prd-hakuna",
- "price_amount": 8464,
- "price_currency": "eur",
- "product_reference": "prd-iphone14",
- "title": {
- "de": "Hakuna.care protection"
},
}
]
}
Retrieve plan and product line items connections by specifying the cart ID
A list of plan and product line items connections
Access token is missing or invalid
The requested resource doesn't exist.
Plan connections
{- "cart_id": "cart-123",
- "plan_connections": [
- {
- "product_line_item_id": "line-item-id-3311",
- "plan_line_item_id": "line-item-id-3322"
}, - {
- "product_line_item_id": "line-item-id-4411",
- "plan_line_item_id": null
}
]
}
Notify Hakuna about cart updates and identify cart management actions required for a given cart
A cart update
Cart update has been accepted
The request was unacceptable due to invalid parameters.
Access token is missing or invalid
An event describing a placed order
{- "cart_id": "cart-123",
- "user_session_id": "f4f78677-31ea-4fea-9d91-5fdd91119aa8",
- "cart_currency": "eur",
- "line_items": [
- {
- "id": "line-item-id-3311",
- "quantity": 2,
- "price_amount": 112900,
- "product_id": "prd-iphone14",
- "product_title": "iPhone 14",
- "product_brand": "Apple"
}, - {
- "id": "line-item-id-3322",
- "quantity": 1,
- "price_amount": 8464,
- "product_id": "pl-prd-hakuna",
- "product_title": "Hakuna.care protection",
- "product_brand": "Hakuna",
- "custom_properties": {
- "product_reference": "prd-iphone14"
}
}, - {
- "id": "line-item-id-4411",
- "quantity": 1,
- "price_amount": 1200,
- "product_id": "prd-bb-32",
- "product_title": "Silikon Case iPhone 14",
- "product_brand": "Apple"
}
]
}
Accepted cart updated and required actions
{- "cart_id": "cart-123",
- "user_session_id": "f4f78677-31ea-4fea-9d91-5fdd91119aa8",
- "actions": [
- {
- "type": "update_line_item",
- "payload": {
- "line_item_id": "line-item-id-3322",
- "line_item_quantity": 2
}
}
]
}
Notifies Hakuna about successful checkout
A successful checkout data
Cart checkout has been accepted
The request was unacceptable due to invalid parameters.
Access token is missing or invalid
Cart checkout data
{- "cart_id": "cart-123",
- "user_session_id": "f4f78677-31ea-4fea-9d91-5fdd91119aa8",
- "order_id": "ord-123"
}
Accepted cart checkout data
{- "cart_id": "cart-123",
- "user_session_id": "f4f78677-31ea-4fea-9d91-5fdd91119aa8",
- "order_id": "ord-123"
}
Retrieve available plans and a link to the Hakuna Assist checkout
A list of plans and a link to a Hakuna Assist checkout
Access token is missing or invalid
The requested resource doesn't exist.
Assist Checkouts
{- "checkout_type": "assist",
- "order_id": "order-364587",
- "available_plans": [
- {
- "line_item_id": "line-item-id-3311",
- "product_reference": "product-123",
- "plan_price_amount": 4999,
- "plan_price_currency": "eur",
- "country": "de"
}, - {
- "line_item_id": "line-item-id-3311",
- "product_reference": "product-123",
- "plan_price_amount": 3999,
- "plan_price_currency": "eur",
- "country": "at"
}
]
}