Zuora is a leading subscription management & billing solution. Stigg’s native integration with Zuora enables one-way synchronization (Stigg to Zuora) of product catalog (products, plans, add-ons, coupons), customers, subscriptions, and usage. Data does not flow back from Zuora to Stigg.Documentation Index
Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
Use this file to discover all available pages before exploring further.
Entity mapping
By default, Stigg uses the following mapping:- Stigg plan → Zuora product
- Stigg price → Zuora rate plan and charge
| Stigg Entity | Zuora Entity |
|---|---|
| Feature | N/A |
| Product | N/A |
| Plan | Product Rate Plan (“Pro plan”) |
| Add-on | Product Rate Plan (as an add-on) |
| Plan / add-on billing period | Billing period on Product Rate Plan Charge |
| Plan / add-on charge | Product Rate Plan Charge |
| Customer | Account |
| Subscription | Subscription (created via Order) |
Entities that are not synced to Zuora
| Entity | Not synced to Zuora when… |
|---|---|
| Customer | Customer doesn’t have any subscription |
| Customer only has subscriptions to free plans | |
| Customer only has trial subscriptions | |
| Customer only has subscriptions to plans with a custom price | |
| Customer’s billing information is not sent to Stigg | |
| Customer doesn’t have a payment method | |
| Syncing of customers is disabled in the environment | |
| Subscription | Subscription is for a free plan |
| Subscription is for a trial plan | |
| Subscription is for a plan with a custom price | |
| Syncing of subscriptions is disabled in the environment |
These are the default rules. Customers and subscriptions can still be forced to sync in special cases. For example, if a Billing ID is set to link with an existing Zuora record or if metadata with the
ZUORA__ prefix is provided.Syncing customer usage to Zuora
When customers are subscribed to plans with pay-as-you-go pricing, feature usage that’s reported to Stigg is synced to Zuora every hour. When the integration is enabled, it’s possible to manually trigger this sync from the Stigg app by leveraging the “Sync usage to Zuora” action in details screen of the relevant subscription.Setting up the integration
Create an API user in Zuora
In Zuora, under the Settings section click on Administration
- Zuora Platform Role - API User
- Billing Role - Zuora Billing Standard User
- Payments Role - Zuora Payments Standard User
- Finance Role - Zuora Finance Standard User
- Commerce Role - Zuora Commerce Standard User
- Reporting Role - Zuora Reporting Standard User
Create an OAuth client in Zuora
In Zuora, open the user that was created and activated in the previous step. Under the OAuth Clients section, create a new client calledstigg-api.
Map Stigg metadata to Zuora custom fields
In Zuora, under the Settings section click on Billing
You can add up to 10 indexed custom and 40 non-indexed fields in Zuora. Indexed fields are recommended for performance but are not required for the integration to work.
| Zuora entity | Field type | Field label | API name | Length |
|---|---|---|---|---|
| Product | text | stiggEntityUrl | stiggEntityUrl | 255 |
| Account | text | stiggEntityUrl | stiggEntityUrl | 255 |
| Account | text | stiggCustomerId | stiggCustomerId | 255 |
| Subscription | text | stiggEntityUrl | stiggEntityUrl | 255 |
| Subscription | text | stiggCustomerId | stiggCustomerId | 255 |
| Subscription | text | stiggResourceId | stiggResourceId | 255 |
| Order | text | stiggEntityUrl | stiggEntityUrl | 255 |
| Order | text | stiggCustomerId | stiggCustomerId | 255 |
| Order | text | stiggResourceId | stiggResourceId | 255 |
Zuora automatically adds a ‘__c’ suffix to all API names, for example: stiggEntityUrl__c
Metadata synchronization
Stigg metadata set on plans, add-ons, and customers can be synced to corresponding Zuora entities using reserved metadata key prefixes.Custom fields — ZUORA__ prefix
Metadata keys prefixed with ZUORA__ are mapped to custom fields on the corresponding Zuora entity.
| Stigg entity | Zuora entity |
|---|---|
| Plan / Add-on | Product |
| Customer | Account |
__c suffix is appended automatically to form the Zuora custom field name:
ZUORA__SalesRegion → SalesRegion__c on the Zuora Product or Account.
The target custom field must already exist in Zuora before syncing. Custom fields are not created automatically.
Charge-level fields — ZUORA_CHARGE__ prefix
Metadata keys prefixed with ZUORA_CHARGE__ are applied to the Zuora Product Rate Plan Charge that corresponds to the plan or add-on. This prefix supports both standard accounting code fields and custom charge fields.
This prefix applies only to plan and add-on metadata.
Accounting code fields
The following keys map to built-in Zuora charge fields:
| Stigg metadata key | Zuora field |
|---|---|
ZUORA_CHARGE__AccountingCode | AccountingCode |
ZUORA_CHARGE__DeferredRevenueAccountingCode | DeferredRevenueAccountingCode |
ZUORA_CHARGE__RecognizedRevenueAccountingCode | RecognizedRevenueAccountingCode |
ZUORA_CHARGE__<FieldName> key is set as a custom field on the charge (with __c appended), following the same convention as the ZUORA__ prefix.
Skip-update flag — ZUORA__SYNC_SKIP_UPDATE
Setting ZUORA__SYNC_SKIP_UPDATE to true on a plan or add-on prevents Stigg from pushing updates to the corresponding Zuora product during sync. The entity will still be created on first sync, but subsequent changes in Stigg will not overwrite the Zuora product.
This is useful when the Zuora product is managed manually or by another system.
Connect Stigg with Zuora
In the Stigg app, navigate to the Settings > Integrations > Apps section. Select the Zuora integration app. In the opened form, enter the following information:- Zuora tenant - the URL of your Zuora tenant
- Client ID - the ID of the OAuth client that you created in the previous step
- Client secret - the secret of the OAuth client that you created in the previous step
- Integration details — update your tenant credentials or toggle Invoice item settlement to enable item-level payment settlement through Zuora.
- Additional settings — optionally enable the Use Stigg Checkout widget toggle to allow customers to add payment methods via the Stigg Checkout widget. See Integration with Zuora payment form for details.
Indication for synced entities
Entities that are synced from Stigg to Zuora have a clickable “billing ID” property with a Zuora logo next to it and indication of their sync status (successful, failed, will not be synced).
Accessing Zuora entities from Stigg
In the Stigg app, clicking on the link of the “billing ID” property will open the relevant entity in Zuora.
Subscription status handling and retry behavior
Status Mapping
| Zuora Status | Stigg Status |
|---|---|
| Draft | Not handled |
| Pending Activation | Not handled |
| Pending Acceptance | Not handled |
| Active | Active |
| Cancelled | Cancelled |
| Suspended | Not handled |