Links

Order feed

The Hakuna Order feed is the easiest way for you to create and manage Orders (and the protection products within them) on our platform.
The only thing you'll need to do is share your Order data with us whenever an Order is created or updated. From there, we'll manage the Orders and connected protection plans for you.
You can either provide us with all of your Orders, including ones that do not contain any protection products, or just the Orders that contain protection products.

Requirements

To ensure that we can manage your Orders and contained protection plans properly, you'll need to do the following:
Order ID - give each of your Orders a unique ID so that we can keep track of updates
Order status - indicate the status of the Order:
  • placed: the transaction is pending or fulfilled, not cancelled
  • cancelled: the transaction will not be fulfilled, either because you decided not to (e.g., failed payment) or because the customer cancelled it
Line item fulfillments and refunds - indicate the quantities of fulfillments and refunds for each line item
Connection between products and protection - products and protection products (i.e., plans) will be transmitted separately as line items, you'll need to link them by adding a reference (using your own IDs) to a protection product line item within each protected product line item
Hakuna brand in lowercase - ensure that the brand of the protection product line item is all lowercase (hakuna), and do not use any other variations (like Hakuna or hakuNa)

Using the Order feed

To create or update an Order, all you need to do is call our endpoint
POST https://api.hellohakuna.com/feeds/order and pass us your Order data.
Here's an example of a new Order for the Frutta Banana with "1 year of warranty extension":
You may not be able to collect all of the requested customer data or provide it in the required format. We accept empty strings for all customer and customer_billing_address data, except country.
curl -X POST 'https://api.hellohakuna.com/feeds/order' \
-H 'Bearer: sk_test_4eC39HqLyjWDarjtT1zdp7dc' \
-H 'Content-Type: application/json' \
-d '[
{
"id": "ord-XYZ-123",
"status": "placed",
"placed_at": 1669377053593,
"cancelled_at": null,
"customer": {
"first_name": "Max",
"last_name": "Mustermann",
"email": "[email protected]",
"phone": "+491601234567"
},
"customer_billing_address": {
"address_line_1": "Musterstrasse 1",
"address_line_2": "",
"city": "Musterstadt",
"country": "de",
"zip": "123456"
},
"line_items": [
{
"id": "prd-1234",
"quantity": 1,
"product_data": {
"id": "prd-1234",
"price": {
"amount": 10000,
"currency": "eur"
},
"brand": "Frutta",
"title": "Banana"
},
"custom_properties": {
"protection_line_item_id": "hak-ext-12"
},
"fulfillments": [],
"refunds": []
},
{
"id": "hak-ext-12",
"quantity": 1,
"product_data": {
"id": "hak-ext-12",
"price": {
"amount": 1200,
"currency": "eur"
},
"brand": "hakuna",
"title": "1 year of warranty extension"
},
"custom_properties": {
"offer_id": "off-12345",
"plan_id": "pl-54132"
},
"fulfillments": [],
"refunds": []
}
]
}
]'
As a response, you'll receive an HTTP Status code 202 with an empty body.
The Order feed works asynchronously. Please let us know if you are testing so that we can give you more immediate feedback.
Example of what the request would look like if the Order was cancelled
curl -X POST 'https://api.hellohakuna.com/feeds/order' \
-H 'Bearer: sk_test_4eC39HqLyjWDarjtT1zdp7dc' \
-H 'Content-Type: application/json' \
-d '[
{
"id": "ord-XYZ-123",
"status": "cancelled",
"placed_at": 1669377053593,
"cancelled_at": 1669380517455,
"customer": {
"first_name": "Max",
"last_name": "Mustermann",
"email": "[email protected]",
"phone": "+491601234567"
},
"customer_billing_address": {
"address_line_1": "Musterstrasse 1",
"address_line_2": "",
"city": "Musterstadt",
"country": "de",
"zip": "123456"
},
"line_items": [
{
"id": "prd-1234",
"quantity": 1,
"product_data": {
"id": "prd-1234",
"price": {
"amount": 10000,
"currency": "eur"
},
"brand": "Frutta",
"title": "Banana"
},
"custom_properties": {
"protection_line_item_id": "hak-ext-12"
},
"fulfillments": [],
"refunds": []
},
{
"id": "hak-ext-12",
"quantity": 1,
"product_data": {
"id": "hak-ext-12",
"price": {
"amount": 1200,
"currency": "eur"
},
"brand": "hakuna",
"title": "1 year of warranty extension"
},
"custom_properties": {
"offer_id": "off-12345",
"plan_id": "pl-54132"
},
"fulfillments": [],
"refunds": []
}
]
}
]'
Example of what the request would look like if the Frutta Banana was shipped
The fulfillment time of Hakuna plans should be the same as the fulfillment time of the protected product. Since they are virtual products, Hakuna plans do not need to be fulfilled independently. We just need to know when the protected product was delivered.
curl -X POST 'https://api.hellohakuna.com/feeds/order' \
-H 'Bearer: sk_test_4eC39HqLyjWDarjtT1zdp7dc' \
-H 'Content-Type: application/json' \
-d '[
{
"id": "ord-XYZ-123",
"status": "placed",
"placed_at": 1669377053593,
"cancelled_at": null,
"customer": {
"first_name": "Max",
"last_name": "Mustermann",
"email": "[email protected]",
"phone": "+491601234567"
},
"customer_billing_address": {
"address_line_1": "Musterstrasse 1",
"address_line_2": "",
"city": "Musterstadt",
"country": "de",
"zip": "123456"
},
"line_items": [
{
"id": "prd-1234",
"quantity": 1,
"product_data": {
"id": "prd-1234",
"price": {
"amount": 10000,
"currency": "eur"
},
"brand": "Frutta",
"title": "Banana"
},
"custom_properties": {
"protection_line_item_id": "hak-ext-12"
},
"fulfillments": [
{
"quantity": 1,
"fulfilled_at": 1667493412562
}
],
"refunds": []
},
{
"id": "hak-ext-12",
"quantity": 1,
"product_data": {
"id": "hak-ext-12",
"price": {
"amount": 1200,
"currency": "eur"
},
"brand": "hakuna",
"title": "1 year of warranty extension"
},
"custom_properties": {
"offer_id": "off-12345",
"plan_id": "pl-54132"
},
"fulfillments": [
{
"quantity": 1,
"fulfilled_at": 1667493412562
}
],
"refunds": []
}
]
}
]'
Example of what the request would look like if the Frutta Banana was returned
curl -X POST 'https://api.hellohakuna.com/feeds/order' \
-H 'Bearer: sk_test_4eC39HqLyjWDarjtT1zdp7dc' \
-H 'Content-Type: application/json' \
-d '[
{
"id": "ord-XYZ-123",
"status": "placed",
"placed_at": 1669377053593,
"cancelled_at": null,
"customer": {
"first_name": "Max",
"last_name": "Mustermann",
"email": "[email protected]",
"phone": "+491601234567"
},
"customer_billing_address": {
"address_line_1": "Musterstrasse 1",
"address_line_2": "",
"city": "Musterstadt",
"country": "de",
"zip": "123456"
},
"line_items": [
{
"id": "prd-1234",
"quantity": 1,
"product_data": {
"id": "prd-1234",
"price": {
"amount": 10000,
"currency": "eur"
},
"brand": "Frutta",
"title": "Banana"
},
"custom_properties": {
"protection_line_item_id": "hak-ext-12"
},
"fulfillments": [
{
"quantity": 1,
"fulfilled_at": 1667493412562
}
],
"refunds": [
{
"quantity": 1,
"refunded_at": 1667493419345
}
]
},
{
"id": "hak-ext-12",
"quantity": 1,
"product_data": {
"id": "hak-ext-12",
"price": {
"amount": 1200,
"currency": "eur"
},
"brand": "hakuna",
"title": "1 year of warranty extension"
},
"custom_properties": {
"offer_id": "off-12345",
"plan_id": "pl-54132"
},
"fulfillments": [
{
"quantity": 1,
"fulfilled_at": 1667493412562
}
],
"refunds": [
{
"quantity": 1,
"refunded_at": 1667493419345
}
]
}
]
}
]'
Please keep in mind that some of the fields in the example may vary slightly depending on the version of our API used. These minor differences have no impact on the general functionality of the Order feed. If you decide to use the Order feed, please get in touch with us so we can share the latest reference version.