BillingRetail

Purpose

BillingRetail is the checkout billing-step reusable for retail customers.

It orchestrates billing address/invoice behavior and step progression in the checkout flow.

Where it's rendered

In Components/Checkout/Default.liquid:

{% render 'Reusables\\BillingRetail\\Default', addresses: addresses, countriesList: countriesList, headQuarterAddress: headQuarterAddress %}

Inputs (Liquid render parameters)

BillingRetail is rendered with named parameters (it doesn’t receive a platform model object).

Model shape (storefront example)

Below is a sanitized excerpt from a real Checkout model dump containing the fields that are passed to this reusable.

{
  "checkout": {
    "billingAddress": {
      "id": "Billing Address Id",
      "name": "",
      "firstName": "Sample first name",
      "lastName": "Sample last name",
      "phoneNumber": "Sample phone",
      "address1": "Sample address",
      "city": "Sample city",
      "state": "Sample state",
      "country": "Sample country",
      "countryCode": "GR",
      "postalCode": "10552",
      "email": "sample@example.com"
    },
    "shippingAddress": {
      "id": "Shipping Address Id",
      "name": "",
      "firstName": "Sample first name",
      "lastName": "Sample last name",
      "phoneNumber": "Sample phone",
      "address1": "Sample address",
      "city": "Sample city",
      "state": "Sample state",
      "country": "Sample country",
      "countryCode": "GR",
      "postalCode": "10552",
      "email": "sample@example.com"
    }
  },
  "countriesList": [
    {
      "code": "GR",
      "name": "Greece"
    },
    ...
  ],
  "addresses": [
    {
      "name": "",
      "isSelectable": true,
      "address": {
        "id": "Address Id",
        "firstName": "Sample first name",
        "lastName": "Sample last name",
        "phoneNumber": "Sample phone",
        "address1": "Sample address",
        "city": "Sample city",
        "state": "Sample state",
        "country": "Sample country",
        "countryCode": "GR",
        "postalCode": "10552",
        "email": "sample@example.com"
      },
      "requiresInvoice": false
    }
  ]
}

Required fields

addresses (array)

Each entry is expected to have:

isSelectable (boolean)

address (object) – the address fields used by AddressForm (id, firstName, lastName, phoneNumber, email, address1, postalCode, city, country/countryCode, state)

countriesList (array)

Each entry is expected to have:

code

name

Optional fields

headQuarterAddress (object | nil)

Passed through to AddressForm.

In the calling site it is only populated for B2B customers and comes from checkout.billingAddress.

Template behavior (Liquid + Alpine)

Source: Reusables/BillingRetail/Default.liquid.

Wraps the content in a container with:

<div class="flex flex-col lg:gap-10" x-data="billingretailreusabledefault">

Renders two steps, each using the Checkout store to show a numbered icon or a “valid” check icon:

Step billingBillingAddress → “Billing Information”

Step billingShippingAddress → “Shipping Information”

Each step conditionally renders its details by calling the Checkout store method:

<div x-show="$store.checkout.canShowDetails('billingBillingAddress')">

and

<div x-show="$store.checkout.canShowDetails('billingShippingAddress')" x-cloak>

Both steps delegate the actual form UI and logic to AddressForm:

{% render 'Reusables\\AddressForm\\Default',
  addressType: 'billing',
  addresses: addresses,
  countriesList: countriesList,
  headQuarterAddress: headQuarterAddress
%}

and

{% render 'Reusables\\AddressForm\\Default',
  addressType: 'shipping',
  addresses: addresses,
  countriesList: countriesList,
  headQuarterAddress: headQuarterAddress
%}

Data contract (JS runtime)

BillingRetail does not declare a JS factory.

Reusables/BillingRetail/Default.js only defines an empty object:

The runtime behavior primarily depends on:

$store.checkout (for step visibility and validity)

addressformreusabledefault.initComponent(...) (for the actual address forms)

JavaScript

File: Reusables/BillingRetail/Default.js

Exposes: billingretailreusabledefault = {}

Global Alpine stores

Used by BillingRetail template:

$store.checkout

steps['billingBillingAddress'].valid / steps['billingShippingAddress'].valid

canShowDetails(stepName)

Used indirectly via AddressForm:

$store.sharedAddresses

Used to sync between the billing and shipping address forms.

$store.toast

AddressForm uses it for validation/invalid-address messages.

Services / API calls

BillingRetail itself has no service calls.

Any API calls related to addresses during checkout come from AddressForm (and/or other higher-level checkout logic).

Dependencies

Reusables/BillingRetail/Default.liquid

Reusables/BillingRetail/Default.js

Reusables/BillingRetail/Default.json (translations)

Reusables/AddressForm/Default.liquid

Reusables/AddressForm/Default.js (main logic)

$store.checkout, $store.sharedAddresses, $store.toast in Assets/js/theme.js

Notes

BillingRetail uses two step names hard-coded in the template:

billingBillingAddress

billingShippingAddress

AddressForm also derives its internal stepName from addressType using the same mapping:

stepName: addressType === "shipping" ? "billingShippingAddress" : "billingBillingAddress",

If GlobalData.Settings.deliveryZonesEnabled is true, AddressForm adds extra validation through $store.sharedAddresses.validAddresses[...] and may show a blocking toast (inValidAddressMessage) until the address is selectable.

Examples

Render (from Checkout):

{% render 'Reusables\\BillingRetail\\Default',
  addresses: model.addresses,
  countriesList: model.countriesList,
  headQuarterAddress: GlobalData.Settings.IsB2bCustomer ? model.checkout.billingAddress : nil
%}

BillingRetail

Purpose#

Where it's rendered#

Inputs (Liquid render parameters)#

Model shape (storefront example)#

Required fields#

Optional fields#

Template behavior (Liquid + Alpine)#

Data contract (JS runtime)#

JavaScript#

Global Alpine stores#

Services / API calls#

Dependencies#

Notes#

Examples#