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

Payload

application/json

{"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"
},
{"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"
}
]
}
}

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": [{"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
}
]
}

E-commerce integration

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

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": {"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"
},
"insurance_details_url": "https://hellohakuna.com/plan-details"
}
]
}

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": [{"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
}
]
}

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

Payload

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": [{"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"
}
]
}

Response samples

application/json

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

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

Payload

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"
}

Hakuna API (v2.0)

About this API

Authentication

Versioning

Idempotent requests

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

ERP integration

Endpoints to integrate with a merchant's ERP system

Publish event

Request Body schema: application/jsonrequired

Retrieve plan and product line items connections for a given order

query Parameters

E-commerce integration

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

Match protection plan for given product data

query Parameters

Retrieve plan and product line item connections for a given cart

query Parameters

Notifies Hakuna about cart updates

Request Body schema: application/jsonrequired

Notifies Hakuna about successful checkout

Request Body schema: application/jsonrequired

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required