# Zuora

Connect to Zuora to manage billing, subscriptions, and revenue data.

---

## Overview

[Zuora](https://www.zuora.com) is a subscription management and recurring billing platform that helps businesses automate the entire quote-to-revenue lifecycle. It provides comprehensive solutions for subscription billing, revenue recognition, and customer lifecycle management.

Connecting Fours to your Zuora tenant lets the Fours AI agent read your billing data — accounts, subscriptions, invoices, and payments — from a Fours workflow or chat.

### Org-Level vs User-Level

> **Org-Level**: Supported, using Zuora's OAuth 2.0 client-credentials grant.
>
> **User-Level**: Not applicable. Zuora's REST API offers client credentials and nothing else — there is no three-legged flow an individual Fours user could consent to — so a per-user connection is impossible rather than merely absent. Every Fours user in your organization shares the org connection.

### How the connection works

The OAuth client is created in **your** Zuora tenant. Fours exchanges its client ID and secret for a bearer token and refreshes it for you — nothing in Fours mints or caches Zuora tokens itself. The subdomain you supply builds the host used for *both* the token exchange and every API call, which is why it must be the subdomain alone.

```d2
shape: sequence_diagram
admin: "Your Fours admin"
zuora: "Your Zuora tenant"
suger: "Fours"
agent: "Fours AI agent"
admin -> zuora: "Create an OAuth client under a role-scoped Zuora user"
admin -> suger: "Client ID + Secret, subdomain (e.g. rest)"
suger -> suger: "Build https://{subdomain}.zuora.com\nfor the token exchange AND every API call"
agent -> suger: "Run a Zuora tool"
suger -> zuora: "client_credentials grant"
zuora -> suger: "Bearer token — Fours refreshes it" { style.stroke-dash: 4 }
suger -> zuora: "Read accounts, subscriptions, invoices, payments"
zuora -> agent: "Data — or a hard error; a failed call never reads as an empty result" { style.stroke-dash: 4 }
```

## Create Integration (Org-Level)

### Prerequisites

- A Zuora account.
- Permission to create an OAuth client in your Zuora tenant.
- The Fours **Admin** role — connecting, disconnecting, and running an integration's actions are all admin-only in Fours.

### Authenticate by client credentials

1. Create an OAuth client in your Zuora tenant, under a user with the permissions you want Fours to operate with. Zuora scopes the client to that user's role. Capture the **Client ID** and **Client Secret** — see the [Zuora OAuth documentation](https://developer.zuora.com/api-references/api/overview/#section/Authentication/OAuth-v2.0).
2. In the Fours console, open [Settings → Integrations](https://console.suger.io/settings?tab=integrations) and click **Connect** on **Zuora**.
3. Enter:
   - **Subdomain** — the label between `https://` and `.zuora.com`, for example `rest`. Common values:

       | Environment | Subdomain |
       | --- | --- |
       | US Production | `rest` |
       | US Cloud 1 Production (NA) | `rest.na` |
       | US API Sandbox | `rest.apisandbox` |
       | US Performance Test (PT1) | `rest.pt1` |
       | EU Production | `rest.eu` |
       | EU API Sandbox | `rest.sandbox.eu` |

   - **Client ID** and **Client Secret** — from step 1.
4. Save.

:::warning
Enter the **subdomain only** — not a full URL. Fours builds both the token endpoint and the API base from it as `https://{subdomain}.zuora.com`, so pasting `https://rest.zuora.com` would produce an unusable host. The connect form rejects values containing a scheme or a trailing `.zuora.com`.
:::

### Check the connection

Fours re-checks the stored credential against Zuora rather than trusting a cached token, so a client secret revoked in Zuora is noticed even while the token it issued has not yet expired.

You see the result on the Zuora card in the **Integrations** list. When the stored credential stops working the card says so directly:

> Connected, but this integration's stored credential can no longer be used — agents and workflows cannot reach it. Disconnect and connect it again to restore access.

This is the same check every org integration gets — see [Connection health](/integrations/#connection-health) for what it does and how to read a card that does not show it.

:::warning
**Connected Zuora before this update? Reconnect it to get the AI tools back.** Zuora now connects a different way. An older connection is **not** dead: Fours still reads your Zuora data through it, carried by a temporary compatibility fallback, so billing and revenue data keep flowing. What an older connection does **not** get is the Fours AI agent's Zuora tools — those are unavailable until you reconnect.

Delete the integration and create it again with the steps above. Reconnecting is the only fix; nothing converts an older connection for you, and the compatibility fallback is temporary — plan the reconnect rather than relying on it.
:::

## Fours AI Tools

When Zuora is connected, the Fours AI agent can read your billing data through Fours' built-in tools (6 actions).

> **Org-level**: All tools run under the org OAuth client, so its Zuora role sets the ceiling on what the agent can read.

| Capability | What the agent can do |
|------------|-----------------------|
| **Accounts** | Read one account by ID or account number, and list or search accounts using a Zuora Object Query filter (`get-account`, `list-accounts`) |
| **Subscriptions** | Read a subscription by ID or number, and list the subscriptions on an account (`get-subscription`, `list-subscriptions`) |
| **Invoices** | List the invoices on an account (`list-invoices`) |
| **Payments** | List the payments on an account (`list-payments`) |

:::info
This tool set is read-only — no Zuora record can be created or modified through it. A call Zuora rejects surfaces as an error, never as an empty result, so the agent cannot mistake a failure for "nothing found".
:::

:::tip
Open the integration from **Settings → Integrations** to see the exact tool list for your connection on its **Actions** tab, and to try a call on the **Playground** tab. The Playground pre-fills only the inputs an action *requires* — add optional ones yourself when you need them.
:::

## Edit Integration

Editing is not supported. For security, if you need to rotate credentials or switch tenants, delete the integration and recreate it.

## Delete Integration

To delete an integration, click the 🗑️ button next to its entry in the **Integrations** list. Fours discards the stored credentials with the integration record, and any workflow or agent depending on Zuora tools stops working immediately. Revoke the OAuth client in Zuora too if you want to cut access from that side.