Checkout & Shipping

Checkout

Access via client.checkout.

init(params)

Initialize a payment session (Klarna, Stripe, etc.) from a completed cart.

const session = await client.checkout.init({
  cartId: cart.id,
  provider: 'klarna', // or 'stripe'
  successUrl: 'https://mystore.com/checkout/confirmation/{reference}',
  cancelUrl: 'https://mystore.com/cart',
})
// → CheckoutResponse { sessionId, snippet?, redirectUrl? }

Embed Klarna's snippet HTML or redirect to Stripe's redirectUrl.

getConfirmation(reference)

Load the order confirmation after the customer returns from the payment provider.

const confirmation = await client.checkout.getConfirmation(orderReference)
// → ConfirmationResponse { order, customer, lineItems, ... }

Shipping

Access via client.shipping.

getOptions(params)

Fetch available shipping options for a cart's address and items.

const options = await client.shipping.getOptions({
  cartId: cart.id,
  countryCode: 'SE',
  postalCode: '11120',
})
// → ShippingOption[]

interface ShippingOption {
  id: string
  name: string
  carrier: string
  priceIncVat: number
  estimatedDelivery?: string
}

Select an option with client.cart.setShipping().

Split shipments

When something in the cart is out of stock, the store can let the customer choose between one shipment when everything is available, or what is in stock now and the rest later. Each shipment then gets its own delivery method and its own shipping charge, so one part can be home delivered and another picked up in store. The store turns this on under Settings → Order routing. When it is off, getShipmentOptions returns enabled: false and nothing changes.

cart.getShipmentOptions(cartId)

What the customer can choose between, against current stock.

const options = await client.cart.getShipmentOptions(cart.id)
if (options.enabled && options.canSplit) {
  // options.complete.shipments: one shipment
  // options.split.shipments: e.g. [{ items, estimate: { date: '2026-10-02' } },
  //                                 { isBackorder: true, items, estimate: { date: '2026-10-20' } }]
}

Each shipment carries its items, an estimated date and pickupAvailable. Pickup is only offered where every item in the shipment is on the shelf now, never on a backorder shipment. The dates are estimates; the delivery promise is set on the order when it is created. A date with source: "stock" is the next working day and does not include transport time.

Free shipping is judged on the whole order's value for every shipment, so splitting never costs the customer free shipping. options.charge says what the backorder shipment costs: fixed (amountIncVat, even when the order ships free), same-as-order (the shipping method's price, free when the order ships free) or free. The first shipment always costs what its shipping method costs. The options from getShipmentShippingOptions for a backorder shipment already carry that price.

cart.setShipmentPreference(cartId, preference)

Record the choice. "split" splits the cart into cart.shipmentOrders, one per shipment. "complete" or null goes back to one shipment. Changing the cart's contents afterwards (a new line, another quantity) resets the choice, so call getShipmentOptions again.

cart = await client.cart.setShipmentPreference(cart.id, 'split')

cart.getShipmentShippingOptions(cartId, shipmentOrderId, postalCode) and cart.setShipmentShipping(cartId, shipmentOrderId, params)

Shipping is chosen per shipment, priced on that shipment's items. In a split cart, cart.setShipping answers 409 CART_IS_SPLIT.

for (const shipment of cart.shipmentOrders) {
  const { options, pickupWarehouse } = await client.cart.getShipmentShippingOptions(cart.id, shipment._id, '11120')
  cart = await client.cart.setShipmentShipping(cart.id, shipment._id, { shippingOptionId: options[0].id, postalCode: '11120' })
}
// cart.shippingLines: one line per shipment, each with its shipmentOrderId

A pickup option is only accepted at the shipment's own warehouse (pickupWarehouse).

At checkout

checkout.init answers 400 SHIPPING_METHOD_REQUIRED with details.shipmentOrderIds when a shipment has no shipping method. If stock changed so that the split no longer holds, it answers 409 SHIPMENT_PLAN_CHANGED with the new options in details.options: show them to the customer again.

With payment on shipment, each shipment is charged when it ships.