Cart and checkout

The CartSDK is the easiest way to get started. Cart data always comes from the server; the SDK does not pretend a local total or stock check is authoritative.

Watch for a cart sync#

const stopListening = sdk.on('cart:synced', (cart) => {
  console.log(cart.id, cart.items);
});

// Call stopListening() when the listener is no longer needed.

The on method returns an unsubscribe function. You may also call sdk.off(event, listener).

Cart methods#

const created = await sdk.createCart({
  userId: 'user-id',
  email: 'buyer@example.com',
  currencyCode: 'ZAR',
});

const cart = await sdk.getCart({ cartId: created.id, currencyCode: 'ZAR' });

const updated = await sdk.addItemToCart(created.id, {
  productId: 'product-id',
  quantity: 2,
  variantId: 'variant-id',
});

await sdk.updateItemQuantity(created.id, updated.items[0].id, 3);
await sdk.removeItem(created.id, updated.items[0].id);
await sdk.applyCoupon(created.id, 'WELCOME');
await sdk.removeCoupon(created.id);

The backend re-checks product availability and pricing. Treat price as display/input data only; it is never payment authority.

Checkout#

const order = await sdk.checkout({
  cartId: created.id,
  userId: 'user-id',
  shippingAddress: { address: '1 Example Street', city: 'Cape Town' },
  paymentMethod: 'wallet',
  currencyCode: 'ZAR',
});

The SDK generates a cryptographically random idempotency key and keeps it for an unchanged retry in the same client instance. You can supply your own idempotencyKey when you need to persist retry identity across application restarts. Reuse that key only for the same checkout payload.

The backend currently accepts wallet checkout. It validates the authenticated actor, cart ownership, current totals, payment eligibility, and duplicate submissions. A second concurrent checkout for the same cart in one SDK instance is rejected locally; the backend lock protects requests across processes and clients too.

Checkout and request events include checkout:started, checkout:completed, checkout:failed, request:started, request:completed, and request:failed.