Skip to main content

Zuora

Zuora Integration Guide

Overview

This guide explains how to connect Bridged with Zuora to read subscription, billing, and payment data including customer accounts, subscriptions, invoices, payments, and usage records. The integration supports reading this data for activation, qualification, and nurture playbooks where subscription and billing context are needed.

Zuora is a subscription management and billing platform that handles recurring billing, invoicing, payment processing, and revenue recognition. It provides a comprehensive REST API (v1) that supports all features of Zuora Billing, Payments, Platform, and Finance .

Primary Use Case: Read Subscription & Billing Data

For Bridged's monetization and commercial integrations, the primary use case is reading subscription-related data, including:

Data Type

Use in Bridged

Customer accounts

Personalize outreach based on subscription status

Subscriptions

Identify active/paused/canceled subscribers for qualification

Invoices

Track billing history and payment amounts

Payments

Monitor successful/failed payment events

Usage records

Track consumption-based billing for lead scoring

Prerequisites

Before starting, ensure you have:

  • A Zuora tenant with API access (Production, Developer Sandbox, or API Sandbox)

  • OAuth 2.0 Client Credentials (Client ID and Client Secret)

  • Your Zuora REST API endpoint URL (varies by environment)

  • A dedicated API user account with appropriate permissions

Environment Endpoints

Zuora has different endpoints depending on your environment :

Environment

REST Root URL

API Base URL

US Cloud 1 API Sandbox

https://rest.sandbox.na.zuora.com

https://rest.sandbox.na.zuora.com

US Cloud 1 Central & Dev Sandbox

https://rest.test.zuora.com

https://rest.test.zuora.com

US Cloud 2 API Sandbox

https://rest.apisandbox.zuora.com

https://rest.apisandbox.zuora.com

EU Cloud API Sandbox

https://rest.sandbox.eu.zuora.com

https://rest.sandbox.eu.zuora.com

Production (NA)

https://rest.na.zuora.com

https://rest.na.zuora.com

Production (EU)

https://rest.eu.zuora.com

https://rest.eu.zuora.com

Note: Your API endpoint is determined by your tenant location. The OAuth token endpoint is https://rest.{environment}/oauth/token .

Connection Methods

Method

Best for

Setup complexity

Access Level

OAuth 2.0 Client Credentials (Preferred)

Server-to-server automated access

Medium

Full API access

OAuth 2.0 Authorization Code

User-specific operations

Medium

User-scoped access

Refresh Token

Long-lived access

Medium

Token renewal

Recommendation: Use OAuth 2.0 Client Credentials for automated server-to-server syncs. Zuora recommends OAuth 2.0 for all API interactions .

Step 1: Set Up OAuth 2.0 Credentials

Step 1.1: Create OAuth Client

  1. Log in to your Zuora tenant as an administrator

  2. Navigate to Settings → Administration → OAuth 2.0 Clients

  3. Click Add OAuth 2.0 Client

  4. Enter the following :

Field

Value

Name

Bridged Integration

Grant Type

Client Credentials

Client ID

Auto-generated (save this)

Client Secret

Auto-generated (save this - shown once only)

  1. Click Save

Step 1.2: Assign API Permissions

  1. In the OAuth client settings, assign the following scopes :

    • entity.{entity_id} - Entity access

    • service.genesis.read - Read subscription data

    • service.genesis.write - Write subscription data (if needed)

    • service.usage.read - Read usage records

    • platform.write - Platform access

Step 2: Configure Bridged to Connect to Zuora

  1. Log in to your Bridged dashboard

  2. Navigate to the Integrations section. If you do not see this section, contact support@bridged.media

  3. Click Zuora → Connect Account

  4. Select OAuth 2.0 Client Credentials as your authentication method

  5. Enter the following credentials:

Field

Description

Environment

Select your Zuora environment (Production NA, Production EU, Sandbox, etc.)

Client ID

From your OAuth client

Client Secret

From your OAuth client

API Base URL

Pre-filled based on environment selection

  1. Click Connect

API Request Example

To verify your connection, generate an access token :

bash

curl --request POST \
  --url https://rest.test.zuora.com/oauth/token \
  --header 'Accept: application/json' \
  --header 'Content-type: application/x-www-form-urlencoded' \
  --data client_id=YOUR_CLIENT_ID \
  --data-urlencode client_secret=YOUR_CLIENT_SECRET \
  --data grant_type=client_credentials

Response:

json

{
  "access_token": "6447d349d8854f0d8d5535484b0b811b",
  "token_type": "bearer",
  "expires_in": 3598,
  "scope": "entity.11e643f4-a3ee-8bad-b061-0025904c57d6 service.genesis.read platform.write"
}

Step 3: Configure Webhooks for Real-time Events (Optional)

Zuora supports webhooks (called "Callout Notifications") for real-time event notifications .

Step 3.1: Set Up Callout Notification in Zuora

  1. Log in to your Zuora tenant

  2. Navigate to Settings → Billing → Notifications → Callouts

  3. Click Add Callout or edit an existing callout

  4. Configure :

Field

Value

Active

Checked

Base URL

https://gateway.bridged.media/webhooks/zuora

HTTP Method

POST

Format

JSON

Authentication

OAuth 2.0 or Token (as configured)

Step 3.2: Add Required Parameters

Zuora requires these parameters in the callout configuration :

Parameter

Description

Event.Category

Event category (e.g., Payment, Subscription)

Event.Date

Event timestamp

Step 3.3: Available Callout Events

Event Category

Event Type

Trigger

Payment

Payment created

New payment processed

Payment

Payment failed

Payment failure occurs

Subscription

Subscription created

New subscription started

Subscription

Subscription updated

Plan changes, renewal

Subscription

Subscription canceled

Cancellation occurs

Invoice

Invoice generated

New invoice created

Invoice

Invoice posted

Invoice posted to customer

Usage

Usage processed

Usage record uploaded

Step 4: Reading Data via API

Available REST API Endpoints

Zuora's v1 REST API provides access to the following data types :

Data Type

API Endpoint

Key Parameters

Accounts

/v1/object-query/accounts

pageSize, cursor

Subscriptions

/v1/object-query/subscriptions

pageSize, cursor

Invoices

/v1/object-query/invoices

pageSize, cursor

Payments

/v1/object-query/payments

pageSize, cursor

Usage

/v1/usage

accountId, subscriptionId

Example: List Accounts

bash

curl -L -X GET 'https://rest.test.zuora.com/object-query/accounts?pageSize=1' \
  -H 'Authorization: Bearer {access_token}'

Example: List Subscriptions for an Account

bash

curl -X GET 'https://rest.test.zuora.com/v1/subscriptions?accountKey=ACCOUNT_KEY' \
  -H 'Authorization: Bearer {access_token}'

Example: Retrieve a Usage Record

bash

curl -X GET 'https://rest.zuora.com/v1/usage/USAGE_ID' \
  -H 'Authorization: Bearer {access_token}'

Step 5: Pagination

Zuora uses cursor-based pagination for most list endpoints .

Pagination Parameters

Parameter

Description

pageSize

Max records per page (max 50 for v1 API; default 10)

cursor

Starting position for next page (use next_page from response)

Pagination Example

First request:

bash

curl -X GET 'https://rest.test.zuora.com/object-query/accounts?pageSize=10' \
  -H 'Authorization: Bearer {access_token}'

Response includes:

json

{
  "data": [...],
  "next_page": "W3sib3JkZXJ="
}

Subsequent request:

bash

curl -X GET 'https://rest.test.zuora.com/object-query/accounts?pageSize=10&cursor=W3sib3JkZXJ=' \
  -H 'Authorization: Bearer {access_token}'

Note: The pageSize maximum for Object Query API is 50 . For other v1 API endpoints, maximum is 40 .

Step 6: Configure Sync Settings

Setting

Options

Description

Data objects

Accounts, Subscriptions, Invoices, Payments, Usage

Which billing data to read

Sync frequency

Hourly, Daily, Weekly

How often to refresh data

Sync method

API Direct, Webhooks, Both

Preferred data access method

Subscription status filter

Active, Canceled, Expired, All

Filter by subscription state

Date range

Days to look back

Only sync recent data

Bulk sync limit: Each bulk operation is limited to 50 records per request. Use pagination for larger datasets.

Rate Limiting & Performance

Rate Limits

Zuora enforces rate limits at the tenant level :

Environment

RPM (API)

RPH (API)

RPD (API)

Production

50,000

2.25M

27M

Developer Sandbox

12,500

25,000

50,000

API Sandbox

2,500

5,000

10,000

Concurrent Request Limits

Type

Concurrency Limit

Default

40

High-volume transactions

200

Object Query

80

Response Headers for Rate Limits

Header

Description

ratelimit-limit

Maximum request limit per window

ratelimit-remaining

Remaining requests before limit

ratelimit-reset

Seconds until limit resets

Retry Strategy

When receiving HTTP 429 - Too Many Requests, implement exponential backoff :

  1. Wait 1 second, retry

  2. Wait 2 seconds, retry

  3. Wait 4 seconds, retry

  4. Continue up to maximum retries

Common Use Cases

Playbook

How Subscription Data Is Used

Activation

Read active subscribers to trigger renewal reminders or upsell campaigns via WhatsApp

Qualification Agent

Read subscription tier and payment history to prioritize high-value customers

Nurture & Conversion

Read invoice and payment data for dunning/failed payment follow-up

Example Conversation Powered by Zuora Data

When a customer asks "When does my subscription renew?", Bridged:

  1. Reads customer's active subscription from Zuora API

  2. Retrieves subscription end date or next billing period

  3. Returns renewal date conversationally

Security & Permissions

  • Zuora uses OAuth 2.0 Client Credentials for server-to-server authentication

  • Access tokens are valid for 1 hour (3,598 seconds)

  • Tokens should be automatically refreshed by Bridged

  • All API calls must be made over TLS 1.2+

  • Credentials are encrypted and never stored in plain text

Required OAuth Scopes

Scope

Required for

service.genesis.read

Reading subscription and account data

service.usage.read

Reading usage records

entity.{id}

Entity access (multi-entity tenants)

Troubleshooting

Issue

Likely cause

Solution

Connection fails (401)

Invalid Client ID/Secret

Verify credentials in OAuth client settings

Token generation fails

Wrong grant type

Ensure grant_type=client_credentials

No data returned (403)

Insufficient scopes

Add service.genesis.read scope

Rate limiting (429)

Too many requests

Reduce sync frequency; implement backoff

Pagination fails

pageSize exceeds max

Use pageSize ≤ 50 for Object Query, ≤ 40 for v1 API

Concurrent limit reached

Too many parallel requests

Reduce concurrent connections; respect concurrency headers

Support

For integration support, contact your Bridged account manager or email support@bridged.media.

For Zuora-specific questions: