> For the complete documentation index, see [llms.txt](https://docs.peakcommerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peakcommerce.com/integrations/billing-and-payments/zuora-integration/zuora-billing-integration.md). # Zuora Billing ### **Overview** Setting up the Billing Integration is an essential step in provisioning PeakCommerce Production and Sandbox tenants. Zuora is one of the billing systems that PeakCommerce can integrate with. To get to the Billing Integrations page, navigate to Integrations > Billing. These settings can be managed by clicking the edit button at the bottom of the page. See the example below. Once the integration is connected, subscription changes made through PeakCommerce — plan switches, add-ons, quantity updates, pauses, and cancellations — are submitted to Zuora via the **Zuora Orders API**. Each change therefore appears as an **Order** on the Zuora account (with Zuora's full order history and audit trail) rather than as a legacy amendment, matching Zuora's current order-based model. ### **Steps** Follow the steps below to integrate the PeakCommerce platform with Zuora. #### 1. Create an API user in Zuora Log in to Zuora with an admin account from the company in order to create an API Only user at the platform level. An API role must already be created. For more information on creating an API role, and setting up a new API user, view the Zuora article: [*Create an API User*](https://knowledgecenter.zuora.com/Billing/Tenant_Management/A_Administrator_Settings/Manage_Users/Create_an_API_User)*.* Click on the username in the top right corner and navigate to Setting > Administration > Manage Users. Click “add single-user” to start filling out the basic information. See the example below. This page requires basic information to create the user. A description of each field can be found below in the order they appear on the New User page. * **Tenant Id:** This field is automatically populated. * **Tenant Name:** This is field is automatically populated. * **First Name:** Contact Zuora administrator for the appropriate name to assign. The name can be edited later. * **Last Name:** Contact Zuora administrator for the appropriate name to assign. The name can be edited later. * **Work Email:** Contact Zuora administrator for the appropriate group email to assign. * **Login Name:** Contact Zuora administrator for the appropriate name to assign. The login name cannot be changed after creating the user. * **Zuora Platform Role:** This must be set to "API Only". * **Billing Role:** Contact Zuora administrator for the appropriate role to assign. * **Payments Role:** Contact Zuora administrator for the appropriate role to assign. * **Finance Role:** Contact Zuora administrator for the appropriate role to assign. * **Commerce Role:** Contact Zuora administrator for the appropriate role to assign. * **Reporting Role:** Contact Zuora administrator for the appropriate role to assign. * **Locals:** This should be set to the companies specific region. * **Language:** This should be set to a preferred language. After filling in these fields click "save" at the bottom of the page. Go into the email used to create the user and wait for an activation email from Zuora. #### 2. Activate the User Upon receiving the email, open the link provided in an Incognito window to set the password and create a security question. You can then close this window and go back to the Zuora admin. #### 3. Put Information into PeakCommerce The information from the new user must be added to the Billing Integrations page on PeakCommerce. A description of these fields can be found in the order they appear. **Endpoint** For API Sandbox, the URL in this field should read: For Central Sandbox, the URL in this field should read:\ \ \ For Production, the URL in this field should read: . {% hint style="info" %} Note: When provisioning PeakCommerce Production tenants, this field will prepoulate with the same URL as was entered here in Sandbox. Update it to the Zuora's Production URL. {% endhint %} **Username** Enter the Login name used to set up the API user in Zuora into the field. **Password** Enter the password used to activate the API user set up in Zuora into the field. **Tenant Id** The Tenant Id can be found in Zuora in the Basic Information of the API user that was just created. See the example below. Copy the Tenant Id and paste it into the field in PeakCommerce **API Security Key 1.0 and 2.0** These fields refer to the versions of Hosted Pages being used. The API Security Keys can be found in Zuora by clicking on the username in the upper right corner and navigating to Payments > Setup Hosted Pages. On the page, there are buttons that say “get hpm 2.0 key” and “get hpm 1.0 key”. See the example below. Clicking on the buttons will download text files containing the keys. Open the files to copy the keys one at a time and paste them into PeakCommerce ensuring there are no spaces. **Zuora App URL** For API Sandbox, the URL in this field should read [https://apisandbox.zuora.com](https://apisandbox.zuora.com/). For Central Sandbox, the URL in this field should read . For Production, the URL in this field should read [https://zuora.com](https://zuora.com/). Note: When provisioning PeakCommerce Production tenants, this field will prepoulate with the same URL as was entered here in Sandbox. Update it to Zuora's Production URL. **Zuora Rest URL** For API Sandbox, the URL in this field should read [https://rest.apisandbox.zuora.com](https://rest.apisandbox.zuora.com/). For Central Sandbox, the URL in this field should read . For Production, the URL in this field should read [https://rest.zuora.com](https://rest.zuora.com/). Tip: When provisioning PeakCommerce Production tenants, this field will pre-populate with the same URL as was entered here in Sandbox. Update it to Zuora's Production URL. **Client Id and Client Secret** The Client ID and Client Secret are created by creating an OAuth client on the API user in Zuora. This is used to authenticate to the Zuora Rest API. To create an OAuth pull up the new API user. Underneath the user's profile Basic Information there is a section for OAuth Clients. See the example below. In the OAuth Clients section, enter a name for the OAuth client and hit create at the bottom of the page. Zuora will display a one-time popup with the Client Id and Client Secret. This is the only time you will see these fields however, the Client Id and Secret can be regenerated if needed. Copy the Id and Secret and insert them into the fields in PeakCommerce. **Tenant Timezone** Enter your Zuora tenant's billing timezone as an **IANA timezone name** (for example `America/New_York`, `Europe/London`, or `UTC`). PeakCommerce uses this to compute activation dates and order timing correctly for journeys that **honor activation offsets** — such as trial and deferred-activation flows — so an order meant to activate, say, "7 days from the contract effective date" lands on the right calendar day for your billing tenant. {% hint style="info" %} Zuora does not expose the tenant timezone over its API, so it must be entered here manually. Set it to match the timezone configured on your Zuora tenant. If your journeys don't use activation offsets you can leave it blank, but setting it is recommended. {% endhint %} #### 4. Test the Integration After all these steps have been completed, test the integration in PeakCommerce by syncing your catalog. Go to **Commerce → Product Catalog** and click **Sync from Provider**. PeakCommerce reads your Zuora products, rate plans, and charges and brings them into the catalog as **Synced** products — if they appear, the connection is working. (You can also click **Create Product** to build an Internal product or Bundle that references those Zuora charges.) If the sync returns nothing or errors, re-check the Endpoint, REST URL, and Client Id/Secret above, then review the run in **Settings → Catalog Sync History**. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.peakcommerce.com/integrations/billing-and-payments/zuora-integration/zuora-billing-integration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.