.png)
Zuora Integration Guide
Connect Zuora subscription, billing, payment, and usage data with enterprise systems through REST APIs, selected events, bulk operations, and Martini workflows.
Zuora integration options at a glance
Zuora’s primary integration method is its REST API, which supports Accounts, Subscriptions, Products, RatePlans, Orders, Invoices, Payments, usage, and related objects. Selected billing, subscription, payment, invoice, and account events can be delivered through callouts and notification frameworks, although event coverage depends on the tenant and feature configuration. Bulk and asynchronous APIs support high-volume processing, while Data Query provides API-based extraction. SOAP remains relevant for legacy operations, and attachment APIs support selected documents. Martini can authenticate with OAuth 2.0, orchestrate calls, process asynchronous jobs, receive notifications, map JSON or XML, and deliver results to enterprise applications, databases, files, or messaging systems.
| Integration point | Supported by Zuora? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Create, update, and retrieve Accounts, Subscriptions, Orders, Invoices, Payments, Products, RatePlans, usage, and related resources. REST is the primary application integration method. | Martini can consume Zuora REST endpoints from workflows, transform JSON responses, expose APIs that orchestrate Zuora operations, and generate reusable integration assets from API definitions. |
| SOAP APIs | Legacy | Support existing billing, subscription, account, and related integrations where a required legacy operation is not available through the selected REST API. | Martini can consume SOAP services, map XML payloads, apply validation, and isolate legacy operations behind reusable workflows or a controlled API. |
| Webhooks / outbound callbacks | Limited | Deliver selected billing, subscription, payment, invoice, and account notifications through callouts and event or notification frameworks. Coverage varies by event and tenant configuration. | Martini can expose an authenticated API endpoint, receive notifications, retrieve the current Zuora object when needed, deduplicate events, and invoke downstream workflows. |
| Bulk / async / batch APIs | Yes | Process selected high-volume operations, usage, billing workloads, and asynchronous extraction jobs without issuing one request per object. | Martini can submit jobs, persist job identifiers, poll with bounded retries, retrieve result pages or files, process partial failures, and resume safely. |
| Data Query and analytics extraction | Yes | Run API-based SQL-like queries and extract operational or analytical data such as Invoices, InvoiceItems, Payments, and Subscriptions. | Martini can schedule queries, monitor completion, retrieve results, transform them to JSON or CSV, and load target databases or data platforms. |
| File / attachment APIs | Limited | Upload, retrieve, or associate documents with selected objects such as Accounts or billing documents. This is not the primary structured synchronization method. | Martini can transfer supported attachments, map object identifiers, validate content metadata, and route files to downstream storage or workflows. |
| Authentication | Yes | Use OAuth 2.0 access tokens, dedicated API users, roles, API profiles, scopes, and tenant-specific production or sandbox endpoints. | Martini can store credentials and tokens in secure environment configuration, configure API authentication, and apply least-privilege access patterns. |
| Database access | No | Zuora does not provide direct customer database access for ordinary integrations. Data Query and export capabilities are API-mediated alternatives. | Martini can consume Zuora extraction APIs and write transformed results to supported SQL databases without assuming access to Zuora’s underlying database. |
How Zuora exposes data and business events
Zuora REST APIs
Zuora REST APIs are the primary standards-based mechanism for working with Accounts, Subscriptions, Products, RatePlans, Orders, Invoices, Payments, usage, and related resources. API versions and tenant feature configuration determine the available object model and operations.
Martini implementation pattern
Martini implementation pattern: a workflow calls the appropriate Zuora REST endpoint, handles authentication and pagination, transforms the response, applies business rules, and writes the result to a target system or returns it through a Martini API.
Implementation sequence
Zuora Events and Callouts
Zuora supports callout notifications and event or notification frameworks for selected billing, subscription, payment, invoice, and account events. Coverage, payloads, and delivery behavior depend on the selected event framework, product features, and tenant configuration.
Martini implementation pattern
Martini implementation pattern: Martini exposes an authenticated REST endpoint, receives the notification, validates its contents, retrieves the current Zuora object when the payload is incomplete, and routes the normalized event to downstream workflows. Scheduled reconciliation supplements unsupported or missed events.
Implementation sequence
Zuora Bulk and Async APIs
Zuora provides bulk and asynchronous mechanisms for selected high-volume operations, usage and billing processing, and extraction workloads. The supported objects and request formats vary by API version and operation.
Martini implementation pattern
Martini implementation pattern: a workflow submits the bulk or asynchronous request, persists the returned job identifier, polls with bounded retries, retrieves result pages or files, and handles partial successes and rejected records.
Implementation sequence
Zuora SOAP APIs
Zuora SOAP APIs remain relevant to legacy billing, subscription, account, and related integrations. REST should generally be evaluated first for new implementations where equivalent functionality is available.
Martini implementation pattern
Martini implementation pattern: Martini consumes the required SOAP operation, maps XML requests and responses, isolates legacy behavior in a reusable workflow, and exposes a stable internal interface to reduce point-to-point coupling.
Implementation sequence
Zuora Data Query
Data Query provides API-based SQL-like extraction for supported Zuora data. It is an extraction service rather than direct access to Zuora’s underlying database and may operate asynchronously.
Martini implementation pattern
Martini implementation pattern: a scheduled workflow submits a query, stores its identifier, polls for completion, retrieves result pages or files, transforms the output, and loads a reporting database or data platform.
Implementation sequence
Common Zuora integration patterns
Pattern 1: Synchronize subscriptions and customers
When to use this pattern
Use this pattern when CRM, ERP, or service applications need current Zuora customer and subscription state. Events can provide timely updates where available, while scheduled REST retrieval and reconciliation cover lifecycle changes that are not exposed through notifications.
Integration direction
Example Mapping
| Zuora Field | Canonical Field | Target Field |
|---|---|---|
| Account.accountNumber | customer.externalId | Account.External_Id__c |
| Account.name | customer.name | Account.Name |
| Subscription.subscriptionNumber | subscription.externalId | Contract.Subscription_Number__c |
| Subscription.status | subscription.status | Contract.Status__c |
Martini implementation pattern
Martini retrieves changed Accounts, Subscriptions, Products, RatePlans, and RatePlanCharges through paginated REST calls or selected notifications. The workflow maps nested subscription structures, validates references, applies idempotent upserts using stable Zuora identifiers, persists a watermark, and routes failed records to retry or reconciliation handling.
Martini capabilities used
- workflows
- API consumption
- data mapping
- business rules
- scheduled execution
- error handling
Pattern 2: Propagate invoice and payment status
When to use this pattern
Use this pattern when finance, ERP, service, or analytics applications need current invoice, payment, refund, or balance status. Notifications provide event-driven updates for selected events, while scheduled reconciliation protects financially significant data against delays or incomplete event coverage.
Integration direction
Example Mapping
| Zuora Field | Canonical Field | Target Field |
|---|---|---|
| Invoice.invoiceNumber | billingDocument.externalId | Invoice.tranId |
| Invoice.balance | billingDocument.openAmount | Invoice.balance |
| Payment.paymentNumber | payment.externalId | CustomerPayment.externalId |
| Payment.status | payment.status | CustomerPayment.status |
Martini implementation pattern
Martini receives a selected Zuora notification, validates and deduplicates it, retrieves the current object when necessary, and maps monetary values without losing precision. The workflow distinguishes transient throttling or transport failures from validation errors, applies bounded retries, and records processing keys for safe replay.
Martini capabilities used
- API exposure
- webhook consumption
- data mapping
- idempotency
- business rules
- retry handling
Pattern 3: Ingest usage for billing
When to use this pattern
Use this pattern when an operational application produces usage that must be submitted to Zuora for usage-based monetization. It is suitable for controlled batch submission where account, subscription, unit, timestamp, and measurement validation is required.
Integration direction
Example Mapping
| Zuora Field | Canonical Field | Target Field |
|---|---|---|
| usage.accountNumber | billingAccount.externalId | Usage.accountKey |
| usage.subscriptionNumber | subscription.externalId | Usage.subscriptionKey |
| usage.quantity | usage.quantity | Usage.quantity |
| usage.timestamp | usage.occurredAt | Usage.effectiveDate |
Martini implementation pattern
Martini receives or retrieves usage, validates account and subscription references, normalizes units and timestamps, groups records into supported batches, and submits them through the applicable Zuora API. Request identifiers and rejected records are persisted so only failed items need reprocessing.
Martini capabilities used
- workflows
- API consumption
- data transformation
- validation
- batch processing
- error handling
Pattern 4: Extract billing data for analytics
When to use this pattern
Use this pattern when a data platform or reporting database needs recurring extracts of Invoices, InvoiceItems, Payments, Subscriptions, usage, or other supported data. Data Query and bulk mechanisms reduce the need for one-request-per-object processing.
Integration direction
Example Mapping
| Zuora Field | Canonical Field | Target Field |
|---|---|---|
| Invoice.invoiceNumber | invoice.number | invoice_number |
| Invoice.amount | invoice.total_amount | total_amount |
| Invoice.updatedDate | invoice.modified_at | modified_at |
| Subscription.status | subscription.status | subscription_status |
Martini implementation pattern
A scheduled Martini workflow submits a Data Query or bulk extraction, persists the asynchronous identifier, polls to completion, retrieves pages or files, and transforms the result into the target schema. It records watermarks, preserves monetary precision, validates row counts, and routes partial failures without discarding successful data.
Martini capabilities used
- scheduled workflows
- API consumption
- asynchronous orchestration
- mapping and transformation
- database or API delivery
- monitoring
Applications commonly integrated with Zuora
Zuora can be integrated with adjacent business applications to coordinate subscription operations, finance, tax, payments, analytics, and service processes. Exact object coverage and direction should be validated for the products and tenant configuration involved.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize customer, commercial, subscription, amendment, invoice, and payment-related information between CRM and billing operations. | Salesforce → Martini → Zuora | Martini can expose or consume REST APIs, map Salesforce customer and commercial data to Zuora Accounts, Subscriptions, Products, and Orders, apply validation and idempotent upsert rules, and route billing status back to Salesforce. |
| NetSuite | Exchange customers, invoices, payments, credit memos, and accounting-related data between subscription billing and ERP processes. | Zuora → Martini → NetSuite | A Martini workflow can consume Zuora REST, bulk, or extraction results, transform financial objects to NetSuite formats, process pagination and asynchronous jobs, and retry or quarantine failed transactions. |
| Avalara | Send subscription charge and invoice context for indirect tax calculation and return tax results to the billing process. | Zuora → Martini → Avalara | Martini can orchestrate tax requests, normalize addresses and charge data, validate returned tax amounts, and pass the result between Zuora and Avalara while preserving monetary precision. |
| Snowflake | Deliver subscription, invoice, usage, payment, and revenue-related data to a cloud data platform for reporting and analytics. | Zuora → Martini → Snowflake | A scheduled Martini workflow can submit Zuora Data Query or bulk jobs, poll for completion, retrieve pages or files, transform the output, and load it into Snowflake through an API or supported database-oriented process. |
| Workday | Align selected customer, finance, accounting, or operational information with subscription billing processes. | Workday → Martini → Zuora | Martini can coordinate Workday and Zuora API calls, map agreed master and financial data models, apply business rules, and maintain separate retry and reconciliation paths for each system. |
| SAP S/4HANA | Synchronize customers, products, orders, invoices, payments, and accounting information with enterprise ERP processes. | SAP S/4HANA → Martini → Zuora | Martini can orchestrate API-led exchanges, transform SAP and Zuora schemas, enforce financial validation, persist business keys, and handle asynchronous or batch processing for larger volumes. |
| ServiceNow | Make subscription status, entitlements, account information, and billing status available to service and customer operations. | Zuora → Martini → ServiceNow | Martini can receive selected Zuora notifications or poll for changes, retrieve current subscription or account state, map it to ServiceNow APIs, and use deduplication and reconciliation for reliable updates. |
| Stripe | Coordinate payment processing or payment-related information where Stripe is used as an adjacent payment service, subject to tenant and gateway configuration. | Zuora → Martini → Stripe | Martini can route payment requests and responses between the systems, validate transaction identifiers and statuses, protect sensitive data, and apply bounded retries only where the operation is safe. |
How to build a Zuora integration in Martini
Objective
Configure Zuora sandbox or production endpoints and authenticate with a least-privilege OAuth client or dedicated API user.
Instructions in Martini
- Select the required Zuora environment and API family.
- Store client secrets, credentials, and tokens in Martini environment configuration.
- Configure OAuth 2.0 where available; use legacy credentials only when required.
- Limit Zuora roles, scopes, and API permissions to the workflow’s operations.
Objective
Select an event-driven, API-led, or scheduled entry point based on Zuora event coverage and synchronization requirements.
Instructions in Martini
- Use a Martini API endpoint for selected Zuora callouts or notifications.
- Use a scheduler for incremental REST, Data Query, or bulk extraction.
- Use an API-triggered workflow when another application initiates billing or usage operations.
- Define reconciliation timing for financially significant objects.
Objective
Call the appropriate Zuora REST, SOAP, bulk, asynchronous, or Data Query mechanism and obtain the complete source data.
Instructions in Martini
- Retrieve related objects when a notification contains only an identifier.
- Handle pagination until the source indicates completion.
- Persist asynchronous job or query identifiers.
- Use bounded polling and backoff for long-running operations.
Objective
Convert Zuora JSON or XML structures into a canonical model and the target application schema.
Instructions in Martini
- Map stable Zuora identifiers such as Account Numbers, Subscription Numbers, Invoice Numbers, and Payment Numbers.
- Normalize lifecycle statuses, timestamps, units, currencies, and monetary precision.
- Separate object-specific mappings for Accounts, Subscriptions, Invoices, Payments, and usage.
- Allow additive fields where possible while validating required fields explicitly.
Objective
Enforce business validation, idempotency, lifecycle rules, and safe processing before writing downstream data.
Instructions in Martini
- Validate account, subscription, product, and payment references.
- Check processed event or business keys before applying updates.
- Distinguish current-state synchronization from lifecycle-history requirements.
- Route invalid or permanently rejected records without retrying them indefinitely.
Objective
Deliver transformed data to enterprise APIs, databases, files, messaging systems, or a controlled Martini API façade.
Instructions in Martini
- Perform idempotent upserts where supported by the target.
- Use bulk or asynchronous target operations for larger volumes where appropriate.
- Record source and target identifiers and processing outcomes.
- Protect sensitive customer, payment, credential, and authorization data.
Common Zuora data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Accounts | Customer billing accounts containing account details, billing settings, payment terms, and financial relationships. | Salesforce, NetSuite, SAP S/4HANA, ServiceNow, data platforms | Martini retrieves or receives account changes, maps stable account identifiers, validates required billing fields, and performs idempotent upserts. |
| Subscriptions | Subscription contracts and lifecycle state, including terms, renewals, cancellations, amendments, and associated rate plans. | Salesforce, ServiceNow, SAP S/4HANA, data warehouses | Martini normalizes lifecycle states, links subscriptions to Accounts and RatePlans, applies incremental synchronization, and preserves business keys. |
| Products | Product catalog items available for sale and association with commercial offerings. | Salesforce, NetSuite, SAP S/4HANA, commerce applications | Martini maps catalog identifiers and attributes, validates catalog dependencies, and routes approved changes to downstream systems. |
| RatePlans | Commercial pricing plans associated with Products and Subscriptions. | Salesforce, ERP platforms, quoting and reporting systems | Martini transforms plan structures, relates them to Products and Subscriptions, and applies controlled catalog-change rules. |
| Invoices | Billing documents containing charges, taxes, adjustments, balances, and payment status. | NetSuite, SAP S/4HANA, Avalara, Snowflake, ServiceNow | Martini retrieves current invoice state, preserves monetary precision, maps invoice lines and statuses, and uses reconciliation for financially significant data. |
| Payments | Payment transactions applied to customer Accounts and Invoices, including status and references. | NetSuite, SAP S/4HANA, Snowflake, ServiceNow, payment services | Martini validates transaction identifiers, prevents duplicate processing, maps statuses, and handles retryable versus permanent failures separately. |
Authentication and security considerations
Authentication and security
Zuora supports OAuth 2.0 access tokens, dedicated API users, roles, API profiles, scopes, and tenant-specific production or sandbox endpoints. Some legacy APIs and integrations may use Basic authentication or username and password credentials.
- Prefer OAuth 2.0 for new integrations where available.
- Use a dedicated integration identity with least-privilege permissions.
- Store client secrets, passwords, and tokens in Martini secure environment configuration.
- Protect Martini endpoints that receive Zuora notifications with authentication and authorization.
- Do not log authorization headers, payment details, or unnecessary customer information.
Operational considerations for Zuora integrations
Reliable Zuora processing
Zuora API limits, pagination, API versions, tenant features, and event coverage can vary. Workflows should use bounded concurrency, exponential backoff, complete pagination, and incremental filters or watermarks where supported.
- Use bulk or asynchronous processing for suitable high-volume workloads.
- Persist job identifiers for Data Query and other long-running operations.
- Use stable business keys and idempotency controls for notifications and create operations.
- Preserve decimal precision for prices, taxes, credits, balances, and payments.
- Test sandbox and production configurations separately and validate schema or catalog changes.
- Use reconciliation for invoices, payments, balances, and events that may be delayed or incomplete.
Why use Martini instead of scripts or point-to-point integrations?
Maintainable integration delivery
Martini separates Zuora connectivity from orchestration, transformation, business rules, and target-system delivery. This is more maintainable than duplicating scripts or building tightly coupled point-to-point integrations.
- Centralize authentication, environment configuration, mappings, and reusable workflow logic.
- Combine APIs, events, schedules, databases, files, and messaging in one integration flow.
- Expose a controlled API façade over Zuora without exposing vendor-specific details to every consumer.
- Apply consistent validation, retry, deduplication, monitoring, and reconciliation patterns.
- Use custom logic when Zuora’s object model or a target system requires additional transformation.
Frequently asked questions
Zuora can be integrated through its REST APIs, selected SOAP operations, outbound callouts and notification frameworks, bulk or asynchronous APIs, Data Query, and selected attachment APIs. REST is generally preferred for new application integrations, while scheduled reconciliation can supplement incomplete event coverage.
Yes. Martini can consume Zuora REST APIs, selected SOAP services, bulk and Data Query endpoints, and receive selected Zuora callouts or notification events through a Martini API. It can orchestrate workflows, transform JSON or XML, apply business rules, and deliver results to enterprise targets.
No. A dedicated Zuora connector is not required. Martini can integrate using Zuora’s native REST APIs, selected SOAP APIs, authentication methods, event notifications, callouts, bulk mechanisms, and Data Query through workflows and APIs.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Zuora. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Zuora, infrastructure, payment providers, tax services, or other third-party systems depending on subscriptions, usage, and deployment model.
Zuora REST APIs should generally be evaluated first for new integrations. Use callouts or event notifications for supported event-driven scenarios, bulk or asynchronous APIs for high-volume work, and Data Query for supported extraction workloads. SOAP remains relevant for existing or legacy operations that require it.
Yes, Martini can expose an authenticated API endpoint to receive Zuora callouts or notification events. Zuora event coverage is selected rather than universal, so the event type, payload, delivery behavior, and tenant configuration should be confirmed. Scheduled REST polling or reconciliation can cover gaps.
Martini can use event notifications, supported modification filters, or scheduled REST and Data Query extraction to identify changes. Workflows map Zuora objects such as Accounts, Subscriptions, Invoices, and Payments to canonical and target models, preserve stable identifiers, apply validation, and store watermarks or processing keys.
Martini workflows can classify throttling, transport, timeout, validation, and business errors; apply bounded retries with backoff to transient failures; and route permanent failures for review. Duplicate notifications can be controlled with event identifiers or stable business keys, while reconciliation workflows verify important billing and payment data. Martini can also expose a controlled REST API façade over Zuora operations.
Related Martini documentation
Workflows
Connect Zuora with your enterprise systems
Use Martini to orchestrate Zuora APIs, selected notifications, asynchronous extraction, and downstream business workflows in a secure, maintainable integration architecture.