Types

This page is the curated reference. The complete, generated type reference lives at /kit/api/core and is regenerated from the published typings. Every type here is exported from @quickbutik/kit and @quickbutik/kit/sdk.

Money is always an integer in the currency’s minor unit (öre, cents): 24900 is 249.00. The MinorUnits alias marks every such field. Prices include VAT. Divide by 100 or use formatMoney, with the currency the response states (product.currency, cart.currency). See Currencies.

Page

interface Page<T> {
  data: T[]
  has_more: boolean
  next_cursor: string | null
}

Product

string

Prefixed, "prod_123". Pass it straight to cart.add.

string | null

number | null

Display price, minor units, in currency.

string | undefined

What every price on this product is in: the client’s chosen currency when the shop offers it, else the shop’s own. Format with this. Absent on a platform older than the field.

string | null

Merchant-authored HTML.

string | null

boolean | null

number | null

VAT percentage: 25, 12, 6.

string | null

Preferred by buildSeo.

string | null

ProductImage[]

ProductOptionType[] | undefined

Optional on the wire; the variant matrix rebuilds groups from the variants when absent.

ProductVariant[]

A simple product has one synthetic variant.

ProductSection[] | undefined

Merchant content sections, in order.

Only from products.get().

A product has no category membership: a category page is products.search({ categoryId }).

ProductVariant

number

The numeric id the cart takes as variantId.

string

string | null

number | null

Grams.

boolean | null

number | null

number | null | undefined

The id of one of the product’s own images, or null.

ProductVariantPrice

Show properties

number | null

Minor units. Falls back to product.price when null.

number | null

The “before” price; null when not on sale.

ProductVariantStock

Show properties

number | null

null means not tracked, so purchasable. Only a number at or below 0 is out of stock.

boolean | null

ProductOptionValue[]

The option values this variant is made of.

ProductImage

number

string | null

Absolute, without resize parameters. Render this.

string | null

The bare storage filename. Not a URL; rendering it 404s.

number | null

string | null

Cache-buster. "temp" means the file is still being processed.

ProductOptionType and ProductOptionValue

interface ProductOptionType {
  id: number
  name: string | null      // "Färg", "Storlek": merchant data, differs per product
  position: number | null
}

interface ProductOptionValue {
  id: number
  name: string | null
  position: number | null
  optionId: number | null
}

ProductSection

interface ProductSection {
  id: string       // stable render key
  title: string    // may be empty
  content: string  // merchant HTML; sanitize before injecting
}

Rendered the way the Quickbutik theme renders them: template-linked sections carry the template’s text, and the [STOCKLEFT], [PRICE] and [BEFOREPRICE] merge tags are replaced.

RelatedProducts

'category' | 'specific' | 'none'

category: up to 8 from the same category, newest first. specific: the merchant’s hand-picked list, up to 12. none: always empty.

RelatedProductSummary[]

Show properties

string

"prod_123"

string | null

{ price: number | null; comparePrice: number | null }

Priced like the product list, discounts and campaign prices included.

ProductImage | null

Shop

string

string | null | undefined

The shop’s own (base) currency, upper-case ISO 4217. Absent on a platform older than the field.

ShopCurrency[] | undefined

Every currency a shopper may browse in, base first. Only the base entry when the merchant’s currency converter is off; read a missing field the same way.

Show properties

string

Upper-case ISO 4217.

'base' | 'display' | 'charge'

base: the shop’s own. display: shown converted, charged in the shop’s currency. charge: priced and charged in this currency. Exported as ShopCurrencyMode.

number

Units of this currency per 1 unit of the shop’s currency.

string | null | undefined

"sv"

boolean | undefined

ShopBrand

Show properties

string | null

string | null | undefined

Doubles as the home page meta description.

string | null

Hex, or null when never set.

ShopTracking | null | undefined

The merchant’s tracking ids as configured in the admin, already validated by the platform. What the kit’s analytics loads by default (destinationsFromShop). Absent on a platform older than the field.

Show properties

string | null

G-…

string | null

GTM-…

string | null

Numeric pixel id.

boolean

Whether the platform sends Meta Conversions API events for this shop. Access tokens never leave the server.

The wire payload also carries demo.enabled, not declared on the type: true while the shop has not activated Quickbutik Payments and its checkout runs in demo mode.

Cart

string

number

The shop’s numeric id, what the hosted checkout URL needs.

CartItem[]

number

Sum of quantities, not of lines.

string

What every amount in this response is in. A cart is priced per request, so the same cart can read in SEK on one request and EUR on the next.

CartPresentment | undefined

How currency relates to the checkout. A missing field means mode: "base".

Show properties

'base' | 'display' | 'charge'

display: amounts converted for display, the checkout charges chargeCurrency (the shop’s own). charge: amounts are what the checkout will charge.

string

What the checkout will charge in.

string

The shop’s own currency.

number

Units of currency per 1 unit of baseCurrency. 1 for base.

number

Display figure, following the shop’s VAT setting. Also subtotalExclTax, subtotalInclTax.

number

Display figure. Also totalExclTax, totalInclTax.

string

string | null | undefined

The campaign storefront the cart is bound to.

StorefrontSurface | null | undefined

Shipping is chosen in the hosted checkout, so a cart total covers products only.

CartItem

string

The line id. The handle for updateItem and removeItem.

number

number | undefined

number

string | null

"Red / XL"; null for a simple product.

string | null

Absolute. Size it with applyImageTransform.

number

Display figure. Also unitPriceExclTax, unitPriceInclTax.

number | null

number

Display figure. Also lineTotalTax, lineTotalExclTax, lineTotalInclTax.

boolean

False once the product was hidden or deleted.

CheckoutSession

Returned by createSession() and as session on a v2 start result.

string

string | null

null for an inline session created without one.

string | null

{ origin: string; returnUrl: string } | null | undefined

'redirect' | 'inline' | undefined

string | null | undefined

StorefrontSurface | null | undefined

'light' | 'dark'

The effective theme.

DisplayCurrency | null | undefined

The currency the checkout shows an approximate amount in, set when the session was created with a "display" currency. null when none applies (no currency sent, the shop’s own, or a "charge" currency, in which case data.pricing.value.currency is it).

Show properties

string

Upper-case ISO 4217.

number

Units of code per 1 unit of the currency the session is charged in.

Record<string, FieldState>

Shopper-supplied values with the server’s verdict: value, status (empty, valid, invalid), errors, updatedAt.

Record<string, DataState>

Server-computed nodes: value, resolvedAt.

CheckoutSessionSnapshot

Returned by getSession() and syncCart(). The same fields as a session (without sessionId and theme), plus:

boolean

Whether the checkout can take payment.

string[]

What still stands in the way.

The data nodes worth reading (CheckoutDataNodes):

Node	Contents
`cart_products`	The lines as the session snapshotted them: `productId`, `variantId`, `name`, `variantName`, `price`, `quantity`, `imageUrl`
`pricing`	Product-only subtotals, `taxOnTop`, and `currency` (what the session is priced and charged in), with `baseCurrency` and `exchangeRate` when that differs from the shop’s own
`order_total`	The authoritative total: `subtotal`, `totalTax`, `totalDiscount`, `totalShipping`, `totalPaymentFee`, `total`, `currency`, `lines`
`shipping_cost`, `payment_cost`, `discount`, `promocode`	`OrderLine[]`: `id`, `tag`, `label`, `amount`, `taxRate`, `taxAmount`

order_total.total is the figure the shopper is charged. Never recompute it.

SessionConfirmation

'completed' | 'processing_payment' | 'no_attempt' | 'failed'

processing_payment: paid, order being created (typically 6 to 17 seconds). no_attempt: no payment attempt known yet.

number | undefined

'redirect' | 'inline' | undefined

string | undefined

number | undefined

ConfirmationOutcome

type ConfirmationOutcome =
  | { kind: "completed"; orderNumber: number | null; confirmation: SessionConfirmation }
  | { kind: "failed"; confirmation: SessionConfirmation }
  | { kind: "timeout"; lastStatus: ConfirmationStatus | null }  // NOT a failure
  | { kind: "aborted" }

orderNumber can be null on completed. Fall back to checkout.parseReturnUrl(location.href)?.orderNumber for display.

CurrencyInfo

What describeCurrency(shop, selected) and useCurrency() resolve a currency choice to.

string | null

What prices are shown in: the choice when the shop offers it, else the shop’s own. null only before the shop is known with nothing chosen.

string | null

The shop’s own currency.

'base' | 'display' | 'charge'

number

Units of currency per 1 unit of the base currency. 1 for base.

string | null

What the checkout will charge: the base currency, or currency in charge mode.

ShopCurrency[]

Every currency the shop offers, base first. Empty until the shop is known.

ConsentState

The shopper’s cookie decision, as shopkit.consent.read(), readConsentCookie() and the consent store report it. ConsentSnapshot (the store’s snapshot) adds open: boolean, whether the preferences panel is open.

'undecided' | 'decided'

Undecided is treated as denied.

boolean

string | null

ISO timestamp of the decision.

number

The cookie-policy revision the decision was made under.

ConsentCategory is "necessary" | "analytics" | "marketing"; ConsentChoice is { analytics: boolean; marketing: boolean }. See Consent and analytics.

Getting Started

Vanilla JavaScript

React

Web Components

Concepts

API Reference

Page

Product

ProductVariant

ProductImage

ProductOptionType and ProductOptionValue

ProductSection

RelatedProducts

Category

Shop

Cart

CartItem

CheckoutSession

CheckoutSessionSnapshot

SessionConfirmation

ConfirmationOutcome

CurrencyInfo

ConsentState

​Page

​Product

​ProductVariant

​ProductImage

​ProductOptionType and ProductOptionValue

​ProductSection

​RelatedProducts

​Category

​Shop

​Cart

​CartItem

​CheckoutSession

​CheckoutSessionSnapshot

​SessionConfirmation

​ConfirmationOutcome

​CurrencyInfo

​ConsentState

Page

Product

ProductVariant

ProductImage

ProductOptionType and ProductOptionValue

ProductSection

RelatedProducts

Category

Shop

Cart

CartItem

CheckoutSession

CheckoutSessionSnapshot

SessionConfirmation

ConfirmationOutcome

CurrencyInfo

ConsentState