Hakuna API (v1.2)

Download OpenAPI specification:Download

This document refers to the API live after November 2022.

Hakuna's REST APIs use standard HTTP verbs, authentication and response codes. Hakuna uses JSON-encoded requests and responses. Don't hesitate to reach out with any questions or feedback. You can email Hakuna directly at support@hellohakuna.com.

Getting Started

The Hakuna API is used to request up-to-date protection Offers for displaying in your store alongside your products and to place and manage Orders when your customers buy protection.

Check out

Authentication

Hakuna uses API keys to authenticate requests. You can manage API keys in your Merchant Console. Authentication is handled via bearer auth passing API key passed in HTTP Authorization header.

Authorization: Bearer <API_KEY>

Offers

Endpoints to create and retrieve an Offer for a product or products collection in your store.

Create Offer

Real-time method to create an Offer for a specific product or products collection in your store. An Offer contains one or more protection plan options, prices for each and additional details to provide more information to your customers. Every Offer is valid until expriration date.

SecuritybearerAuth
Request
Request Body schema: application/json

The product or products collection you want to create an Offer for

One of:

Data to create offer

type
required
string (OfferType)

A type of an offer

Enum: "protection_product" "protection_products_collection"
required
object (Product)

A merchant product data

Responses
201

Offer has been created for provided product

400

The request was unacceptable due to invalid parameters or unsupported product.

401

Access token is missing or invalid

post/offers
Request samples
application/json
{
  • "type": "protection_product",
  • "product": {
    }
}
Response samples
application/json
{
  • "id": "ee589e89-e5a6-4742-9fe8-3d5e119a599f",
  • "type": "protection_product",
  • "created_at": 1645446874158,
  • "expired_at": 1648038918163,
  • "product": {
    },
  • "products_collection": null,
  • "plans": [
    ],
  • "marketing_content": {
    }
}

Retrieve Offer

Retrieve an Offer based on the ID. All fields of an Offer are returned.

SecuritybearerAuth
Request
path Parameters
offerId
required
string <uuidv4>

UUIDv4 of the Offer to retrieve

Example: ee589e89-e5a6-4742-9fe8-3d5e119a599f
Responses
200

An Offer

401

Access token is missing or invalid

404

The requested resource doesn't exist.

get/offers/{offerId}
Response samples
application/json
{
  • "id": "ee589e89-e5a6-4742-9fe8-3d5e119a599f",
  • "type": "protection_product",
  • "created_at": 1645446874158,
  • "expired_at": 1648038918163,
  • "product": {
    },
  • "products_collection": null,
  • "plans": [
    ],
  • "marketing_content": {
    }
}

Orders

Endpoints to place and manage Orders for protection plans from your customers.

Place Order

You can create a protection Order for your customer by providing us the selected plans and protected product data as line-items and the customer data. Only Offer IDs can be used which are not expired yet.

SecuritybearerAuth
Request
Request Body schema: application/json

Required data to create an Order

required
object

A customer information

required
object

A customer billing address.

required
Array of objects

A list of line item objects, each containing information about an item in the Order.

Responses
201

Order has been placed

400

The request was unacceptable due to invalid parameters or unsupported customer location.

401

Access token is missing or invalid

post/orders
Request samples
application/json

A request example to place order

{
  • "customer": {
    },
  • "customer_billing_address": {
    },
  • "line_items": [
    ]
}
Response samples
application/json

A placed order

{
  • "id": "797f73eb-22e0-4145-b8af-d6fdac71613d",
  • "customer": {
    },
  • "customer_billing_address": {
    },
  • "line_items": [
    ],
  • "status": "placed",
  • "cancelled_at": null,
  • "cancel_reason": null,
  • "refunds": [ ],
  • "fulfillments": [ ]
}

Retrieve Order

Retrieve an Order by specifying the ID. All fields of an Order are returned.

SecuritybearerAuth
Request
path Parameters
orderId
required
string <uuidv4>

UUIDv4 of the Order to retrieve

Example: 797f73eb-22e0-4145-b8af-d6fdac71613d
Responses
200

An Order

401

Access token is missing or invalid

404

The requested resource doesn't exist.

get/orders/{orderId}
Response samples
application/json

A placed order

{
  • "id": "797f73eb-22e0-4145-b8af-d6fdac71613d",
  • "customer": {
    },
  • "customer_billing_address": {
    },
  • "line_items": [
    ],
  • "status": "placed",
  • "cancelled_at": null,
  • "cancel_reason": null,
  • "refunds": [ ],
  • "fulfillments": [ ]
}

Create fulfillment for Order

Create a fulfillment for a specific Order by specifying the Order ID and fulfilled items. This is required for us to actually activate the protection. Fulfillment generally means that the product was shipped.

SecuritybearerAuth
Request
path Parameters
orderId
required
string <uuidv4>

UUIDv4 of the Order to retrieve

Example: 797f73eb-22e0-4145-b8af-d6fdac71613d
Request Body schema: application/json

Required data to create a fulfillment

required
Array of objects

A list of fulfilled line items.

Responses
201

Created fulfillment

400

The request was unacceptable due to invalid parameters.

401

Access token is missing or invalid

404

The requested resource doesn't exist.

post/orders/{orderId}/fulfillments
Request samples
application/json

A request to create a fulfillment

{
  • "fulfillment_line_items": [
    ]
}
Response samples
application/json

A fulfillment

{
  • "id": "0a5eb87d-2d59-4d42-8734-df3593f7d455",
  • "fulfillment_line_items": [
    ]
}

Cancel Order

Cancel an Order by specifying the ID. We will cancel the whole Order and the cancellation will be only accepted, if the Order has not been fulfilled yet.

SecuritybearerAuth
Request
path Parameters
orderId
required
string <uuidv4>

UUIDv4 of the Order to retrieve

Example: 797f73eb-22e0-4145-b8af-d6fdac71613d
Request Body schema: application/json

Required data to cancel an Order

reason
string

The reason for the Order cancellation.

Responses
200

An Order

400

The request was unacceptable due to the Order cancel decline.

401

Access token is missing or invalid

404

The requested resource doesn't exist.

post/orders/{orderId}/cancel
Request samples
application/json

A request to cancel an order

{
  • "reason": "customer"
}
Response samples
application/json

A cancelled order

{
  • "id": "797f73eb-22e0-4145-b8af-d6fdac71613d",
  • "customer": {
    },
  • "customer_billing_address": {
    },
  • "line_items": [
    ],
  • "status": "cancelled",
  • "cancelled_at": 1645453287866,
  • "cancel_reason": "customer",
  • "refunds": [ ],
  • "fulfillments": [ ]
}

Create refund for Order

Create a refund for one or all items of an Order by specific the Order ID and line_items_ids. This can be necessary if a customer revokes one or multiple items from their pruchase in your store. Only possible for 30 days after fulfillment.

SecuritybearerAuth
Request
path Parameters
orderId
required
string <uuidv4>

UUIDv4 of the Order to retrieve

Example: 797f73eb-22e0-4145-b8af-d6fdac71613d
Request Body schema: application/json

Required data to create a refund

required
Array of objects

A list of refunded line items.

Responses
201

Created refund

400

The request was unacceptable due to invalid parameters.

401

Access token is missing or invalid

404

The requested resource doesn't exist.

post/orders/{orderId}/refunds
Request samples
application/json

A request to create a refund

{
  • "refund_line_items": [
    ]
}
Response samples
application/json

A refund object

{
  • "id": "f55ca068-1860-4970-82d8-c77388554f9c",
  • "refund_line_items": [
    ]
}

Order feed

Endpoints to add merchant orders to Hakuna platform

Add merchant Orders to Hakuna platform for future processing

You can manage protection Orders for your customers by providing us with your Order data (ID, status, line item fulfillments and refunds, connection between products and protection) whenever an Order is created or updated.

SecuritybearerAuth
Request
Request Body schema: application/json

Required data to add merchant Orders

required
Array of objects

A list of orders in the merchant system

Responses
202

Accepted orders

400

The request was unacceptable due to invalid parameters.

post/feeds/order
Request samples
application/json

A request to add orders to feed

{
  • "orders": [
    ]
}
Response samples
application/json
{
  • "error_code": "invalid_request_parameters",
  • "validation_errors": [
    ]
}