Powered by Redocly

Hakuna API (v1.3)

Download OpenAPI specification:Download

This document refers to v1.3 of the API, live after June 2023. The Hakuna API v1.3 is built on top of the previous version v1.2 and significantly simplifies your interactions with the Hakuna Platform. So far, this version is only accessible to selected patners: This reference is for Globetrotter / Fenix Outdoor.

Hakuna's REST APIs use standard HTTP verbs, authentication and response codes as well as JSON-encoded requests and responses.

Don't hesitate to contact us with any questions or feedback. You can email Hakuna directly at support@hellohakuna.com.

Getting Started

This version allows you to create Protection Items in your (ERP) system beforehand, and without needing to manage any Hakuna related data. Once you sell a protection item, you can use the Order API to place and manage it, again, without managing any Hakuna related data.

Check out

Authentication

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

Authorization: Bearer <API_KEY>

Orders

Endpoints to place and manage Orders for Protection from your customers.

Place Order

You can create an Order for your customer by providing us with the selected protection and protected product data as line items, as well as the customer data.

SecuritybearerAuth
Request
Request Body schema: application/json
required

Required data to create an Order

order_id
required
string

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

placed_at
required
integer

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

sales_channel
required
string

The channel through which the sale was made.

Enum: "e-commerce" "offline"
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

{
  • "order_id": "order-364587",
  • "placed_at": 1645315200000,
  • "sales_channel": "e-commerce",
  • "customer": {
    },
  • "customer_billing_address": {
    },
  • "line_items": [
    ]
}
Response samples
application/json

A placed Order

{
  • "order_id": "order-364587",
  • "placed_at": 1645315200000,
  • "sales_channel": "e-commerce",
  • "customer": {
    },
  • "customer_billing_address": {
    },
  • "line_items": [
    ],
  • "status": "placed",
  • "cancelled_at": null,
  • "cancel_reason": null,
  • "refunds": [ ],
  • "fulfillments": [ ],
  • "cancellations": [ ]
}

Retrieve Order

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

SecuritybearerAuth
Request
path Parameters
orderId
required
string

The identifier of the Order in the merchant's system

Example: order-364587
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

{
  • "order_id": "order-364587",
  • "placed_at": 1645315200000,
  • "sales_channel": "e-commerce",
  • "customer": {
    },
  • "customer_billing_address": {
    },
  • "line_items": [
    ],
  • "status": "placed",
  • "cancelled_at": null,
  • "cancel_reason": null,
  • "refunds": [ ],
  • "fulfillments": [ ],
  • "cancellations": [ ]
}

Create line item level cancellation for Order

Create a cancellation for a specific Order by specifying the Order ID and cancelled items so that we can manage the protection status accordingly.

SecuritybearerAuth
Request
path Parameters
orderId
required
string

The identifier of the Order in the merchant's system

Example: order-364587
Request Body schema: application/json
required

Required data to create a cancellation

required
Array of objects

A list of cancelled line items.

Responses
201

Created cancellation

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}/cancellations
Request samples
application/json

A request to create a cancellation

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

The cancellation resource

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

Create fulfillment for Order

Create a fulfillment for a specific Order by specifying the Order ID and 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

The identifier of the Order in the merchant's system

Example: order-364587
Request Body schema: application/json
required

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

The identifier of the Order in the merchant's system

Example: order-364587
Request Body schema: application/json
required

Required data to cancel an Order

cancel_reason
string

The reason for the Order cancellation.

cancelled_at
required
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

{
  • "cancel_reason": "customer",
  • "cancelled_at": 1645453287866
}
Response samples
application/json

A cancelled Order

{
  • "order_id": "order-364587",
  • "placed_at": 1645315200000,
  • "sales_channel": "e-commerce",
  • "customer": {
    },
  • "customer_billing_address": {
    },
  • "line_items": [
    ],
  • "status": "cancelled",
  • "cancelled_at": 1645453287866,
  • "cancel_reason": "customer",
  • "refunds": [ ],
  • "fulfillments": [ ],
  • "cancellations": [ ]
}

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

The identifier of the Order in the merchant's system

Example: order-364587
Request Body schema: application/json
required

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": [
    ]
}