Storefront fields

Reference for the settings of a WaveRunner storefront, its checkout settings, the fulfilment statuses of a store order, the two storefront CSV flows and the merchant profile fields the legal pages read. For the setup walkthrough see the Storefronts guide.

Store settings

Field	Type	Description
name	string	The store's name, shown in the admin app and to pages as the {{store.name}} token. Max 255 characters.
slug	string	URL-safe store identifier, unique per tenant.
domain	string	The custom domain the store is served on: one of the tenant's registered custom domains, or blank while it has none.
locale	string	en or de; the language of the checkout labels and the starter kit copy. Default en.
currency	string	ISO 4217 code every product sold in the store is priced in; bound collections and the gateway must agree with it. Default EUR.
countries	array	ISO 3166-1 alpha-2 codes of the markets the store serves; shipping and tax resolve per country.
payment_gateway	uuid	The gateway the store's orders bill through. A selling store cannot be published without one.
merchant_profile	uuid	The seller's legal identity, read by the legal pages and the order emails. Blank uses the tenant's default active merchant profile.
discount_profile	uuid	Discount codes and automatic discounts for the checkout. Blank means no discounts.
shipping_profile	uuid	Shipping zones and rates for the checkout. Blank means no shipping line.
tax_profile	uuid	Tax rates by country and tax class. Blank means no tax line.
autoresponder_profile	uuid	The email rules for the store's orders, stamped on every order of the store.
allow_repeat_customers	boolean	Off: an IBAN that already paid an order of this store cannot order again here. It can only tighten the tenant's duplicate IBAN rule, never loosen it. Default true.

Checkout settings

The checkout_settings object of a store. Every key is optional; an absent key takes the default.

Key	Type	Default	Description
fulfil_on	string	order_created	When an order enters the fulfilment queue and its stock is committed: order_created or order_completed (after the payment completes).
max_payment_attempts	integer	3	Payment attempts allowed per checkout, 1 to 10.
duplicate_lead_handling	string	ALLOW	ALLOW or BLOCK an order from a customer who already exists.
duplicate_lead_keys	array	["EMAIL"]	What identifies an existing customer: EMAIL, IBAN. Not empty when the handling is BLOCK.
button_label	object	runtime default	The pay button label per locale, keys en and de, up to 60 characters each.
terms	object	none	The terms acceptance: mode is none, notice or checkbox; text holds the wording per locale, up to 500 characters each.
required_fields	array	[]	Checkout fields required besides name, email and IBAN: phone, address, city, postal_code, country.
email_first	boolean	false	Capture the email on the cart as soon as it is valid.
upsell_flow	object	{"pages": []}	The post-purchase upsell pages shown after a successful checkout, in order: {"pages": [<page id>, ...]}, at most 20 upsell pages of the store.

Fulfilment statuses

The fulfilment_status of an order. Orders that did not come from a store, and store orders with nothing to ship, read not_required.

Status	Meaning
not_required	Nothing to ship (a digital product, or an order from outside a store).
unfulfilled	Waiting to be packed and shipped; listed in the fulfilment queue once it reached the store's fulfil point.
fulfilled	Picked and packed, not yet shipped.
shipped	A shipment with a carrier and tracking was created; sends order.shipped.
delivered	The latest shipment was delivered; sends order.delivered.
returned	The shipped or delivered order came back and its stock was returned; sends order.returned.

The fulfilment events and their variables are listed in Webhook Events.

Stock CSV columns

The stock CSV update, matched by sku or the variant id. A row gives either delta or on_hand, never both. Every row that moves stock writes a stock adjustment with the reason csv; reserved quantities are never changed.

Column	Type	Description
delta	integer	Added to the stock on hand; may be negative. 0 changes nothing.
note	string	Recorded on the adjustment, up to 255 characters. A note alone moves nothing.
on_hand	integer	The new stock on hand, 0 or more; the difference to the current level is what is recorded.

Reviews import columns

The reviews import (POST /api/v2/product-reviews/import/) takes the rows of a CSV file. Every row is validated before anything is created; a dry run reports each row as would_create or rejected without creating a review. Imported reviews carry the source import, and the verified purchase flag is computed from the author email.

Column	Type	Description
product	string	Required. The product slug, or the product id when the import reads products by id.
rating	integer	Required. 1 to 5.
title	string	Up to 255 characters.
body	string	The review text.
author_name	string	Up to 255 characters.
author_email	string	A valid email address or blank; used for the verified purchase flag.
submitted_at	string	ISO 8601 date or date and time; UTC when no offset is given; blank means now.
review_status	string	pending (default), approved or rejected. A status other than pending moderates the review.

Merchant profile fields on the legal pages

The legal pages of a starter kit read the store's merchant profile through merchant tokens. A token resolves only when its field has a value; a published page that uses a token without a value is refused by the publish checks, so fill the profile (or delete the line) before publishing.

Token	Merchant profile field
{{merchant.legalName}}	Legal name (the profile name when blank; the tenant's legal name as the last fallback)
{{merchant.legalForm}}	Legal form, for example GmbH or Ltd
{{merchant.addressLine1}}	Address line 1
{{merchant.addressLine2}}	Address line 2
{{merchant.postalCode}}	Postal code
{{merchant.city}}	City
{{merchant.country}}	Country code
{{merchant.registerCourt}}	Register court
{{merchant.registerNumber}}	Register number
{{merchant.vatId}}	VAT identification number
{{merchant.contactEmail}}	Contact email (the tenant's support email as the fallback)
{{merchant.contactPhone}}	Contact phone
{{merchant.representatives}}	The names of the representatives, comma separated
{{merchant.responsiblePersonName}}	EU responsible person: name
{{merchant.responsiblePersonAddress}}	EU responsible person: address
{{merchant.responsiblePersonEmail}}	EU responsible person: email

Related pages

• Session Fields: the lines and subscriptions keys of a storefront session.
• Webhook Events: order.created and the fulfilment events.
• Webhooks and CSV Imports.