Pre-Filling the Checkout

Overview

gaiia supports a range of URL parameters that let you customize the checkout experience before a customer arrives — from pre-filling address and product details to targeting a specific account type or plan category. This is especially useful for campaign links, QR codes, and targeted signup flows — like routing business and residential customers to separate experiences.

In this article, we'll be covering how each parameter works, how to combine them in a single URL, and how gaiia handles edge cases when inputs are invalid or mismatched.

This feature is enabled by default. There's no setup required in gaiia — everything is configured in the URL.

Pre-Fill an Address

Use the address parameter to pre-fill location details for the customer. The parameter must be a URL-encoded JSON object. It supports the following fields:

• country
• line1
• line2
• locality
• postalCode
• premise
• region
• thoroughfare
• buildingName
• county
• latitude
• longitude
• neighborhood
• nationalAddressIdentifier

None of the fields are strictly required in the URL, but gaiia will only proceed if the required address fields for that country are present. If they're missing, the customer is redirected to the full address form.

For example, in the USA, you'll typically need:

• premise (house or building number)
• thoroughfare (street name)
• line2 (apartment or unit number)
• locality (city)
• postalCode (ZIP code)
• county

If those fields are missing or malformed, prefill will fail and the customer will be directed to the address form.

📝 Note: Always put the house number in the premise field and the street name in thoroughfare. Do not combine them in a single field.

Example

JSON:

{
  "country": "USA",
  "premise": "6864",
  "thoroughfare": "Terreno Drive",
  "locality": "Rancho Murieta",
  "region": "CA",
  "postalCode": "95683"
}

URL-encoded version:

%7B%22country%22%3A%22USA%22%2C%22premise%22%3A%226864%22%2C%22thoroughfare%22%3A%22Terreno%20Drive%22%2C%22locality%22%3A%22Rancho%20Murieta%22%2C%22region%22%3A%22CA%22%2C%22postalCode%22%3A%2295683%22%7D

Preselect Products

Use the products parameter to preselect specific plans or bundles in the signup flow. This is especially useful for campaigns targeting a single offering or for internal tools that send direct signup links.

Provide the slug for each product, separated by commas:

https://signup.yourisp.com/?products=internet-basic,home-phone

If the customer is eligible for those products, they appear preselected on the product selection step. Invalid or unavailable slugs are silently ignored — they won't cause an error.

Set the Account Type

Use the account-type parameter to automatically assign an account type (e.g. Residential or Commercial) for the customer session. To learn more about account types and how they work in checkout, see Account Types in the Checkout.

When a customer arrives via this URL:

• The account type picker is hidden from the checkout flow.
• Only products associated with that account type are displayed.
• The behaviour is identical to a customer manually selecting that account type in checkout.

The parameter value must be all lowercase, with hyphens replacing spaces. For example, Residential becomes residential, and Small Business becomes small-business.

https://checkout.yourisp.com/?account-type=residential

Set the Plan Category

Use the product-types parameter to surface only plans belonging to a specific plan category (such as Internet, TV, or Mobile). To learn more about plan categories and how they're configured, see About Categories and Configuring Categories for Products.

When a customer arrives via this URL:

• Only plans belonging to the specified category are displayed.
• The Shop-By-Service side panel is not shown.

The parameter value should be the slug for the plan category you want to target. To find a category's slug, navigate to Products > Settings > Categories.

https://checkout.yourisp.com/?product-types=internet

You can also target multiple plan categories by separating slugs with commas:

https://checkout.yourisp.com/?product-types=internet,mobile-phone,television

Combine Parameters in a Single URL

All parameters can be used together in a single URL. You can combine any of the following:

• address — pre-fills location details
• products — preselects specific plans or bundles
• account-type — sets the account type and hides the picker
• product-types — filters by plan category

Example using address and product pre-fill together:

https://signup.yourisp.com/?address=%7B%22country%22%3A%22USA%22%2C%22premise%22%3A%229876%22%2C%22thoroughfare%22%3A%22Main%20Street%22%7D&products=internet-basic

This URL will pre-fill the address with 9876 Main Street and preselect the product with slug internet-basic.

Example using product-type and account-type together:

https://signup.yourisp.com/?product-types=internet,mobile-phone&account-type=residential

This URL will pre-fill the address with the plan categories internet and mobile-phone and for the account type residential.

Understand How gaiia Handles Edge Cases

• If the account-type value is invalid or references an account type that wouldn't appear in checkout, gaiia shows the account type picker as usual.
• If the customer's entered address is not associated with the specified account type, gaiia applies the same behaviour as when a manually selected account type returns no available plans.
• If required address fields are missing from the address parameter, gaiia redirects the customer to complete the address form manually.

Best Practices

• Use a URL encoding tool such as urlencoder.org to safely encode your address JSON string.
• Always put the house number in premise and the street name in thoroughfare. Do not combine them into a single field.
• If checkout seems to hang or spin, double-check your encoding and field formatting.
• Invalid product slugs in the products parameter are silently ignored — verify slugs against your product catalog before publishing links.
• You can combine all parameters in the same URL; just ensure everything is cleanly encoded.