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.
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)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.
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": []
}
]
}
]'
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": []
}
]
}
]'
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.
Last modified 2d ago