ERP + E-commerce integration

Context

This integration path requires both ERP and e-commerce integration. You will still be responsible for the UI components on the PDP and in the cart that present protection plans as an opt-in next to the corresponding products.

Preparation

Create items

Using the list provided to you by your Hakuna Account Manager, add the required products/items representing protection plans to your inventory.

Share item IDs with Hakuna

Once you have manually created the items, please share the product/item IDs from your system with your Hakuna Account Manager.

As an example, let's pretend that you added an item representing a 1-year warranty extension to your ERP system and shared the ID "pl-prd-hakuna" with Hakuna.

E-commerce integration

Present protection plans

On the product detail page

On your product detail pages, your e-commerce system needs to present protection plans as an opt-in next to the corresponding protectable products. To find out what protection plan and information to display for a particular product, pass us the product information and the user session ID in an HTTP GET request.

As a response, you'll get the matching protection plan.

Example response

{
  "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": 1200,
      "price_currency": "eur",
      "product_reference": "prd-iphone14",
      "title": {
        "de": "1 Jahr Garantieerweiterung"
      },
      "insurance_details_url": "https://hellohakuna.com/plan-details"
    }
  ]
}

When a product is added to the cart with the associated protection plan selected, you must also add the selected plan as a line item to the cart, with a reference to the protected product as a custom property.

In the cart

In the cart, your e-commerce system needs to:

• display the relationship between associated protection plans and products

• present protection plans as an opt-in next to the corresponding unprotected products

To identify connected plans and products as well as unprotected products in the cart, pass us the cart ID and the user session ID in an HTTP GET request.

As a response, you'll get a list of all product and protection plan line item connections:

Example response

In this example response, you can see that there is one protected product and plan connection in the cart with the line item IDs line-item-id-3311 and line-item-id-3322.

{
  "cart_id": "cart-123",
  "plan_connections": [
    {
      "product_line_item_id": "line-item-id-3311",
      "plan_line_item_id": "line-item-id-3322"
    }
  ]
}

For all unprotected products in the cart, find and display the matching protection plans as an opt-in.

When a protection plan is selected from the cart, you must add an item to the cart that represents that plan, with a reference to the protected product as a custom property.

Manage your cart

Whenever your cart is updated, your e-commerce system needs to notify Hakuna of the cart updates and then perform any cart management actions returned by Hakuna.

Example request

curl -X POST 'https://api.hellohakuna.com/sandbox/orders' \
H 'Bearer: sk_test_4eC39HqLyjWDarjtT1zdp7dc' \
H 'Content-Type: application/json' \
d '{
  "cart_id": "cart-123",
  "user_session_id": "f4f78677-31ea-4fea-9d91-5fdd91119aa8",
  "cart_currency": "eur",
  "line_items": [
    {
      "id": "line-item-id-3311",
      "quantity": 1,
      "price_amount": 20000,
      "product_id": "prd-iphone14",
      "product_title": "iPhone 14",
      "product_brand": "Apple"
    },
    {
      "id": "line-item-id-3322",
      "quantity": 1,
      "price_amount": 2000,
      "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"
    }
  ]
}'

In the response, you'll get a list of necessary cart management actions that you need to take to reconcile your cart. Once you have completed these actions, you will need to notify Hakuna of these additional cart updates, then perform any additional cart management actions and notify Hakuna again, continuing this process until no further cart management actions are required.

Example response

This example response shows what cart management action you would need to take if the quantity of the protected product line-item-3311 was increased to 2.

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

Notify Hakuna of a successful checkout

When an order is successfully placed, your e-commerce system needs to notify Hakuna. This information allows our platform to connect the cart and order data with the order events you share through your ERP and the Hakuna API.

Example request

curl -X POST 'https://api.hellohakuna.com/sandbox/orders' \
H 'Bearer: sk_test_4eC39HqLyjWDarjtT1zdp7dc' \
H 'Content-Type: application/json' \
d '{
  "cart_id": "cart-123",
  "user_session_id": "f4f78677-31ea-4fea-9d91-5fdd91119aa8",
  "order_id": "ord-123"
}'

As a response, you'll get the accepted cart checkout data.

Example response

{
  "cart_id": "cart-123",
  "user_session_id": "f4f78677-31ea-4fea-9d91-5fdd91119aa8",
  "order_id": "ord-123"
}

ERP integration

Your ERP system must notify Hakuna whenever any of the following order events occur so that our platform can create and manage the protection for your customers accordingly:

• Order placement event: When an order is placed in your system

• Line item fulfillment event: When one or more line items are fulfilled in your system (e.g., after shipping)

• Line item refund event: When one or more line items are refunded in your system (e.g., after a product return)

• Order cancellation event: When an entire order is cancelled (e.g., because of a failed payment)

Publish order placement events

Let's pretend that a customer named Max Mustermann buys an iPhone 14 with a 1-year extended warranty and a phone case from you. You will need to publish an order placement event by calling our events endpoint and passing us order, customer, and product information. You can skip the custom property product_reference since it is only required in ERP-only integration.

Example request

curl -X POST 'https://api.hellohakuna.com/sandbox/orders' \
-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",
    "cart_id": "cart-123",
    "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": 112900,
        "product_id": "prd-iphone14",
        "product_title": "iPhone 14",
        "product_brand": "Apple"
      },
      {
        "id": "line-item-id-3322",
        "quantity": 1,
        "price_amount": 1200,
        "product_id": "pl-prd-hakuna",
        "product_title": "1 Jahr Garantieerweiterung",
        "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": "Silicone Case iPhone 14",
        "product_brand": "Apple"
      }
    ]
  }
}'

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

Example response

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

Publish line item fulfillment events

Once you ship Max's iPhone and the phone case, you'll need to publish the line item fulfillment events for the two products.

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. You can use the Hakuna API to check for connections between products and plans so you know which plans to fulfill when.

Example request

curl -X POST 'https://api.hellohakuna.com/sandbox/orders' \
-H 'Bearer: sk_test_4eC39HqLyjWDarjtT1zdp7dc' \
-H 'Content-Type: application/json' \
-d '{
  "type": "order_fulfillment_added",
  "payload": {
    "order_id": "ord-123",
    "fulfillment_line_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"
      }     
    ]
  }
}'

Publish line item refund events

Let's pretend that Max decides to return the iPhone and the phone case. Whenever a protected product is refunded, you must also refund the protection plan associated with that product. You can use the Hakuna API to check for connections between products and plans so you know which plan to refund.

Once you've refunded all of the products and associated protection plans, you will need to publish the line item refund events:

Example request

curl -X POST 'https://api.hellohakuna.com/sandbox/orders' \
-H 'Bearer: sk_test_4eC39HqLyjWDarjtT1zdp7dc' \
-H 'Content-Type: application/json' \
-d '{
  "type": "order_refund_added",
  "payload": {
    "order_id": "ord-123",
    "refund_line_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"
      }     
    ]
  }
}'

Publish order cancellation events

Let's rewind and pretend that Max changed his mind about the iPhone and the phone case, so he cancels his order before you can fulfill it. Whenever an entire order is cancelled for any reason, you will need to publish an order cancellation event:

Example request

curl -X POST 'https://api.hellohakuna.com/sandbox/orders' \
-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"
  }
}'

That's all you need to do!