## Zoho Billing - Product, solutions, integrations, support, and resources Index

Access the complete documentation index at:
https://www.zoho.com/bh/billing/llms.txt

Use this file to discover all available documentation pages before proceeding.

# Prefill Hosted Payment Pages

Prefilling Hosted Payment Pages is useful if you collect a new customers’ basic information on your own webpage or form application, and then direct them to one of Zoho Billing’s Hosted Payment Pages.

By prefilling Hosted Payment Pages, the data that you’ve collected from your customers on your own webpage or form will be filled into the Hosted Payment Page. This can save your customers from the hassle of entering their details all over again–thereby providing a more seamless transition to the Hosted Payment Page.

**Insight:**

Your customers will be able to **edit** their data on the Hosted Payment Page if you prefill it using this method, instead of via API.

## Setting up Prefilled Hosted Payment Pages

Prefilling Hosted Payment Pages works by passing field values as parameters in a plan’s URL.

To get your plan’s URL:

*   Navigate to _Product Catalog_ > _Subscription Items_.
*   Select a subscription item.
*   Find the plan that you’re looking for and click **Share Hosted Payment Page**.
*   Click **Copy** below the link in the _URL_ tab to copy the plan’s URL.

Now, you’ll need to append the information that you’ve collected from your customers as parameters to this URL, after which, you can use it to direct customers to the prefilled Hosted Payment Page.

#### Appending Parameters to Your Plan’s URL

You can view a [list of all the parameters that can be prefilled](/bh/billing/help/settings/customisation/pre-fill.html#list) in the Hosted Payment Pages, along with specific notes for some parameters. The information that you want to be prefilled on the Hosted Payment Page should be mapped to these parameters and then be appended to the plan’s URL.

#### Points to note while appending parameters:

*   Make sure to add a **question mark** at the end of the plan’s URL, before you start appending parameters.
    
    For example, If your plan’s URL is:
    
    ```
      https://billing.zoho.com/subscribe/dc506029cac98b6asdfjhvb543e474d9403c16d836d1bc4e3bd2c445f231875e271/123
    ```
    
    Add a question mark at the end to make it look like this:
    
      `https://billing.zoho.com/subscribe/dc506029cac98b6asdfjhvb543e474d9403c16d836d1bc4e3bd2c445f231875e271/123?`
      
    
*   Once you’ve added the question mark at the end, you can start appending parameters by following this format in the plan’s URL: “[**parameter placeholder**](/bh/billing/help/settings/customisation/pre-fill.html#list)**\=parameter value**”. You should **ensure that every parameter placeholder is associated with a value**, to avoid loading errors.
    
    So, if you want to append the parameter for your customer’s first name, for which the placeholder is **first\_name**, the URL will look like this:
    
    _(Let’s assume your customer’s name is Patrick)_
    
      `https://billing.zoho.com/subscribe/dc506029cac98b6asdfjhvb543e474d9403c16d836d1bc4e3bd2c445f231875e271/123?first_name=Patrick`
    

**Warning:**

To avoid errors while accessing Hosted Payment Pages, it’s necessary that you **encode** the parameter’s **value** alone. This is to ensure that special characters or blank spaces that your customers enter get converted to a URL-friendly format.

E.g. If your customer’s billing address is “**Southern California**”, after encoding it, it would be “**Southern%20California**”. Here’s how that would look in the plan’s URL:

```
https://billing.zoho.com/subscribe/dc506029cac98b6asdfjhvb543e474d9403c16d836d1bc4e3bd2c445f231875e271/123?billing_city=Souther%20California
```

The need to encode special characters also applies to placeholders like **addon\_code\[0\]**, where the square brackets **\[ \]** are special characters. This is what a URL with the addon code as 456 would look like:

```
https://billing.zoho.com/subscribe/dc506029cac98b6asdfjhvb543e474d9403c16d836d1bc4e3bd2c445f231875e271/123?addon_code%5B0%5D=456
```

**Pro Tip:**

If you’re using a form application to collect your customer’s data before directing them to the Hosted Payment Page, look into how the form application can construct and encode the URL automatically. For example, [Zoho Forms](/forms/) can [map fields to a placeholder’s name and construct the URL with encoded values](https://help.zoho.com/portal/en/kb/forms/form-settings/prefill/articles/field-alias). On the other hand, if you’re using your own web page or application to collect data, you can use something like JavaScript’s `encodeURIComponent` function.

*   Multiple parameters should be separated by the ampersand sign (**&**).
    
    This is how a plan’s URL with multiple parameters would look:
    
    ```
    https://billing.zoho.com/subscribe/dc506029cac98b6asdfjhvb543e474d9403c16d836d1bc4e3bd2c445f231875e271/123?first_name=Patrick&last_name=Jane
    ```
    

After you’ve constructed your plan’s URL with the appended parameters, you can use it to direct your users to the plan’s Hosted Payment Page with all the prefilled data.

### List of Parameters That Can Be Prefilled

**Order Summary**

*   quantity
*   addon\_code\[0\]
    
    > _As mentioned above, special characters–like the square brackets_ _**\[**_ _**\]**_ _used for this parameter–need to be encoded to a URL-friendly format. So, the_ _**addon\_code\[0\]**_ _placeholder will look like_ _**addon\_code%5B0%5D**_\*, after it has been encoded.\*
    
*   addon\_quantity\[0\]
    
    > The _**addon\_quantity\[0\]**_ _placeholder will look like_ _**addon\_quantity%5B0%5D**_\*, after it has been encoded.\*
    
*   coupon\_code
*   tax\_reg\_no

**Account Information**

*   first\_name
*   last\_name
*   email
*   company\_name
*   phone
*   mobile
*   website

**Billing Address**

*   billing\_street
    
*   billing\_city
    
*   billing\_zip
    
*   billing\_state\_code (or) billing\_state
    
    > For **Canada**, **India**, the **United Arab Emirates** and the **United States of America**, you should use the **billing\_state\_code** parameter, whose value should be a 2-letter state code (for example, TN for Tamil Nadu and KY for Kentucky). For all other countries, use the **billing\_state** parameter, whose value can be the name of the state itself, i.e, a state code is not required for the value of this parameter.
    
*   billing\_country\_code
    
    > The **value** of the billing country code must be the equivalent **ISO 3166-1** code for the country in the **Alpha-2** (2-letter) format. For example, IN for India and US for the United States of America. By providing this code, the country will be selected automatically from a dropdown in the Hosted Payment Page.
    

**Shipping Address**

*   shipping\_street
*   shipping\_city
*   shipping\_zip
*   shipping\_state\_code (or) shipping\_state
    
    > For **Canada**, **India**, the **United Arab Emirates** and the **United States of America**, you should use the **shipping\_state\_code** parameter, whose value should be a 2-letter state code (for example, TN for Tamil Nadu and KY for Kentucky). For all other countries, use the **shipping\_state** parameter, whose value can be the name of the state itself, i.e., a state code is not required for the value of this parameter.
    
*   shipping\_country\_code
    
    > The **value** of the shipping country code must be the equivalent **ISO 3166-1** code for the country in the **Alpha-2** (2-letter) format. For example, IN for India and US for the United States of America. By providing this code, the country will be selected automatically from a dropdown in the Hosted Payment Page.
    

### Prefill Customer and Invoice Custom Fields Using API Field Names

You can prefill custom fields for customers and invoices in the Hosted Payment Pages by adding the custom field’s API field name as the parameter placeholder. If you collect custom field values on another webpage or form before redirecting customers to the Hosted Payment Page, you can pass those values in the Hosted Payment Page URL parameters and prefill them during checkout.

To include custom fields in the Hosted Payment Page and prefill them using URL parameters, follow these two steps:

#### Step 1: Include Custom Fields in the Hosted Payment Page Template

**Note:**

This feature is enabled by default for organizations created after July 1, 2026. For existing organizations, this feature is currently in early access. Reach out to our support at [support@zohobilling.com](mailto:support@zohobilling.com) to get it enabled for your organization.

Once you enable this feature, you can include customer and invoice custom fields directly in the Hosted Payment Page.

**Note:**

If you previously passed custom field values directly in the Hosted Payment Page URL, remove those values and use the [API field method to prefill](/bh/billing/help/settings/customisation/pre-fill.html#step-2-api-field-names) them instead. Learn how to [migrate from URL-based parameters to template-based custom fields](/billing/kb/hosted-payment-pages/switch-to-template-based-custom-fields.html).

*   Go to **Settings** > **Hosted Payment Pages**.
*   Edit the required template.
*   Open the **Order Details** tab.
*   Under **Account Information**, click **Add Field** under **Customer Custom Fields** to add customer custom fields.
*   Under **Additional Information** (Single-Page template) or **Final Summary** (Multi-Page template), click **Add Field** under **Invoice Custom Fields** to add invoice custom fields.
*   Choose the field type (**Optional**, **Mandatory**, **Hidden**, or **Read Only**) based on your requirement.
*   Click **Save**.

#### Step 2: Include Custom Field API Field Names in the Hosted Payment Page URL

To include a customer or invoice custom field value in the Hosted Payment Page link:

*   Go to **Settings** > **Preferences** > **Customers** > **Field Customization** for customer custom fields.
*   Or go to **Settings** > **Preferences** > **Invoices** > **Field Customization** for invoice custom fields.
*   Click **Edit** next to your custom field.
*   Copy the **API Field Name** and use it as the parameter placeholder in your plan URL.

For example, if the API field name is **cf\_customer\_segment** and the value is **Enterprise**, append it like this:

```
https://billing.zoho.com/subscribe/dc506029cac98b6asdfjhvb543e474d9403c16d836d1bc4e3bd2c445f231875e271/123?cf_customer_segment=Enterprise
```

To pass multiple customer custom fields, append each one using **&**:

```
https://billing.zoho.com/subscribe/dc506029cac98b6asdfjhvb543e474d9403c16d836d1bc4e3bd2c445f231875e271/123?cf_customer_segment=Enterprise&cf_customer_code=ZYLK-001
```

**Note:**

Encode each parameter value before appending it to the URL. If the value contains spaces or special characters, use URL encoding.

![Customer Custom Fields Placeholder](/billing/images/help/images/settings/customisation/hosted-payment-pages/customer-field-placeholder.png)

**Note:**

If you don’t see the API Field Name for your custom field, reach out to our support at [support@zohobilling.com](mailto:support@zohobilling.com) for further assistance.

Also, if your custom field is of the **Date** data type, make sure the date value is in the **YYYY-MM-DD** format.

**Note:**

If a Customer custom field and an Invoice custom field share the same API field name, prefix the parameter placeholder with the module name to distinguish them. Use **customer.cf\_fieldname** for customer fields and **invoice.cf\_fieldname** for invoice fields.

For example: `?customer.cf_segment=Enterprise&invoice.cf_segment=Renewal`.

When the customer submits through the Hosted Payment Page, the prefilled values are saved automatically in Zoho Billing.

* * *