Get started API reference

ERP + E-commerce client integration

Context

Use the e-commerce client integration to offer product protection to your customers in your online store. Our client SDK takes care of matching protection plans to products, displaying the right content, managing the selection states, and preparing line items for the cart so that you only need to use the Hakuna API to perform cart updates, confirm successful checkouts, and share order events with Hakuna.

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 1 year of Hakuna.care to your ERP system and shared the ID "pl-prd-hakuna" with Hakuna.

E-commerce client integration

Initialize the Hakuna elements and client SDK

To ensure that your customers see your tailored protection plans, content, and design, add the following script to your product detail pages and your cart page.

The Hakuna elements are fully customizable, so we can adjust the colours, fonts, branding, content, etc. to make them perfectly fit your business! Just contact your Hakuna Account Manager for more information.

Render the Hakuna elements

To actually display the offering on a page and give your customers the option to add protection plans to the products they're purchasing, you need to render the Hakuna elements on the product detail pages and in the cart.

On the product detail page

On the product detail page, the Hakuna elements give customers the option to add a protection plan to a product before they add it to the cart. If they click on the link to learn more, a modal with a button to add the protection plan and more information about the offering will pop up.

To render the Hakuna elements on the product detail page, place the <hakuna-details-page></hakuna-details-page> custom element with the following attributes of your product where you want them to be displayed on the page:

interface Attributes {
  productId: string;
  productBrand: string;
  productTitle: string;
  productCategory: string;
  productPriceAmount: number; // product price in cents
  productPriceCurrency: 'eur'; // product price currency code
}
Example
<hakuna-details-page
	product-id="444010197"
	product-brand="Apple"
	product-title="iPhone 14"
	product-category="smartphones"
	product-price-amount="20000"
	product-price-currency="eur"
></hakuna-details-page>

When a customer clicks the "Add to Cart" button, you need to add the product and the selected protection plan as line items to your cart.

The Hakuna SDK provides a method to get the selected protection plan on the product details page. Use hakuna.detailsPage.getSelectedPlan in your "Add to Cart" button click handler. If the customer has selected a protection plan, getSelectedPlan will return a Plan object:

interface PlanData {
	title: string;
	price_amount: number; // in cents
	price_currency: 'eur';
	merchant_product_id: string;
}

When items have been added to your cart, your backend needs to notify Hakuna about the cart update via the Hakuna API endpoint POST/cart_updates.

Example

Here's an example of a request to notify Hakuna that an iPhone and the corresponding protection plan have been added to the cart:

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

In the cart

In the cart, the Hakuna elements enable customers to add and/or manage their protection plan for each line item. They can see which products they have already opted to add a protection plan to, add a protection plan to any unprotected products, and remove previously added protection plans.

To render the Hakuna elements in the cart, place the <hakuna-cart-item></hakuna-cart-item> custom element with the following attributes below each item in the cart:

interface Attributes {
  cartId: string;
  lineItemId: string;
  productId: string;
  productBrand: string;
  productTitle: string;
  productCategory: string;
  productPriceAmount: number; // product price in cents
  productPriceCurrency: 'eur'; // product price currency code
  itemQuantity: number;
}
Example
<hakuna-cart-item
  cart-id="cart-123"
	line-item-id="li-3211"
	item-quantity="1"
	product-id="444010197"
	product-brand="Apple"
	product-title="iPhone 14"
	product-category="smartphones"
	product-price-amount="20000"
	product-price-currency="eur"
></hakuna-cart-item>

To keep track of changes to selected protection plans you need to subscribe to all HakunaCartItem elements. Whenever a protection plan is selected, the corresponding HakunaCartItem element emits a planSelected event, and whenever a protection plan is unselected, it emits a planUnselected event.

When a protection plan gets selected, you need to add the selected protection plan line item to your cart, and when a protection plan gets unselected you need to remove the protection plan line item from your cart.

Hakuna SDK provides a method to subscribe to events from all HakunaCartItem elements on the page: hakuna.on(eventType, callback).

When a protection plan gets selected, we will call the provided callback with the following data:

interface Payload {
  title: string;
	price_amount: number; // in cents
	price_currency: 'eur';
	merchant_product_id: string;
}

When a protection plan gets unselected, we will call the provided callback with the following data:

interface Payload {
  title: string;
	price_amount: number; // in cents
	price_currency: 'eur';
	merchant_product_id: string;
	plan_line_item_id: string;
}

When items have been added to or removed from your cart, your backend needs to notify Hakuna about the cart update via the Hakuna API endpoint POST/cart_updates.

Example

Here's an example of a request to notify Hakuna that the quantity of the iPhone in the cart has been increased to 2:

curl -X POST 'https://api.hellohakuna.com/sandbox/cart_updates' \
-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": 2,
      "price_amount": 20000,
      "product_id": "444010197",
      "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"
    }
  ]
}'

As a response, you'll receive confirmation that the cart update has been synced as well as the cart management actions you need to take based on the provided cart update:

Here's the request:

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

Confirm successful checkout

When the checkout is completed successfully, your backend needs to notify Hakuna via the Hakuna API endpoint POST/cart_checkout.

Example

Here's an example of a request to notify Hakuna of a successful checkout:

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:

{
  "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 the successful checkout that you previously shared with Hakuna related to a transaction involving a customer named Max Mustermann who bought an iPhone 14 with 1 year of Hakuna.care protection 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.

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

Example
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": "max.mustermann@example.com"
    },
    "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": 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"
        }
      }
    ]
  }
}'

Response:

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

Publish line item fulfillment events

Once you ship Max's iPhone, you'll need to publish the line item fulfillment events for the product.

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

Here's an example request to publish line item fulfillment events for the iPhone and the phone case:

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_items": [
      {
        "line_item_id": "line-item-id-3311",
        "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. Whenever a protected product is refunded, you must also refund the protection plan associated with that product.

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

Example

Here's an example request to publish the line item refund events for the iPhone and the plan:

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_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"
      }   
    ]
  }
}'

Publish order cancellation events

Let's rewind and pretend that Max changed his mind about the iPhone, 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
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!

PreviousERP + E-commerce integrationNextFrontend widget integration

Last updated