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.
Setting the account type
Use the account-type parameter to preselect an account type — Residential or Business, for example — for the customer's session. To learn more about account types in checkout, see Account Types in the Checkout.
The value is the account type's name, lowercased with hyphens replacing spaces. Residential becomes residential; Small Business becomes small-business.
https://signup.yourisp.com/?account-type=residential
When a customer arrives through that link:
- The account type picker is skipped.
- Only products associated with that account type are shown.
- Behaviour matches a customer selecting that account type manually.
If the value doesn't match a configured account type, gaiia ignores it and shows the picker as usual. If your checkout runs a product availability workflow that restricts account types, that workflow wins — an account type it doesn't allow is replaced with the first one it does.
Filtering by service type
Use the product-types parameter to show only plans of a given service type.
The values are gaiia's service types, not the categories under Products > Settings > Categories. Use the service type in lowercase with hyphens for underscores: internet, mobile-phone, residential-phone, television.
https://signup.yourisp.com/?product-types=internet
Separate multiple service types with commas:
https://signup.yourisp.com/?product-types=internet,mobile-phone
When the parameter matches at least one configured service type, only those plans are shown and the Shop-By-Service side panel is hidden.
Service types marked as required in your checkout configuration are always included, whether or not you list them. If Internet is required, ?product-types=television still shows Internet plans alongside Television. If none of the values match a configured service type, the parameter is ignored and checkout behaves normally.
Combining parameters
All four query parameters work together in a single URL:
-
address— pre-fills location details -
products— preselects specific plans or bundles -
account-type— sets the account type and skips the picker -
product-types— limits checkout to given service types
https://signup.yourisp.com/?product-types=internet,mobile-phone&account-type=residential
The promo code is the exception — it is a URL path, not a query parameter, so it goes at the end of the domain rather than after a ?.
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.
Related to