> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Zuora

> Sync business-critical data from your data warehouse to Zuora with Hightouch

## Setup

After selecting Zuora from our Destinations catalog, you will be prompted to enter your Zuora Base URL, Client ID, and Client Secret.

Use [this table](https://www.zuora.com/developer/api-reference/#section/Introduction/Access-to-the-API) from Zuora to select the correct Zuora URL, and follow
[these steps](https://knowledgecenter.zuora.com/Billing/Tenant_Management/A_Administrator_Settings/Manage_Users?_gl=1%2Ap9mz1o%2A_ga%2AMzI5ODc0MjYxLjE2NDY3NjQxMDI.%2A_ga_MY8CQ650DH%2AMTY1NDA0MTU1MC40My4xLjE2NTQwNDE2MTIuMA..&_ga=2.23071486.552820277.1653943857-329874261.1646764102#Create_an_OAuth_Client_for_a_User)
to create an OAuth Client in Zuora that will provide you with the required Client ID and Secret.

## Syncing

Hightouch supports syncing to the following Zuora objects:

* `Accounts`
* `Subscriptions`
* `Usage`

### Sync modes

Here are the possible modes for how to alter Outreach objects:

* **Upsert**: pushes new objects to Zuora and updates fields that change in your warehouse.
  * Supported for `Accounts` and `Subscriptions`.
* **Update**: updates particular fields on existing objects in Zuora. It doesn't add new objects.
  * Supported for `Accounts`, `Subscriptions`, and `Usage`.
* **Insert**: adds new objects in Zuora.
  * Supported for `Usage`.

### Record matching

Records can be matched from your source to your Zuora workspace by the given fields in the dropdown.

The following are supported record ID's for each object:

* **`Accounts`**: `Account Number`, `Account ID`
* **`Subscription`**: `Subscription Number`, `Subscription ID`
* **`Usage`**: `Usage Record ID`

![](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-zuora-record-id-match.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=81662763d6159130f6977135b4acc436)

> [!WARNING]
>
> A record ID is required when performing `Upsert` or `Update` actions, but not
> `Insert`.

### Field mapping

You can sync columns from your source to Zuora's object properties, including
custom fields.

#### Required fields

Each object / action pair will have their own required properties to be mapped. These required properties will be in their own mapping section during sync configuration. Be sure to scroll down to our [Zuora Object Notes](#object-notes) to see which fields are required, and their respective data types.

![](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-zuora-required-mappings.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=48948451a188421e28fa1b755773304f)

#### Optional and custom fields

Any optional built-in fields or custom fields sent to Zuora will be mapped in the custom mappings section of sync configuration. Scroll down to our [Zuora Object Notes](#object-notes) to see Zuora's optional built-in fields, and their respective data types.

![](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-zuora-custom-mappings.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=831819e64f7566915477ad91752bbb8a)

#### Helpful tip:

Use our advanced mapper to fill in static values for numbers or string values that may be consistent across your sync, that may not have a column in your data warehouse. See the example below.

![](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-zuora-advanced-mapper.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=0a8754dc91754b1ea4eac610cc652157)

### Zuora object notes

#### Accounts

The following fields can be used for `Accounts` for each respective action.

> **Upsert**
>
> | Field Name | Notes | Required |
> | - | - | - |
> | accountNumber | string | |
> | applyCredit | boolean | |
> | applyCreditBalance | boolean | |
> | autoPay | boolean | |
> | batch | string | |
> | billCycleDay | integer | yes |
> | billToContact.firstName | string | yes |
> | billToContact.lastName | string | yes |
> | collect | boolean | |
> | communicationProfileId | string | |
> | creditMemoReasonCode | string | |
> | creditMemoTemplateId | string | |
> | crmId | string | |
> | currency | string | yes |
> | debitMemoTemplateId | string | |
> | documentDate | string | |
> | invoice | boolean | |
> | invoiceCollect | boolean | |
> | invoiceTargetDate | string | |
> | invoiceTemplateId | string | |
> | name | string | yes |
> | notes | string | |
> | parentId | string | |
> | paymentGateway | string | |
> | paymentTerm | string | |
> | runBilling | boolean | |
> | salesRep | string | |
> | sequenceSetId | string | |
> | soldToSameAsBillTo | boolean | |
> | tagging | string | |
> | targetDate | string | |
> | Class\_\_NS | string | |
> | CustomerType\_\_NS | string | |
> | Department\_\_NS | string | |
> | IntegrationId\_\_NS | string | |
> | IntegrationStatus\_\_NS | string | |
> | Location\_\_N | string | |
> | Subsidiary\_\_NS | string | |
> | SyncDate\_\_NS | string | |
> | SynctoNetSuite\_\_NS | string | |

> **Update**
>
> | Field Name | Notes |
> | - | - |
> | autoPay | boolean |
> | batch | string |
> | billCycleDay | integer |
> | billToContact | Contact |
> | communicationProfileId | string |
> | creditMemoTemplateId | string |
> | crmId | string |
> | debitMemoTemplateId | string |
> | defaultPaymentMethodId | string |
> | invoiceDeliveryPrefsEmail | boolean |
> | invoiceDeliveryPrefsPrint | boolean |
> | invoiceTemplateId | string |
> | name | string |
> | notes | string |
> | parentId | string |
> | paymentGateway | string |
> | paymentTerm | string |
> | salesRep | string |
> | sequenceSetId | string |
> | soldToContact | Contact |
> | tagging | object |
> | Class\_\_NS | string |
> | CustomerType\_\_NS | string |
> | Department\_\_NS | string |
> | IntegrationId\_\_NS | string |
> | IntegrationStatus\_\_NS | string |
> | Location\_\_NS | string |
> | Subsidiary\_\_NS | string |
> | SyncDate\_\_NS | string |
> | SynctoNetSuite\_\_NS | string |

Notes:

* By default, `autoPay` is set to `false` for inserted `Accounts`, unless it's defined in the mappings for your sync.
  * If you would like to set `autoPay` to true, you must include either a `paymentMethod`, `creditCard`, or `hmpCreditCardPaymentMethodId` in your mappings.
* If either the `workEmail` or `personalEmail` fields are included in mappings, the account's email delivery preference is automatically set to `true`.
* To see more information on any respective field, view the Zuora API docs for [Creating an account](https://www.zuora.com/developer/api-reference/#operation/POST_Account) or [Updating an account](https://www.zuora.com/developer/api-reference/#operation/PUT_Account) via the API.

***

#### Subscriptions

The following fields can be used for `Subscriptions` for each respective action.

> **Upsert**
>
> | Field Name | Notes | Required |
> | - | - | - |
> | accountKey | string | yes |
> | applyCredit | boolean | |
> | applyCreditBalance | boolean | |
> | autoRenew | boolean | |
> | collect | boolean | |
> | contractEffectiveDate | string | yes |
> | creditMemoReasonCode | string | |
> | customerAcceptanceDate | string | |
> | documentDate | string | |
> | externallyManagedBy | string | |
> | gatewayId | string | |
> | initialTerm | integer | |
> | initialTermPeriodType | string | |
> | invoice | boolean | |
> | invoiceCollect | boolean | |
> | invoiceOwnerAccountKey | string | |
> | invoiceSeparately | boolean | |
> | invoiceTargetDate | string | |
> | notes | string | |
> | paymentMethodId | string | |
> | renewalSetting | string | |
> | renewalTerm | integer | yes |
> | renewalTermPeriodType | string | |
> | runBilling | boolean | |
> | serviceActivationDate | string | |
> | subscriptionNumber | string | |
> | subscribetoRatePlans.productRatePlanId | string | yes |
> | targetDate | string | |
> | termStartDate | string | |
> | termType | string | yes |
> | CpqBundleJsonId\*\*QT | string | |
> | OpportunityCloseDate\*\*QT | string | |
> | OpportunityName\*\*QT | string | |
> | QuoteBusinessType\*\*QT | string | |
> | QuoteNumber\*\*QT | string | |
> | QuoteType\*\*QT | string | |
> | IntegrationId\*\*NS | string | |
> | IntegrationStatus\*\*NS | string | |
> | Project\*\*NS | string | |
> | SalesOrder\*\*NS | string | |
> | SyncDate\_\_NS | string | |

> **Update**
>
> | Field Name | Notes |
> | - | - |
> | add | Array of objects |
> | applicationOrder | Array of strings |
> | applyCredit | boolean |
> | applyCreditBalance | boolean |
> | autoRenew | boolean |
> | clearingExistingBillToContactId | boolean |
> | clearingExistingPaymentTerm | boolean |
> | collect | boolean |
> | creditMemoReasonCode | string |
> | currentTerm | integer |
> | currentTermPeriodType | string |
> | documentDate | string |
> | externallyManagedBy | string |
> | includeExistingDraftDocItems | boolean |
> | includeExistingDraftInvoiceItems | boolean |
> | invoice | boolean |
> | invoiceCollect | boolean |
> | invoiceSeparately | boolean |
> | invoiceTargetDate | string |
> | notes | string |
> | preview | boolean |
> | previewType | string |
> | renewalSetting | string |
> | renewalTerm | integer |
> | renewalTermPeriodType | string |
> | runBilling | boolean |
> | targetDate | string |
> | termStartDate | string |
> | termType | string |
> | CpqBundleJsonId\_\_QT | string |
> | OpportunityCloseDate\_\_QT | string |
> | OpportunityName\_\_QT | string |
> | QuoteBusinessType\_\_QT | string |
> | QuoteNumber\_\_QT | string |
> | QuoteType\_\_QT | string |
> | IntegrationId\_\_NS | string |
> | IntegrationStatus\_\_NS | string |
> | Project\_\_NS | string |
> | SalesOrder\_\_NS | string |
> | SyncDate\_\_NS | string |

Notes:

* Only the fields to be changed should be specified. If an empty field is submitted with this operation, the corresponding field in the account is emptied.
* To see more information on any respective field, view the Zuora API docs for [Creating a subscription](https://www.zuora.com/developer/api-reference/#operation/POST_Subscription) or [Updating a subscription](https://www.zuora.com/developer/api-reference/#operation/PUT_Subscription) via the API.

***

#### Usage

The following fields can be used for `Usage` for each respective action.

> **Insert**
>
> | Field Name | Type | Required |
> | - | - | - |
> | AccountId | string | |
> | AccountNumber | string | |
> | ChargeId | string | |
> | ChargeNumber | string | |
> | Description | string | |
> | EndDateTime | string \<date-time> | |
> | Quantity | double | yes |
> | StartDateTime | string \<date-time> | yes |
> | SubmissionDateTime | string \<date-time> | |
> | SubscriptionId | string | |
> | SubscriptionNumber | string | |
> | UOM | string | yes |

> **Update**
>
> | Field Name | Notes |
> | - | - |
> | EndDateTime | string \<date-time> |
> | Quantity | double |
> | RbeStatus | string |
> | StartDateTime | string \<date-time> |
> | SubmissionDateTime | string \<date-time> |
> | UOM | string |

Notes

* Any field with a type of `string <date-time>` must be in the format `"YYYY-MM-DDTHH:mm:ss"`.
* To see more information on any respective field, view the Zuora API docs for [Creating a usage record](https://www.zuora.com/developer/api-reference/#operation/Object_POSTUsage) or [Updating a usage record](https://www.zuora.com/developer/api-reference/#operation/Object_PUTUsage) via the API.

## Tips and troubleshooting

To see the exact API requests and responses from each sync run, use the [live debugger](https://docs.hightouch.com/syncs/debugger.md). To get notified by Slack, PagerDuty, SMS, or email when a sync fails, set up [sync alerts](https://docs.hightouch.com/syncs/alerting.md). If you run into an issue this page doesn't cover, [contact support](#pylon-chat).