Pre-filling the Checkout

Overview

gaiia supports advanced checkout prefill by letting you pass address and product information directly into the signup URL. This is especially useful for creating campaign links, QR codes, or quick-start signup flows where you already know the customer's details.

In this article, we'll be covering how to use this feature, what the two parameter options look like, and how to avoid common formatting mistakes.

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

Using the Checkout Prefill Function

There are two parameters you can use with checkout prefill:

• address — a JSON-stringified object that pre-fills location details
• products — a comma-separated list of product slugs to preselect options

You can use either one on its own, or combine them for a full prefill experience. Below, we'll cover how to use each one — and how to make sure the formatting doesn't break things.

Here's a complete example using both parameters:

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 fields with 9876 Main Street
• Pre-select the product with slug internet-basic

Not seeing the product or address appear? Scroll down to Best Practices for common fixes.

Prefilling an Address

One of the options is using the address parameter to prefill location details. This lets you pass known address info directly into the first step of checkout — helpful if you're linking from an internal tool or targeting a known building or neighborhood.

The parameter must be a URL-encoded JSON object. It supports the following fields:

{
  country?: string,
  line1?: string,
  line2?: string,
  locality?: string,
  postalCode?: string,
  premise?: string,
  region?: string,
  thoroughfare?: string,
  buildingName?: string,
  county?: string,
  latitude?: number,
  longitude?: number,
  neighborhood?: string,
  nationalAddressIdentifier?: string
}

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 user will be redirected to the full address form.

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

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

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

When passing address information, always ensure that the house number is in the 'premise' field and the street name is in the 'thoroughfare' field. 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

Prefilling Products

The other option is using the products parameter to preselect specific plans or bundles in the signup flow. This is especially handy for campaigns targeting a single offering — or for internal tools sending direct signup links.

Use the slugs for each product, separated by commas. Example:

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

If the user is eligible for those products, they’ll appear preselected on the product selection step.

Invalid or unavailable slugs are ignored — they won’t throw an error.

Best Practices

• Use a tool like urlencoder.org to safely encode your address JSON string.
• Don’t combine the house number and street name. Instead of putting 9876 Terreno Drive in thoroughfare, split it like this:
  • premise = 9876
  • thoroughfare = Terreno Drive
• If required address fields are missing, gaiia will redirect the user to complete the form manually.
• If checkout seems to hang or spin indefinitely, double-check your encoding and field formatting.

You can combine both parameters in the same URL — just be sure everything is clean and encoded properly.