Links
Comment on page

Using the Order feed

To create or update an Order with the Order feed, all you need to do is call our endpoint and pass us your order data.
HTTP method: POST
Sandbox endpoint: https://api.hellohakuna.com/sandbox/feeds/order
Production endpoint: https://api.hellohakuna.com/feeds/order
As a response, you'll receive a request ID, which you can use to track the status of your request.
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.

Example

Let's pretend that a customer named Max Mustermann bought an iPhone 14 with 1 year of all-round protection, which you already added to your ERP system as a protection product.
To create an Order, you just need to call our Order feed endpoint with the required data:
Make sure to replace the sample sandbox publishable key with your actual key if you try out this example. Also keep in mind that we're using the Offer that we created specifically for the iPhone 14. If you want to use the Offer we created for the product collection, just update the inputs (i.e., protection_line_item_id, plan_id, etc.). The structure of the request will be the same for Offers for product collections.
curl -X POST 'https://api.hellohakuna.com/sandbox/feeds/order' \
-H 'Bearer: sk_test_4eC39HqLyjWDarjtT1zdp7dc' \
-H 'Content-Type: application/json' \
-d '[
{
"id": "ord-XYZ-123",
"status": "placed",
"placed_at": 1683875934,
"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": "München",
"country": "de",
"zip": "81371"
},
"line_items": [
{
"id": "prd-iphone14",
"quantity": 1,
"product_data": {
"id": "prd-iphone14",
"price": {
"amount": 112900,
"currency": "eur"
},
"brand": "Apple",
"title": "iPhone 14"
},
"custom_properties": {
"protection_line_item_id": "prd-hakuna-care-iphone14"
},
"fulfillments": [],
"refunds": []
},
{
"id": "prd-hakuna-care-iphone14",
"quantity": 1,
"product_data": {
"id": "prd-hakuna-care-iphone14",
"price": {
"amount": 8464,
"currency": "eur"
},
"brand": "hakuna",
"title": "1 year of all-round protection"
},
"custom_properties": {
"offer_id": "off-eaf57888-8a68-4f23-8e68-137fc6dd48f4",
"plan_id": "pl-90e8f25b-6d83-4d2e-89da-71d8385cdf72"
},
"fulfillments": [],
"refunds": []
}
]
}
]'
As a response, you'll receive a request ID, like this:
{
"request_id": "req-6d3af6d1-6bfc-4eb1-a21c-ad345ead7955"
}
Then, whenever there's an evolutionary change to the Order (i.e., cancellation, fulfillment or refund), you'll just need to call our Order feed endpoint with the required data:
Since we only accept evolutionary changes to an Order, only the Order status, line item fulfillments, or refunds should be updated. The rest of the Order should stay the same.
Example of what the request would look like if the Order was cancelled
curl -X POST 'https://api.hellohakuna.com/sandbox/feeds/order' \
-H 'Bearer: sk_test_4eC39HqLyjWDarjtT1zdp7dc' \
-H 'Content-Type: application/json' \
-d '[
{
"id": "ord-XYZ-123",
"status": "cancelled",
"placed_at": 1683875934,
"cancelled_at": 1683876022,
"customer": {
"first_name": "Max",
"last_name": "Mustermann",
"email": "[email protected]",
"phone": "+491601234567"
},
"customer_billing_address": {
"address_line_1": "Musterstrasse 1",
"address_line_2": "",
"city": "München",
"country": "de",
"zip": "81371"
},
"line_items": [
{
"id": "prd-iphone14",
"quantity": 1,
"product_data": {
"id": "prd-iphone14",
"price": {
"amount": 112900,
"currency": "eur"
},
"brand": "Apple",
"title": "iPhone 14"
},
"custom_properties": {
"protection_line_item_id": "prd-hakuna-care-iphone14"
},
"fulfillments": [],
"refunds": []
},
{
"id": "prd-hakuna-care-iphone14",
"quantity": 1,
"product_data": {
"id": "prd-hakuna-care-iphone14",
"price": {
"amount": 8464,
"currency": "eur"
},
"brand": "hakuna",
"title": "1 year of all-round protection"
},
"custom_properties": {
"offer_id": "off-eaf57888-8a68-4f23-8e68-137fc6dd48f4",
"plan_id": "pl-90e8f25b-6d83-4d2e-89da-71d8385cdf72"
},
"fulfillments": [],
"refunds": []
}
]
}
]'
Example of what the request would look like if the iPhone 14 was shipped
Since they are virtual products, Hakuna protection plans do not need to be fulfilled independently. We just need to know when the protected product was delivered. Please leave the fulfillment array for any Hakuna line items empty.
curl -X POST 'https://api.hellohakuna.com/sandbox/feeds/order' \
-H 'Bearer: sk_test_4eC39HqLyjWDarjtT1zdp7dc' \
-H 'Content-Type: application/json' \
-d '[
{
"id": "ord-XYZ-123",
"status": "placed",
"placed_at": 1683875934,
"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": "München",
"country": "de",
"zip": "81371"
},
"line_items": [
{
"id": "prd-iphone14",
"quantity": 1,
"product_data": {
"id": "prd-iphone14",
"price": {
"amount": 112900,
"currency": "eur"
},
"brand": "Apple",
"title": "iPhone 14"
},
"custom_properties": {
"protection_line_item_id": "prd-hakuna-care-iphone14"
},
"fulfillments": [
{
"quantity": 1,
"fulfilled_at": 1683876082
}
],
"refunds": []
},
{
"id": "prd-hakuna-care-iphone14",
"quantity": 1,
"product_data": {
"id": "prd-hakuna-care-iphone14",
"price": {
"amount": 8464,
"currency": "eur"
},
"brand": "hakuna",
"title": "1 year of all-round protection"
},
"custom_properties": {
"offer_id": "off-eaf57888-8a68-4f23-8e68-137fc6dd48f4",
"plan_id": "pl-90e8f25b-6d83-4d2e-89da-71d8385cdf72"
},
"fulfillments": [],
"refunds": []
}
]
}
]'
Example of what the request would look like if the iPhone 14 was returned
Since they are virtual products, Hakuna protection plans do not need to be refunded independently. We just need to know when the protected product was refunded. Please leave the refunds array for any Hakuna line items empty.
curl -X POST 'https://api.hellohakuna.com/sandbox/feeds/order' \
-H 'Bearer: sk_test_4eC39HqLyjWDarjtT1zdp7dc' \
-H 'Content-Type: application/json' \
-d '[
{
"id": "ord-XYZ-123",
"status": "placed",
"placed_at": 1683875934,
"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": "München",
"country": "de",
"zip": "81371"
},
"line_items": [
{
"id": "prd-iphone14",
"quantity": 1,
"product_data": {
"id": "prd-iphone14",
"price": {
"amount": 112900,
"currency": "eur"
},
"brand": "Apple",
"title": "iPhone 14"
},
"custom_properties": {
"protection_line_item_id": "prd-hakuna-care-iphone14"
},
"fulfillments": [
{
"quantity": 1,
"fulfilled_at": 1683876082
}
],
"refunds": [
{
"quantity": 1,
"refunded_at": 1683876136
}
]
},
{
"id": "prd-hakuna-care-iphone14",
"quantity": 1,
"product_data": {
"id": "prd-hakuna-care-iphone14",
"price": {
"amount": 8464,
"currency": "eur"
},
"brand": "hakuna",
"title": "1 year of all-round protection"
},
"custom_properties": {
"offer_id": "off-eaf57888-8a68-4f23-8e68-137fc6dd48f4",
"plan_id": "pl-90e8f25b-6d83-4d2e-89da-71d8385cdf72"
},
"fulfillments": [],
"refunds": []
}
]
}
]'
After each successful request, you'll get a request ID as a response.