Checkout

Pay for the cart.

subbly.checkout.purchase(cartId, payload?, params?)

Charges the cart and creates the subscription, the invoice and the orders. It needs a signed-in customer, and the cart must be ready: a customer attached, a delivery method set and a payment method chosen.

The SDK does not touch subbly.cart afterwards. The cart is complete on the server, so drop your local copy and create a new one for the next order.

A card that needs 3-D Secure rejects with code: 'payment_requires_action' and a paymentIntentId. Take the customer through the verification with subbly.paymentIntents.getPaymentIntent and subbly.paymentIntents.confirm, then call purchase again with the same paymentIntentId. The call can also reject with out_of_stock or bad_request.

Method parameters

cartIdRequiredstring

UUID of the cart to charge, usually subbly.cart.id.

payloadoptionalCheckoutPurchasePayload

How to pay. Leave it out to charge the payment method already on the cart.

paramsoptionalPurchaseRequestParams

Relations to include in the response.

ReturnsPromise<CheckoutPurchaseResponse>

What the purchase created.


Purchase the cart
const { invoice, subscription, orders } = await subbly.checkout.purchase(
  subbly.cart.id,
)


Handle 3-D Secure
try {
  await subbly.checkout.purchase(subbly.cart.id)
} catch (error) {
  if (error.code !== 'payment_requires_action') throw error

  const intent = await subbly.paymentIntents.getPaymentIntent(
    error.paymentIntentId,
  )

  // Verify `intent.token` with the payment gateway, then:
  await subbly.paymentIntents.confirm(intent.id, externalPaymentId)
  await subbly.checkout.purchase(subbly.cart.id, {
    paymentIntentId: intent.id,
  })
}

Last modified on September 15, 2026