Powered by Redocly

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, including prices, plus additional details that you can provide to your customers. Every Offer is valid until the expiration date.

SecuritybearerAuth
Request
Request Body schema: application/json

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

type
required
string

A type of an Offer

country
string = 2 characters
Default: "de"

Two-letter country code (ISO 3166-1 alpha-2 format) in lower case. Germany ("de") by default.

sales_channel
string
Default: "e-commerce"

The channel through which the sale will be made. E-commerce ("e-commerce") by default.

Enum: "e-commerce" "post-purchase"
required
object

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": "off-ee589e89-e5a6-4742-9fe8-3d5e119a599f",
  • "country": "de",
  • "type": "protection_product",
  • "created_at": 1645446874158,
  • "expired_at": 1648038918163,
  • "sales_channel": "e-commerce",
  • "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: off-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": "off-ee589e89-e5a6-4742-9fe8-3d5e119a599f",
  • "country": "de",
  • "type": "protection_product",
  • "created_at": 1645446874158,
  • "expired_at": 1648038918163,
  • "sales_channel": "e-commerce",
  • "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 an Order for your customer by providing us with the selected plans and protected product data as line items, as well as the customer data. Only valid (i.e. unexpired) Offer IDs can be used.

SecuritybearerAuth
Request
Request Body schema: application/json

Required data to create an Order

id
string

The identifier of the Order in the merchant's system.

placed_at
integer

The time at which the Order is placed in a merchant's system in milliseconds since the Unix epoch.

sales_channel
string
Default: "e-commerce"

The channel through which the sale was made. E-commerce ("e-commerce") by default.

Enum: "e-commerce" "post-purchase"
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 sample Order placement request

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

A placed Order

{
  • "id": "ord-797f73eb-22e0-4145-b8af-d6fdac71613d",
  • "placed_at": 1645315200000,
  • "sales_channel": "e-commerce",
  • "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: ord-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": "ord-797f73eb-22e0-4145-b8af-d6fdac71613d",
  • "placed_at": 1645315200000,
  • "sales_channel": "e-commerce",
  • "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 the fulfilled items so that we can manage the protection status accordingly. Generally, fulfillment means that the product was shipped.

SecuritybearerAuth
Request
path Parameters
orderId
required
string <uuidv4>

UUIDv4 of the Order to retrieve

Example: ord-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

The fulfillment resource

{
  • "id": "ff-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: ord-797f73eb-22e0-4145-b8af-d6fdac71613d
Request Body schema: application/json

Required data to cancel an Order

reason
string

The reason for the Order cancellation.

cancelled_at
integer

The time at which the line item is cancelled in milliseconds since the Unix epoch

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": "ord-797f73eb-22e0-4145-b8af-d6fdac71613d",
  • "placed_at": 1645315200000,
  • "sales_channel": "e-commerce",
  • "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 line items of an Order by specifying the Order ID and line_items_ids. This can be necessary if a customer revokes one or multiple items from their purchase in your store. Refunds are only possible for fulfilled line items, up to 30 days after fulfillment.

SecuritybearerAuth
Request
path Parameters
orderId
required
string <uuidv4>

UUIDv4 of the Order to retrieve

Example: ord-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

The refund resource

{
  • "id": "re-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

An Order feed response example

{
  • "request_id": "req-f55ca069-1860-4970-82d8-c77388554f9c"
}

Retrieve request status

Retrieve the processing status of the request by specifying the ID. The status contains the current processing status and useful information about the processing.

SecuritybearerAuth
Request
path Parameters
requestId
required
string <uuidv4>

UUIDv4 of the RequestStatus to retrieve

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

A RequestStatus

401

Access token is missing or invalid

404

The requested resource doesn't exist.

get/feeds/order/{requestId}
Response samples
application/json

Example request status

{
  • "processing_status": "in_progress",
  • "failed_orders": [
    ],
  • "statuses": [
    ]
}