Sharing order events with the Events API

You can share order events with us via the Hakuna API so we can create and manage the insurance contracts appropriately.

Publish order placement events

Whenever an order is placed in your system, publish an order placement event by calling our events endpoint and passing us order, customer, and product information (including a product_reference for any protection products in the order):

Example

Request:

curl -X POST 'https://api.hellohakuna.com/sandbox/events' \
-H 'Bearer: sk_test_4eC39HqLyjWDarjtT1zdp7dc' \
-H 'Content-Type: application/json' \
-d '{
  "type": "order_placed",
  "payload": {
    "order_id": "ord-123",
    "placed_at": "2022-02-20T00:00:00.000Z",
    "order_currency": "eur",
    "customer": {
      "first_name": "Max",
      "last_name": "Mustermann",
      "email": "[e-mail]"
    },
    "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": 89900,
        "product_id": "prd-iphone14",
        "product_title": "iPhone 14",
        "product_brand": "Apple"
      },
      {
        "id": "line-item-id-3322",
        "quantity": 1,
        "price_amount": 8499,
        "product_id": "protection-item-id-323",
        "product_title": "Hakuna.care protection",
        "product_brand": "Hakuna",
        "custom_properties": {
          "product_reference": "prd-iphone14"
        }
      },
      {
        "id": "line-item-id-4411",
        "quantity": 1,
        "price_amount": 25500,
        "product_id": "prd-airpods-gen3",
        "product_title": "Airpods 3rd Generation",
        "product_brand": "Apple"
      }
    ]
  }
}'

Response:

{
  "event_id": "evt-7c1784a1-d96b-4ec6-b515-8dc4a5433cbe"
}

As a response, you'll receive the generated event ID.

Publish line item fulfillment events

Whenever you ship any of the products in an order, publish the line item fulfillment events for the fulfilled products by calling our events endpoint and passing us the order ID and a list of the fulfilled line items.

Hakuna does not require you to fulfill protection plan line items, but it may make sense to have your ERP system automatically fulfill them when the associated product is fulfilled.

Example request

curl -X POST 'https://api.hellohakuna.com/sandbox/events' \
-H 'Bearer: sk_test_4eC39HqLyjWDarjtT1zdp7dc' \
-H 'Content-Type: application/json' \
-d '{
  "type": "order_fulfillment_added",
  "payload": {
    "order_id": "ord-123",
    "fulfillment_items": [
      {
        "line_item_id": "line-item-id-3311",
        "quantity": 1,
        "fulfilled_at": "2022-02-21T12:51:14.158Z"
      },
      {
        "line_item_id": "line-item-id-4411",
        "quantity": 1,
        "fulfilled_at": "2022-02-21T12:51:14.158Z"
      }     
    ]
  }
}'

As a response, you'll receive the generated event ID.

Publish line item refund events

Whenever you refund any products in an order, publish the line item refund events by calling our events endpoint and passing us the order ID and a list of the refunded line items. Keep in mind that whenever a protected product is refunded, you must also refund the associated protection product.

Example request

curl -X POST 'https://api.hellohakuna.com/sandbox/events' \
-H 'Bearer: sk_test_4eC39HqLyjWDarjtT1zdp7dc' \
-H 'Content-Type: application/json' \
-d '{
  "type": "order_refund_added",
  "payload": {
    "order_id": "ord-123",
    "refund_items": [
      {
        "line_item_id": "line-item-id-3311",
        "quantity": 1,
        "refunded_at": "2022-02-21T12:51:14.158Z"
      },
      {
        "line_item_id": "line-item-id-3322",
        "quantity": 1,
        "refunded_at": "2022-02-21T12:51:14.158Z"
      },
      {
        "line_item_id": "line-item-id-4411",
        "quantity": 1,
        "refunded_at": "2022-02-21T12:51:14.158Z"
      }     
    ]
  }
}'

As a response, you'll receive the generated event ID.

Publish line item cancellation events

Whenever you cancel any products in an order, you will need to publish the line item cancellation events by calling our events endpoint and passing us the order ID and a list of the cancelled line items. Keep in mind that whenever a protected product is cancelled, you must also cancel the associated protection product.

Example request

curl -X POST 'https://api.hellohakuna.com/sandbox/events' \
-H 'Bearer: sk_test_4eC39HqLyjWDarjtT1zdp7dc' \
-H 'Content-Type: application/json' \
-d '{
  "type": "order_line_items_cancelled",
  "payload": {
    "order_id": "ord-123",
    "cancelled_line_items": [
      {
        "line_item_id": "line-item-id-3311",
        "cancelled_at": "2022-02-21T12:51:14.158Z"
      },
      {
        "line_item_id": "line-item-id-3322",
        "quantity": 1,
        "refunded_at": "2022-02-21T12:51:14.158Z"
      }    
    ]
  }
}'

As a response, you'll receive the generated event ID.

Publish order cancellation events

Whenever an entire order is cancelled for any reason, publish an order cancellation event by calling our events endpoint and passing us the order ID and the date and time the order was cancelled at.

Example request

curl -X POST 'https://api.hellohakuna.com/sandbox/events' \
-H 'Bearer: sk_test_4eC39HqLyjWDarjtT1zdp7dc' \
-H 'Content-Type: application/json' \
-d '{
  "type": "order_cancelled",
  "payload": {
    "order_id": "ord-123",
    "cancelled_at": "2022-02-20T15:00:00.000Z"
  }
}'

As a response, you'll receive the generated event ID.