ERP-only integration

Context

The ERP-only integration path is the least invasive as it does not require any e-commerce integration, but it does mean that your e-commerce system will be responsible for:

• mapping protection plans to products (i.e., using a custom property)

• presenting protection plans as an opt-in next to protectable products

• keeping selected protection plan quantities in the cart in sync with the protected product, even when zeroed out (e.g., removed from the cart)

• tracking the connection between the protection plan and the protected product

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 "protection-item-id-323" with Hakuna.

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 1 year of Hakuna.care protection 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 (including the custom property product_reference, which is required for all line items containing a protection plan in ERP-only integration):

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

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-234800",
    "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": 20000,
        "product_id": "prd-iphone14",
        "product_title": "iPhone 14",
        "product_brand": "Apple"
      },
      {
        "id": "line-item-id-3322",
        "quantity": 1,
        "price_amount": 2000,
        "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": 1200,
        "product_id": "prd-bb-32",
        "product_title": "Silicone Case iPhone 14",
        "product_brand": "Apple"
      }
    ]
  }
}'

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.

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_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.

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_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!