Pre-filling the Checkout

Overview

gaiia supports advanced checkout prefill by letting you pass address, product, and promo code 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 parameter options and promo code link 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.

Prefilling a Promo Code

You can also share a checkout link that carries a promo code, so the discount is applied automatically and the customer never has to type the code. Unlike the address and products options above, a promo code is not passed as a query parameter — it's added as a path at the end of your checkout URL:

https://<your-checkout-domain>/promo/YOURCODE

For example, for a code named SUMMER25:

https://<your-checkout-domain>/promo/SUMMER25

When a customer opens the link, the promo code is saved and carried through the checkout. It's validated and applied automatically once the customer has entered their address, since the assigned discount product needs to match their coverage area.

The promo code must already exist and be active in your instance. The same eligibility rules apply as when a code is entered manually: the assigned discount product has to be within the customer's coverage area, and configured in any property where you want the code to work. See Promo Codes - Overview to set one up.

A few things to keep in mind:

• Only one promo code can be applied per checkout.
• If the code is expired or invalid, the customer is still taken to the checkout, where a message lets them know the code could not be applied.

If your signup link uses a custom domain that redirects to your gaiia checkout, make sure the redirect preserves the full URL path (including the /promo/ portion). Otherwise the promo code is dropped during the redirect and won't be applied.

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.