Skip to content
/Captures

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

Refunds

Operations

Captures

Operations

List all order captures

Request

List all order captures

Path
order_idstring(uuid)required

Order id

curl -i -X GET \
  'https://api.kustom.co/ordermanagement/v1/orders/{order_id}/captures'

Responses

Captures found.

Bodyapplication/jsonArray [
billing_addressobject(AddressDto)

Shipping address for the capture.

capture_idstring

The capture id. Generated when the capture is created.

Example: "4ba29b50-be7b-44f5-a492-113e6a865e22"
captured_amountinteger(int64)>= 1

The captured amount in minor units.

captured_atstring(date-time)

The time of the capture. Specified in ISO 8601.

Example: "2025-11-19T01:51:17Z"
descriptionstring

Description of the capture shown to the customer.

Example: "Order has been shipped"
klarna_referencestring

Customer friendly reference id, used as a reference when communicating with the customer.

Example: "K4MADNY-1"
order_linesArray of objects(OrderLineDto)

List of order lines for the capture shown to the customer.

referencestring[ 0 .. 255 ] characters

Internal reference to the capture which will be included in the settlement files. Max length is 255 characters.

refunded_amountinteger(int64)

Refunded amount for this capture in minor units.

Example: 0
shipping_addressobject(AddressDto)

Shipping address for the capture.

shipping_infoArray of objects(ShippingInfoDto)

Shipping information for this capture.

]
Response
application/json
[
  {
    "billing_address": { … },
    "capture_id": "4ba29b50-be7b-44f5-a492-113e6a865e22",
    "captured_amount": 1,
    "captured_at": "2025-11-19T01:51:17Z",
    "description": "Order has been shipped",
    "klarna_reference": "K4MADNY-1",
    "order_lines": [ … ],
    "reference": "string",
    "refunded_amount": 0,
    "shipping_address": { … },
    "shipping_info": [ … ]
  }
]

Capture an order

Request

Create capture. Read more on Capturing 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.

Bodyapplication/jsonrequired
captured_amountinteger(int64)[ 0 .. 200000000 ]required

The captured amount in minor units.

descriptionstring[ 0 .. 255 ] characters

Description of the capture shown to the customer. Maximum 255 characters.

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

Order lines for this capture. Maximum 1000 items.

referencestring[ 0 .. 255 ] characters

Internal reference to the capture. This will be included in the settlement files. Max length is 255 characters.

shipping_delayinteger(int64)>= 0

Delay before the order will be shipped. Use for improving the customer experience regarding payments. This field is currently not returned when reading the order. Minimum: 0. Please note: to be able to submit values larger than 0, this has to be enabled in your merchant account. Please contact Kustom for further information.

shipping_infoArray of objects(ShippingInfoDto)[ 0 .. 500 ] items

Shipping information for this capture. Maximum 500 items.

curl -i -X POST \
  'https://api.kustom.co/ordermanagement/v1/orders/{order_id}/captures' \
  -H 'Content-Type: application/json' \
  -H 'Klarna-Idempotency-Key: string' \
  -d '{
    "captured_amount": 200000000,
    "description": "string",
    "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
      }
    ],
    "reference": "string",
    "shipping_delay": 0,
    "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

Capture created

Response
No content

Add shipping information

Request

Add shipping info to a capture. Read more on Adding shipping info

Path
order_idstring(uuid)required

Order id

capture_idstringrequired

Capture 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}/captures/{capture_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

Get capture details

Request

Retrieve the details of a capture. To learn more, refer to the Retrieving capture details article.

Path
order_idstring(uuid)required

Order id

capture_idstringrequired

Capture id

curl -i -X GET \
  'https://api.kustom.co/ordermanagement/v1/orders/{order_id}/captures/{capture_id}'

Responses

Capture found.

Bodyapplication/json
billing_addressobject(AddressDto)

Shipping address for the capture.

capture_idstring

The capture id. Generated when the capture is created.

Example: "4ba29b50-be7b-44f5-a492-113e6a865e22"
captured_amountinteger(int64)>= 1

The captured amount in minor units.

captured_atstring(date-time)

The time of the capture. Specified in ISO 8601.

Example: "2025-11-19T01:51:17Z"
descriptionstring

Description of the capture shown to the customer.

Example: "Order has been shipped"
klarna_referencestring

Customer friendly reference id, used as a reference when communicating with the customer.

Example: "K4MADNY-1"
order_linesArray of objects(OrderLineDto)

List of order lines for the capture shown to the customer.

referencestring[ 0 .. 255 ] characters

Internal reference to the capture which will be included in the settlement files. Max length is 255 characters.

refunded_amountinteger(int64)

Refunded amount for this capture in minor units.

Example: 0
shipping_addressobject(AddressDto)

Shipping address for the capture.

shipping_infoArray of objects(ShippingInfoDto)

Shipping information for this capture.

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"
  },
  "capture_id": "4ba29b50-be7b-44f5-a492-113e6a865e22",
  "captured_amount": 1,
  "captured_at": "2025-11-19T01:51:17Z",
  "description": "Order has been shipped",
  "klarna_reference": "K4MADNY-1",
  "order_lines": [
    { … }
  ],
  "reference": "string",
  "refunded_amount": 0,
  "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": [
    { … }
  ]
}