@brinkcommerce/shopper-sdk

TypeScript SDK for the Brink Commerce Shopper API. Covers all endpoints across the core API and all 18 provider integrations.

Installation

npm install @brinkcommerce/shopper-sdk

Setup

import { ShopperClient } from '@brinkcommerce/shopper-sdk'

const shopper = new ShopperClient({
  baseUrl: 'https://shopper.eu-west-1.acme.brinkcommerce.io',
  apiKey: 'your-api-key', // optional, for BFF/server-side usage
})

The baseUrl is your customer-specific host. All provider endpoints are derived from it automatically.

SSR / session hydration

If you already have a JWT from a previous session (e.g. stored in a cookie), pass it at construction time:

const shopper = new ShopperClient({
  baseUrl: 'https://shopper.eu-west-1.acme.brinkcommerce.io',
  sessionToken: existingToken,
})

Token management

The SDK manages two tokens automatically — you never need to handle them manually.

Session token — issued by sessions.start() and refreshed on every mutating session call. Used by all session, cart, and loyalty endpoints.

Checkout token — issued by checkouts.start() and reissued every time it is called. Used exclusively by all payment and shipping provider endpoints (Adyen, Avarda, Ingrid, KCO, Ledyer, NShift, Qliro, SCO, Walley, Zaver, Custom Payment, Custom Shipping). Both tokens are stored internally and injected into requests automatically.

Error handling

All methods throw ShopperError on non-2xx responses.

import { ShopperClient, ShopperError } from '@brinkcommerce/shopper-sdk'

try {
  await shopper.sessions.addItem({ productVariantId: 'sku-1', quantity: 1 })
} catch (e) {
  if (e instanceof ShopperError) {
    console.error(e.statusCode) // e.g. 404
    console.error(e.body)       // parsed response body
  }
}

Core API

Sessions

// Start a session — JWT is stored automatically
const session = await shopper.sessions.start({
  storeGroupId: 'store-group-1',
  countryCode: 'SE',
  languageCode: 'sv-SE',
})

// Get current session
const session = await shopper.sessions.get()

// Add an item
const session = await shopper.sessions.addItem({
  productVariantId: 'sku-hoodie-l',
  quantity: 2,
})

// Update item quantity
const session = await shopper.sessions.updateItem(itemId, { quantity: 3 })

// Remove item
const session = await shopper.sessions.removeItem(itemId)

// Add / remove discount code
const session = await shopper.sessions.addDiscountCode({ code: 'SUMMER20' })
const session = await shopper.sessions.removeDiscountCode('SUMMER20')

// Set item options (e.g. gift wrap)
const session = await shopper.sessions.setItemOptions(itemId, {
  options: { giftWrap: 'true' },
})
const session = await shopper.sessions.removeItemOptions(itemId)

// Single option
const session = await shopper.sessions.setItemOption(itemId, 'giftWrap', { value: 'true' })
const session = await shopper.sessions.removeItemOption(itemId, 'giftWrap')

// Update session attributes
await shopper.sessions.patchAttributes({ company: { name: 'Acme AB', vatId: 'SE556...' } })

// Migrate a session (e.g. post-login)
const session = await shopper.sessions.migrate({
  storeGroupId: 'store-group-1',
  countryCode: 'SE',
  languageCode: 'sv-SE',
})

Products

No JWT required for product endpoints.

const prices = await shopper.products.getPrices({
  productParentId: 'parent-1',
  storeGroupId: 'store-group-1',
  countryCode: 'SE',
})

const pricesWithDiscounts = await shopper.products.getPricesWithDiscounts({
  productParentId: 'parent-1',
  storeGroupId: 'store-group-1',
  countryCode: 'SE',
})

const stock = await shopper.products.getStock({
  productParentId: 'parent-1',
  storeGroupId: 'store-group-1',
  countryCode: 'SE',
})

Checkouts

// Start a checkout — issues a new checkout token automatically
// All subsequent payment and shipping provider calls use this token
const { checkout } = await shopper.checkouts.start({
  paymentProvider: { name: 'adyen', id: 'adyen-provider-id' },
  shippingProvider: { name: 'ingrid', id: 'ingrid-provider-id' },
})

// Get current checkout — requires a checkout token (call start() first)
const { checkout } = await shopper.checkouts.get()

Detecting a stale checkout

When the session changes after a checkout has been started (items added or removed, discount codes applied, provider state changes, attribute updates, etc.), the checkout must be started again. Use isCheckoutStale to detect this:

import { ShopperClient, isCheckoutStale } from '@brinkcommerce/shopper-sdk'

let { checkout } = await shopper.checkouts.start({ paymentProvider: { name: 'adyen', id: '...' } })

// Later — session is modified
const session = await shopper.sessions.addItem({ productVariantId: 'sku-1', quantity: 1 })

if (isCheckoutStale(session, checkout)) {
  // A new checkout token is issued and stored automatically
  ;({ checkout } = await shopper.checkouts.start({ paymentProvider: { name: 'adyen', id: '...' } }))
}

isCheckoutStale compares session.version against checkout.sessionVersion. If the session has been updated since the checkout was started (cart changes, provider state changes, attribute updates, etc.), it returns true.

Reusing an existing checkout

When navigating to the checkout page, reuse the existing checkout if it is still valid rather than always starting a new one:

const canReuse = existingCheckout && session && !isCheckoutStale(session, existingCheckout)

const { checkout } = canReuse
  ? await shopper.checkouts.get()
  : await shopper.checkouts.start({ paymentProvider: { name: '...', id: '...' }, shippingProvider: { name: '...', id: '...' } })

Detecting a payment provider change

isCheckoutStale only checks whether the session has changed. If the user selects a different payment provider, the checkout must also be started again even when the session is unchanged. Use isCheckoutForPaymentProvider to detect this:

import { ShopperClient, isCheckoutStale, isCheckoutForPaymentProvider } from '@brinkcommerce/shopper-sdk'

const selectedProvider = 'klarna' // the provider the user just chose

const canReuse =
  existingCheckout &&
  session &&
  !isCheckoutStale(session, existingCheckout) &&
  isCheckoutForPaymentProvider(existingCheckout, selectedProvider)

const { checkout } = canReuse
  ? await shopper.checkouts.get()
  : await shopper.checkouts.start({ paymentProvider: { name: selectedProvider, id: '...' } })

isCheckoutForPaymentProvider checks checkout.capabilities.paymentProvider.name against the given provider name.

Payment providers

Adyen

const session = await shopper.adyen.createSession({
  adyen: {
    shopperName: { firstName: 'Jane', lastName: 'Doe' },
    telephoneNumber: '+46701234567',
    deliveryAddress: { street: 'Kungsgatan 1', city: 'Stockholm', ... },
  },
})

const zeroPayment = await shopper.adyen.createZeroPayment({ ... })
const confirmation = await shopper.adyen.getConfirmation()

Avarda

const payment = await shopper.avarda.createPayment({ ... })
await shopper.avarda.syncPayment()
const confirmation = await shopper.avarda.getConfirmation()

Custom Payment

const session = await shopper.customPayment.createSession({ ... })
await shopper.customPayment.syncSession()
const confirmation = await shopper.customPayment.getConfirmation()

Klarna Checkout (KCO)

const order = await shopper.kco.createOrder({ ... })
const order = await shopper.kco.getOrder()
await shopper.kco.syncOrder({})
await shopper.kco.syncOrder({ klarna: { shipping_address: { postal_code: '11120' } } })

Ledyer

const session = await shopper.ledyer.createSession({ ... })
await shopper.ledyer.syncSession()
const confirmation = await shopper.ledyer.getConfirmation()

Qliro

Standard checkout:

const order = await shopper.qliro.createOrder({ ... })
const order = await shopper.qliro.getOrder()
await shopper.qliro.syncOrder()

Upsell flow — the upsell token is stored automatically after startUpsell():

const upsell = await shopper.qliro.startUpsell()

await shopper.qliro.addUpsellItem({ productVariantId: 'sku-1', quantity: 1 })
await shopper.qliro.updateUpsellItem(itemId, { quantity: 2 })
await shopper.qliro.removeUpsellItem(itemId)

const upsell = await shopper.qliro.getUpsell()
await shopper.qliro.confirmUpsell()

Svea Checkout (SCO)

const order = await shopper.sco.createOrder({ ... })
const order = await shopper.sco.getOrder()
await shopper.sco.syncOrder()

Walley

const checkout = await shopper.walley.createCheckout({ ... })
const checkout = await shopper.walley.getCheckout()
await shopper.walley.syncCheckout()

Zaver

const payment = await shopper.zaver.createPayment({ ... })
const confirmation = await shopper.zaver.getConfirmation()

Gift cards & vouchers

Retain24

await shopper.retain24.addGiftCard('card-id', { amount: 10000, pin: '1234' })
await shopper.retain24.removeGiftCard('card-id')

const product = await shopper.retain24.addGiftCardProduct({
  templateId: 'tpl-1',
  amountToLoad: 50000,
  distribution: 'email',
})
await shopper.retain24.removeGiftCardProduct(itemId)

BSG Gift Card

await shopper.bsgGiftCard.addGiftCard('card-id', { ... })
await shopper.bsgGiftCard.removeGiftCard('card-id')

KBS Gift Card

await shopper.kbsGiftCard.addGiftCard('card-id', { ... })
await shopper.kbsGiftCard.removeGiftCard('card-id')

Loyalty & capabilities

Voyado

await shopper.voyado.start({ contactId: 'uuid-...' })

await shopper.voyado.addVoucher({ checkNumber: 'VOUCHER123' })
await shopper.voyado.removeVoucher(voucherId)

await shopper.voyado.addPromotion({ promotionInstanceId: 'promo-1' })
await shopper.voyado.removePromotion(promotionId)

Bonus

await shopper.bonus.start({ ... })
await shopper.bonus.update({ ... })

External Price

await shopper.externalPrice.start({ customerId: 'customer-1' })

Shipping

Ingrid

const session = await shopper.ingrid.createSession({ ... })
await shopper.ingrid.syncSession({ ... })

NShift

const options = await shopper.nshift.getDeliveryCheckout('11120')
await shopper.nshift.setDeliveryOption({ ... }, '11120')

Custom Shipping

const session = await shopper.customShipping.createSession({ ... })
await shopper.customShipping.syncSession({ ... })

Tax

Tax is computed server-side. If the merchant has Avalara or TaxJar configured, calculated tax shows up in session.cart and checkout totals automatically — there are no shopper-facing tax endpoints to call.