Post-delivery

In this section, you will learn more about how to manage your orders after they have been shipped using Klarna's order management API.

Prerequisites

Tip: You can read more in-depth technical content on the API / SDK reference page.


Retrieve a capture

Retrieving all information related to a capture, as example shipping/billing information.

Use case

You need to view what information is related to a shipped item.

 

 

1. Retrieve the capture information from Klarna

Send in the order id and the specific capture id you want to know more about.

$merchantId = getenv('MERCHANT_ID') ?: '0';
$sharedSecret = getenv('SHARED_SECRET') ?: 'sharedSecret';
$orderId = getenv('ORDER_ID') ?: '12345';
$captureId = getenv('CAPTURE_ID') ?: '34567';

$connector = Klarna\Rest\Transport\Connector::create(
    $merchantId,
    $sharedSecret,
    Klarna\Rest\Transport\ConnectorInterface::EU_TEST_BASE_URL
);

$order = new Klarna\Rest\OrderManagement\Order($connector, $orderId);

$capture = $order->fetchCapture($captureId);
Capture capture = client.newCapture(orderId, captureId);
CaptureData data = capture.fetch();
IOrder order = client.NewOrder(orderId);
ICapture capture = client.NewCapture(order.Location, captureId);
CaptureData captureData = capture.Fetch();

2. Handle the response from Klarna

Klarna will respond with one of the following:

Error message - something went wrong

200 - OKThe server has fulfilled the request and the capture information is returned

HTTP/1.1 200 OK
Content-Type: application/json

{
    "capture_id" : "1890011",
    "klarna_reference": "AQ-HWC4-1",
    "captured_amount" : 26600,
    "captured_at": "2014-02-14T07:56:47.624Z",
    "description": "Shipped part of the order",
    "order_lines": [
        {
            "reference": "SKU123456789",
            "type": "physical",
            "name": "Klarna t-shirt",
            "unit_price": 13300,
            "quantity": 2,
            "quantity_unit": "pcs",
            "total_amount": 26600,
            "total_discount_amount": 0,
            "tax_rate": 900,
            "total_tax_amount": 2196
        }
    ],
    "shipping_address": {
        "given_name": "John",
        "family_name": "Smith",
        "title" : "Mr",
        "street_address": "The Street 1",
        "street_address2": "",
        "postal_code": "SL2 5DT",
        "city": "The City",
        "country": "GB",
        "email": "user@example.com",
        "phone": "57-3895734"
    },
    "billing_address": {
        "given_name": "John",
        "family_name": "Smith",
        "title" : "Mr",
        "street_address": "The Street 1",
        "street_address2": "",
        "postal_code": "SL2 5DT",
        "city": "The City",
        "country": "GB",
        "email": "user@example.com",
        "phone": "57-3895734"
    },
    "shipping_info" : [
        {
            "shipping_company" : "DHL",
            "shipping_method" : "Home",
            "tracking_uri" : "tracking-uri",
            "tracking_number" : "1234567890",
            "return_tracking_number" : "E-55-KL",
            "return_shipping_company" : "DHL",
            "return_tracking_uri" : "return-tracking-uri"
        }
    ]
}

Add new shipping information to a capture

Shipping information can be attached to a capture, this will help you and us to keep track of orders sent to the consumer.

Use case

You have made a capture of your order, now when you have sent the order you want to add the shipping details

 

 

1. Add the shipping information and make the API call

Send in the shipping details and add them to a specific capture.

{
    "shipping_info" : [
        {
            "shipping_company" : "DHL",
            "shipping_method" : "Home",
            "tracking_uri" : "tracking-uri",
            "tracking_number" : "1234567890",
            "return_tracking_number" : "E-55-KL",
            "return_shipping_company" : "DHL",
            "return_tracking_uri" : "return-tracking-uri"
        }
    ]
}
$merchantId = '0';
$sharedSecret = 'sharedSecret';
$orderId = '12345';
$captureId = '34567';

$connector = \Klarna\Rest\Transport\Connector::create(
    $merchantId,
    $sharedSecret,
    \Klarna\Rest\Transport\ConnectorInterface::EU_TEST_BASE_URL
);

$order = new \Klarna\Rest\OrderManagement\Order(
    $connector,
    $orderId
);

$capture = $order->fetchCapture($captureId);
$capture->addShippingInfo([
    "shipping_info" => [
        [
            "shipping_company" => "DHL",
            "shipping_method" => "Home",
            "tracking_uri" => "tracking-uri",
            "tracking_number" => "1234567890",
            "return_tracking_number" => "E-55-KL",
            "return_shipping_company" => "DHL",
            "return_tracking_uri" => "return-tracking-uri"
        ]
    ]
]);
Capture capture = client.newCapture(orderId, captureId);
CaptureData data = capture.fetch();

final List<ShippingInfo> info = new ArrayList<ShippingInfo>() {
    {
        add(new ShippingInfo()
                .setShippingCompany("DHL")
                .setShippingMethod("Home")
                .setTrackingUri("tracking-uri")
                .setTrackingNumber("1234567890")
                .setReturnTrackingNumber("E-55-KL")
                .setReturnShippingCompany("DHL")
                .setReturnTrackingUri("return-tracking-uri"));
    }
};

capture.addShippingInfo(new AddShippingInfo().setShippingInfo(info));
IOrder order = client.NewOrder(orderId);
ICapture capture = client.NewCapture(order.Location, captureId);

ShippingInfo shippingInfo = new ShippingInfo
{
    ShippingCompany = "DHL",
    ShippingMethod = "Home",
    TrackingUri = new Uri("tracking-uri"),
    TrackingNumber = "1234567890",
    ReturnTrackingNumber = "E-55-KL",
    ReturnShippingCompany = "DHL",
    ReturnTrackingUri = new Uri("return-tracking-uri")
};

AddShippingInfo addShippingInfo = new AddShippingInfo();
addShippingInfo.ShippingInfo = new List<ShippingInfo>() { shippingInfo };

capture.AddShippingInfo(addShippingInfo);

2. Handle the response from Klarna

Klarna will respond with one of the following:

Error message - something went wrong

204 - No Content - The server has fulfilled the request

 

Note: 

In upcoming versions of the API, this response will be returned instead of 201:

201 - Created - The server has fulfilled the request 


Update the billing address for a capture

Update the billing address for a capture. Shipping address can not be updated.

Use case

The consumer contacts you and wants to send the invoice to another address than the products, e.g buying a gift for someone.

 

 

1. Add the consumers new billing address and make the API call

Fields can be updated independently. To clear a field, set its value to "" (empty string). Mandatory fields can not be cleared.

{
    "billing_address": {
        "given_name": "John",
        "family_name": "Smith",
        "title" : "Mr",
        "street_address": "The Street 1",
        "street_address2": "",
        "postal_code": "SL2 5DT",
        "city": "The City",
        "country": "GB",
        "email": "user@example.com",
        "phone": "57-3895734"
    }
}
Capture capture = client.newCapture(orderId, captureId);

UpdateCustomerDetails data = new UpdateCustomerDetails() {
    {
        setBillingAddress(
            new Address()
                .setStreetAddress("123 Fake St")
                .setCity("New York")
                .setRegion("NY")
                .setPostalCode("12345")
                .setCountry("US")
        );
    }
};

capture.updateCustomerDetails(data);
IOrder order = client.NewOrder(orderId);
ICapture capture = client.NewCapture(order.Location, captureId);

UpdateCustomerDetails updateCustomerDetails = new UpdateCustomerDetails()
{
    BillingAddress = new Address()
    {
        StreetAddress = "123 Fake St",
        City = "New York",
        Region = "NY",
        PostalCode = "12345",
        Country = "US"
    }
};

capture.UpdateCustomerDetails(updateCustomerDetails);

2. Handle the response from Klarna

Klarna will respond with one of the following:

Error message - something went wrong

204 - No Content - The server has fulfilled the request 

 

Note: 

In upcoming versions of the API, this response will be returned instead of 201:

201 - Created - The server has fulfilled the request 


Trigger a new send out of customer communication

Trigger a new send out of customer communication., typically a new invoice, for a capture.

Use case

The consumer did not receive the invoice as expected and you want to send a new invoice.

 

 

1. Make the API call and trigger a new send out

$merchantId = getenv('MERCHANT_ID') ?: '0';
$sharedSecret = getenv('SHARED_SECRET') ?: 'sharedSecret';
$orderId = getenv('ORDER_ID') ?: '12345';
$captureId = getenv('CAPTURE_ID') ?: '34567';

$connector = Klarna\Rest\Transport\Connector::create(
    $merchantId,
    $sharedSecret,
    Klarna\Rest\Transport\ConnectorInterface::EU_TEST_BASE_URL
);

$order = new Klarna\Rest\OrderManagement\Order($connector, $orderId);

$capture = $order->fetchCapture($captureId);
$capture->triggerSendout();
Capture capture = client.newCapture(orderId, captureId);
capture.triggerSendout();
IOrder order = client.NewOrder(orderId);
ICapture capture = client.NewCapture(order.Location, captureId);
capture.TriggerSendOut();

2. Handle the response from Klarna

Klarna will respond with one of the following:

Error message - something went wrong

204 - No Content - The server has fulfilled the request

 

In case of a 404 response, the response body will indicate whether the order or capture was not found

 

Note: 

In upcoming versions of the API, this response will be returned instead of 201:

201 - Created - The server has fulfilled the request 


Refund an amount of a captured order

Refund an amount of a captured order. The refunded amount will be credited to the customer.
The refunded amount must not be higher than 'captured_amount'. The refunded amount can optionally be accompanied by a descriptive text and order lines.

Use case

The consumer sends item(s) back and you need to refund the consumer with the specific amount.

 

 

1. Add new amount and make API call

 

$merchantId = getenv('MERCHANT_ID') ?: '0';
$sharedSecret = getenv('SHARED_SECRET') ?: 'sharedSecret';
$orderId = getenv('ORDER_ID') ?: '12345';

$connector = Klarna\Rest\Transport\Connector::create(
    $merchantId,
    $sharedSecret,
    Klarna\Rest\Transport\ConnectorInterface::EU_TEST_BASE_URL
);

$order = new Klarna\Rest\OrderManagement\Order($connector, $orderId);
$order->refund([
    "refunded_amount" => 3000,
    "description" => "Refunding half the tomatoes",
    "order_lines" => [
        [
            "type" => "physical",
            "reference" => "123050",
            "name" => "Tomatoes",
            "quantity" => 5,
            "quantity_unit" => "kg",
            "unit_price" => 600,
            "tax_rate" => 2500,
            "total_amount" => 3000,
            "total_tax_amount" => 600
        ]
    ]
]);
Order order = client.newOrder(orderId);

final List<OrderLine> lines = new ArrayList<OrderLine>()
{
    {
        add(new OrderLine()
                .setType("physical")
                .setReference("123050")
                .setName("Tomatoes")
                .setQuantity(5L)
                .setQuantityUnit("kg")
                .setUnitPrice(600L)
                .setTaxRate(2500)
                .setTotalAmount(3000L)
                .setTotalTaxAmount(600L));
    }
};

Refund data = new Refund()
{
    {
        setRefundedAmount(3000L);
        setDescription("Refunding half the tomatoes");
        setOrderLines(lines);
    }
};

order.refund(data);
Client client = new Client(connector);
IOrder order = client.NewOrder(orderId);

List<OrderLine> lines = new List<OrderLine>();

lines.Add(new OrderLine()
{
    Type = "physical",
    Reference = "123050",
    Name = "Tomatoes",
    Quantity = 5,
    QuantityUnit = "kg",
    UnitPrice = 600,
    TaxRate = 2500,
    TotalAmount = 3000,
    TotalTaxAmount = 600
});

Refund refund = new Refund()
{
    RefundedAmount = 3000,
    Description = "Refunding half the tomatoes",
    OrderLines = lines
};

order.Refund(refund);

2. Handle the response from Klarna

Klarna will respond with one of the following:

Error message - something went wrong

204 - No Content - The server has fulfilled the request 

 

Note: 

In upcoming versions of the API, this response will be returned instead of 201:

201 - Created - The server has fulfilled the request 


Release the remaining authorization for an order

Signal that there is no intention to perform further captures.

Use case

You and the consumer are happy with the delivery and you have no need to change or update the order.

 

 

1. Get the order id and make the API call

You need the specific order id to release the remaining authorization.

$merchantId = getenv('MERCHANT_ID') ?: '0';
$sharedSecret = getenv('SHARED_SECRET') ?: 'sharedSecret';
$orderId = getenv('ORDER_ID') ?: '12345';

$connector = Klarna\Rest\Transport\Connector::create(
    $merchantId,
    $sharedSecret,
    Klarna\Rest\Transport\ConnectorInterface::EU_TEST_BASE_URL
);

$order = new Klarna\Rest\OrderManagement\Order($connector, $orderId);
$order->releaseRemainingAuthorization();
Order order = client.newOrder(orderId);
order.releaseRemainingAuthorization();
IOrder order = client.NewOrder(orderId);
order.ReleaseRemainingAuthorization();

2. Handle the response from Klarna

Klarna will respond with one of the following:

Error message - something went wrong

204 - No Content - The server has fulfilled the request 

 

Note:

In upcoming versions of the API, this response will be returned instead of 201:

201 - Created - The server has fulfilled the request