Zuora

Zuora

This connector uses the Zuora Billing REST API v1 of one tenant: customer accounts, subscriptions and orders, invoices, payments, refunds and credit memos, the product catalog with rate plans, usage, and three query tools (Object Query lists, ZOQL and Data Query SQL). It can create and update accounts, place orders, renew, suspend and resume subscriptions, record usage, email invoices and create credit memos.

Setup (5 minutes)

1. In Zuora open Settings, Administration, Manage Users, pick (or create) an API user with the permissions the tools need, and under OAuth Clients create a client. Copy the client id and the client secret (shown once).
2. Paste them into ZUORA_CLIENT_ID and ZUORA_CLIENT_SECRET. The connector gets a token from /oauth/token with the client credentials grant and renews it before it expires.
3. Set ZUORA_API_URL to the REST host of your tenant, without a path: https://rest.zuora.com (US Cloud 2), https://rest.na.zuora.com (US Cloud 1), https://rest.eu.zuora.com (EU), https://rest.ap.zuora.com (APAC), or a sandbox: https://rest.apisandbox.zuora.com, https://rest.sandbox.na.zuora.com, https://rest.sandbox.eu.zuora.com, https://rest.test.zuora.com, https://rest.test.eu.zuora.com, https://rest.test.ap.zuora.com. The host is shown in Zuora under your tenant info and in the address of the API docs for your data center.
4. Run zuora_list_products to check the setup.

Workflow

• Accounts: zuora_list_accounts (filter, e.g. ["status.EQ:Active", "balance.GT:0"]), zuora_get_account, zuora_get_account_summary (everything about one customer), zuora_list_account_payment_methods, zuora_create_account, zuora_update_account.
• Subscriptions: zuora_list_subscriptions, zuora_list_account_subscriptions, zuora_get_subscription. Changes go through orders: zuora_preview_order first to show the user the amounts, then zuora_create_order; zuora_list_orders, zuora_get_order. Lifecycle: zuora_renew_subscription, zuora_suspend_subscription, zuora_resume_subscription, zuora_cancel_subscription.
• Invoices: zuora_list_invoices (e.g. ["status.EQ:Posted", "balance.GT:0", "duedate.LT:2026-10-01"] for overdue), zuora_get_invoice, zuora_list_invoice_items, zuora_list_invoice_files (PDF links), zuora_email_invoice.
• Money: zuora_list_payments, zuora_get_payment, zuora_create_payment, zuora_refund_payment, zuora_list_refunds, zuora_get_refund; credit memos with zuora_list_credit_memos, zuora_get_credit_memo, zuora_list_credit_memo_items, zuora_create_credit_memo_from_invoice.
• Catalog: zuora_list_products, zuora_get_product, zuora_list_product_rate_plans, zuora_get_product_rate_plan (the ids go into orders as productRatePlanId).
• Usage: zuora_list_usages, zuora_create_usage.
• Queries: zuora_query and zuora_query_more for ZOQL on one object; zuora_create_data_query, then zuora_get_data_query until queryStatus is completed, for SQL with joins and totals (zuora_list_data_queries shows earlier jobs); zuora_describe_object lists the fields of an object.

Switched off at install: zuora_cancel_subscription, zuora_create_payment and zuora_refund_payment; they move money or cannot be undone, so an admin switches them on when the team needs them.

Before writing: orders, payments, refunds, cancellations and credit memos change what customers are billed. Use zuora_preview_order and show the user the amounts, and wait for a yes. zuora_create_order with processingOptions (runBilling, collectPayment) also invoices and charges the customer.

Reading the answers: most keys (account_key, subscription_key, invoice_key) take either the number (A00000001, A-S00000001, INV00000001) or the 32-character id; filters such as accountId need the id. Amounts are decimal numbers in the currency of the account. Dates are YYYY-MM-DD, timestamps are in the tenant time zone unless they end with Z. v1 answers carry success: true or success: false with reasons: [{code, message}]; Object Query answers carry data.

Paging: Object Query lists (zuora_list_accounts, zuora_list_subscriptions, zuora_list_invoices, zuora_list_usages) return up to page_size records (10 by default, 99 at most) and nextPage; pass it as cursor until it is missing. Other lists take page and page_size and return nextPage as a link while more exist. ZOQL returns up to 2,000 records and done: false with a queryLocator for the rest.

Limits and errors: Zuora limits concurrent requests per tenant and requests per hour per user; 429 means wait and try again. 401 a wrong client id or secret or the wrong host for the tenant; 403 an API user without the permission; 404 a wrong number or id. Errors in v1 answers come with HTTP 200 or 400 and success: false; read reasons. For tenants with Multi-entity, the OAuth client must belong to the entity you want to read.