Skip to content
Order Management
/
/
Release an authorization

Order Management API (1.0.0)

Download OpenAPI description
order-management.json
order-management.yaml
Languages
Servers
Default Server URL
https://api.kustom.co

Orders

Operations

Add shipping information

Request

Add shipping info to an order. Read more on Adding shipping info

Path
order_idstring(uuid)required

Order id

Headers
Klarna-Idempotency-Keystring

This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.

Bodyapplication/jsonrequired
shipping_infoArray of objects(ShippingInfoDto)[ 1 .. 500 ] itemsrequired

New shipping info. Maximum: 500 items.

curl -i -X POST \
  'https://api.kustom.co/ordermanagement/v1/orders/{order_id}/shipping-info' \
  -H 'Content-Type: application/json' \
  -H 'Klarna-Idempotency-Key: string' \
  -d '{
    "shipping_info": [
      {
        "return_shipping_company": "DHL SE",
        "return_tracking_number": 93456415674545680000,
        "return_tracking_uri": "http://shipping.example/findmypackage?93456415674545679888",
        "shipping_company": "DHL SE",
        "shipping_method": "Home",
        "tracking_number": 63456415674545680000,
        "tracking_uri": "http://shipping.example/findmypackage?63456415674545679874"
      }
    ]
  }'

Responses

Shipping information was appended.

Response
No content

Release an authorization

Request

Release remaining authorization. Read more on Releasing remaining authorization

Path
order_idstring(uuid)required

Order id

Headers
Klarna-Idempotency-Keystring

This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.

curl -i -X POST \
  'https://api.kustom.co/ordermanagement/v1/orders/{order_id}/release-remaining-authorization' \
  -H 'Klarna-Idempotency-Key: string'

Responses

Remaining authorization was released.

Bodyapplication/json
string
Response
application/json
"string"

Extend the authorization time

Request

Extend authorization time. Read more on Extending order authorization time

Path
order_idstring(uuid)required

Order id

Headers
Klarna-Idempotency-Keystring

This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.

curl -i -X POST \
  'https://api.kustom.co/ordermanagement/v1/orders/{order_id}/extend-authorization-time' \
  -H 'Klarna-Idempotency-Key: string'

Responses

Authorization time was extended.

Response
No content

Cancel an order

Request

Cancel order. Read more on Cancelling an order

Path
order_idstring(uuid)required

Order id

Headers
Klarna-Idempotency-Keystring

This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.

curl -i -X POST \
  'https://api.kustom.co/ordermanagement/v1/orders/{order_id}/cancel' \
  -H 'Klarna-Idempotency-Key: string'

Responses

Order was cancelled.

Response
No content

Acknowledge a Kustom checkout order

Request

Acknowledge order. Read more on Acknowledging orders

Path
order_idstring(uuid)required

Order id

Headers
Klarna-Idempotency-Keystring

This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.

curl -i -X POST \
  'https://api.kustom.co/ordermanagement/v1/orders/{order_id}/acknowledge' \
  -H 'Klarna-Idempotency-Key: string'

Responses

Order was acknowledged.

Response
No content

Update merchant references

Request

Update merchant references. Read more on Updating merchant references

Path
order_idstring(uuid)required

Order id

Headers
Klarna-Idempotency-Keystring

This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.

Body
required
merchant_reference1string[ 0 .. 255 ] characters

New merchant reference 1. Old reference will be overwritten if this field is present.

merchant_reference2string[ 0 .. 255 ] characters

New merchant reference 2. Old reference will be overwritten if this field is present.

curl -i -X PATCH \
  'https://api.kustom.co/ordermanagement/v1/orders/{order_id}/merchant-references' \
  -H 'Content-Type: application/json' \
  -H 'Klarna-Idempotency-Key: string' \
  -d '{
    "merchant_reference1": "string",
    "merchant_reference2": "string"
  }'

Responses

Order merchant references were updated.

Response
No content

Update customer addresses

Request

Update shipping address. Read more on Updating customer addresses

Path
order_idstring(uuid)required

Order id

Headers
Klarna-Idempotency-Keystring

This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.

Bodyapplication/jsonrequired
shipping_addressobject(AddressDto)

Shipping address for the capture.

curl -i -X PATCH \
  'https://api.kustom.co/ordermanagement/v1/orders/{order_id}/customer-details' \
  -H 'Content-Type: application/json' \
  -H 'Klarna-Idempotency-Key: string' \
  -d '{
    "shipping_address": {
      "attention": "Anders Exempelsson",
      "city": "Vetlanda",
      "country": "se",
      "email": "john.testsson@kustom.co",
      "family_name": "Testsson",
      "given_name": "John",
      "organization_name": "Kustom",
      "phone": "1-555-555-5555",
      "postal_code": 12345,
      "region": "TN",
      "street_address": "Testgatan 10",
      "street_address2": 1,
      "title": "Herr"
    }
  }'

Responses

Order consumer details were updated.

Bodyapplication/json
string
Response
application/json
"string"

Update the order amount and order lines

Request

Set new order amount and order lines. Read more on Updating orders

Path
order_idstring(uuid)required

Order id

Headers
Klarna-Idempotency-Keystring

This header will guarantee the idempotency of the operation. The key should be unique and is recommended to be a UUID version 4. Retries of requests are safe to be applied in case of errors such as network errors, socket errors and timeouts. Input values of the operation are disregarded when evaluating the idempotency of the operation, only the key matters.

Bodyapplication/jsonrequired
descriptionstring[ 0 .. 255 ] characters

Description of the change.

Example: "Added charger"
order_amountinteger(int64)[ 0 .. 200000000 ]required

The new total order amount. Minor units.

order_linesArray of objects(OrderLineDto)[ 0 .. 1000 ] itemsrequired

New set of order lines for the order.

curl -i -X PATCH \
  'https://api.kustom.co/ordermanagement/v1/orders/{order_id}/authorization' \
  -H 'Content-Type: application/json' \
  -H 'Klarna-Idempotency-Key: string' \
  -d '{
    "description": "Added charger",
    "order_amount": 200000000,
    "order_lines": [
      {
        "image_url": "https://yourstore.example/product/headphones.png",
        "merchant_data": "Some metadata",
        "name": "string",
        "product_identifiers": {
          "brand": "Intel",
          "category_path": "Electronics Store > Computers & Tablets > Desktops",
          "color": "Denim blue",
          "global_trade_item_number": 735858293167,
          "manufacturer_part_number": "BOXNUC5CPYH",
          "size": 4
        },
        "product_url": "https://yourstore.example/product/headphones",
        "quantity": 1,
        "quantity_unit": "pcs.",
        "reference": 75001,
        "tax_rate": 0,
        "total_amount": 200000000,
        "total_discount_amount": 0,
        "total_tax_amount": 200000000,
        "type": "physical",
        "unit_price": 200000000
      }
    ]
  }'

Responses

Authorization was updated.

Bodyapplication/json
string
Response
application/json
"string"

Get order details

Request

An order that has the given order id. Read more on Retrieving order details

Path
order_idstring(uuid)required

Order id

Headers
Klarna-Integratorstring
curl -i -X GET \
  'https://api.kustom.co/ordermanagement/v1/orders/{order_id}' \
  -H 'Klarna-Integrator: string'

Responses

Order found

Bodyapplication/json
billing_addressobject(AddressDto)

Shipping address for the capture.

captured_amountinteger(int64)

The total amount of all captures. In minor units.

Example: 0
capturesArray of objects(CaptureDto)

List of captures for this order.

created_atstring(date-time)

The time for the purchase. Formatted according to ISO 8601.

Example: "2025-11-29T10:25:40Z"
customerobject(CustomerDto)

Information about the customer placing the order.

expires_atstring(date-time)

Order expiration time. The order can only be captured until this time. Formatted according to ISO 8601.

Example: "2025-12-04T10:26:06Z"
fraud_statusstring

Fraud status for the order. Either ACCEPTED, PENDING or REJECTED.

Example: "ACCEPTED"
initial_payment_methodobject(InitialPaymentMethodDto)

Initial payment method for this order

klarna_referencestring

A Klarna generated reference that is shorter than the Klarna Order Id and is used as a customer friendly reference. It is most often used as a reference when Klarna is communicating with the customer with regard to payment statuses.

Example: "K4MADNY"
localestring

The customers locale. Specified according to RFC 1766.

Example: "en-us"
merchant_datastring

Text field for storing data about the order. Set at order creation.

Example: "Order metadata"
merchant_reference1string

The order number that the merchant should assign to the order. This is how a customer would reference the purchase they made. If supplied, it is labeled as the Order Number within post purchase communications as well as the payment method related apps.

Example: 10001
merchant_reference2string

Can be used to store your internal reference to the order. This is generally an internal reference number that merchants use as alternate identifier that matches their internal ERP or Order Management system.

Example: 501
order_amountinteger(int64)

The order amount in minor units. That is the smallest currency unit available such as cent or penny.

order_idstring

The unique order ID. Cannot be longer than 255 characters.

Example: "f3392f8b-6116-4073-ab96-e330819e2c07"
order_linesArray of objects(OrderLineDto)

An array of order_line objects. Each line represents one item in the cart.

original_order_amountinteger(int64)

The original order amount. In minor units.

purchase_countrystring

The purchase country. Formatted according to ISO 3166-1 alpha-2.

Example: "us"
purchase_currencystring

The currency for this order. Specified in ISO 4217 format.

Example: "usd"
refunded_amountinteger(int64)

The total amount of refunded for this order. In minor units.

Example: 0
refundsArray of objects(RefundDto)

List of refunds for this order.

remaining_authorized_amountinteger(int64)

The remaining authorized amount for this order. To increase the remaining_authorized_amount the order_amount needs to be increased.

Example: 0
selected_shipping_optionobject(SelectedShippingOptionDto)

The shipping option selected by the user.

shipping_addressobject(AddressDto)

Shipping address for the capture.

shipping_infoArray of objects(ShippingInfoDto)

Shipping information for this order.

statusstring

The order status.

Enum"AUTHORIZED""PART_CAPTURED""CAPTURED""CANCELLED""EXPIRED""CLOSED"
Example: "AUTHORIZED"
Response
application/json
{
  "billing_address": {
    "attention": "Anders Exempelsson",
    "city": "Vetlanda",
    "country": "se",
    "email": "john.testsson@kustom.co",
    "family_name": "Testsson",
    "given_name": "John",
    "organization_name": "Kustom",
    "phone": "1-555-555-5555",
    "postal_code": 12345,
    "region": "TN",
    "street_address": "Testgatan 10",
    "street_address2": 1,
    "title": "Herr"
  },
  "captured_amount": 0,
  "captures": [
    { … }
  ],
  "created_at": "2025-11-29T10:25:40Z",
  "customer": {
    "date_of_birth": "Sun Sep 06 02:00:00 CEST 1981",
    "national_identification_number": "string",
    "vat_id": "string",
    "type": "person",
    "organization_entity_type": "LIMITED_COMPANY",
    "organization_registration_id": "string"
  },
  "expires_at": "2025-12-04T10:26:06Z",
  "fraud_status": "ACCEPTED",
  "initial_payment_method": {
    "description": "Slice it (Fixed Payments)",
    "number_of_installments": 3,
    "type": "FIXED_AMOUNT"
  },
  "klarna_reference": "K4MADNY",
  "locale": "en-us",
  "merchant_data": "Order metadata",
  "merchant_reference1": 10001,
  "merchant_reference2": 501,
  "order_amount": 0,
  "order_id": "f3392f8b-6116-4073-ab96-e330819e2c07",
  "order_lines": [
    { … }
  ],
  "original_order_amount": 0,
  "purchase_country": "us",
  "purchase_currency": "usd",
  "refunded_amount": 0,
  "refunds": [
    { … }
  ],
  "remaining_authorized_amount": 0,
  "selected_shipping_option": {
    "carrier": "string",
    "carrier_product": { … },
    "class": "string",
    "id": "string",
    "location": { … },
    "method": "string",
    "name": "string",
    "price": 0,
    "selected_addons": [ … ],
    "tax_amount": 0,
    "tax_rate": 0,
    "timeslot": { … },
    "tms_reference": "string",
    "type": "string"
  },
  "shipping_address": {
    "attention": "Anders Exempelsson",
    "city": "Vetlanda",
    "country": "se",
    "email": "john.testsson@kustom.co",
    "family_name": "Testsson",
    "given_name": "John",
    "organization_name": "Kustom",
    "phone": "1-555-555-5555",
    "postal_code": 12345,
    "region": "TN",
    "street_address": "Testgatan 10",
    "street_address2": 1,
    "title": "Herr"
  },
  "shipping_info": [
    { … }
  ],
  "status": "AUTHORIZED"
}

Refunds

Operations

Captures

Operations