Zuora actions

The Zuora block reads and writes Zuora billing accounts, subscriptions, invoices and payments. For the plain-language guide, see Zuora.

When to use it

Use it to pull open invoices and payments into a reconciliation or collections workflow, set up a customer account, or record a payment received outside Zuora. There is no Zuora trigger.

Connection

• Provider id: zuora. OAuth client credentials: the connection stores a Client ID, Client Secret and the tenant subdomain (for example rest.na or rest.sandbox.na), which picks the Zuora data center.
• The block can do only what the OAuth client's Zuora user role allows.
• Pin an account with config.connection. Without it, the step uses the company's default Zuora connection.

Actions

Settings

Keys (accountKey, invoiceKey, paymentKey, subscriptionKey) accept an id or a number (account number, invoice number, payment number).

Filters and paging

• listAccounts, listInvoices and listPayments use Zuora Object Query. Each filter entry is field.OPERATOR:value with EQ, NE, LT, GT, SW or IN, for example ["status.EQ:Posted", "balance.GT:0"]; several entries combine with AND. Each sort entry is field.ASC or field.DESC. Pass the nextPage output as cursor for the next page. pageSize goes up to 99.
• listAccountSubscriptions and listInvoiceItems use numbered pages: page from 1 and pageSize up to 40. Their nextPage is a URL.

Write rules

• createAccount and createPayment accept idempotencyKey. Build it from an id that stays the same on a retry, such as the upstream event or record id, plus the invoice id when one event pays several invoices. Do not use the run id: a retried run has a new id.
• createPayment with type Electronic requires effectiveDate (YYYY-MM-DD). External defaults to today.
• createAccount sends billCycleDay 0 (Zuora picks the day) when you leave it empty and create no subscription.
• additionalFields is a JSON object of other Zuora fields, such as {"Region__c": "EMEA"}. A named field wins over the same key there.
• A request is refused when any key, at any depth, names a raw card field: a key ending in cardNumber or securityCode, or a key that is cvv, cvv2, cvc, cvc2 or pan (case and separators ignored). Values are not inspected.

Output

The step output is the Zuora response with success. Object Query lists return data and nextPage. getAccount returns basicInfo, billingAndPayment, metrics and billToContact. getAccountSummary returns basicInfo, billToContact, subscriptions, invoices and payments. Read fields with {{steps.<stepId>.<path>}}, for example {{steps.open_invoices.data}}.

Example

List the account's posted invoices that still carry a balance, then record an external payment. The caller passes invoices as an array such as [{"invoiceId": "8a8...", "amount": 1250}]; a reference that is the whole value keeps the array intact.

{
  "name": "Record a Zuora payment",
  "trigger": { "type": "api" },
  "steps": [
    {
      "id": "open_invoices",
      "type": "action",
      "name": "List open invoices",
      "action": "zuora.listInvoices",
      "config": {
        "filter": ["status.EQ:Posted", "balance.GT:0", "accountId.EQ:{{input.accountId}}"],
        "sort": ["dueDate.ASC"],
        "pageSize": 50
      }
    },
    {
      "id": "record_payment",
      "type": "action",
      "name": "Record the payment",
      "action": "zuora.createPayment",
      "config": {
        "accountId": "{{input.accountId}}",
        "amount": "{{input.amount}}",
        "currency": "USD",
        "type": "External",
        "effectiveDate": "{{input.paymentDate}}",
        "invoices": "{{input.invoices}}",
        "referenceId": "{{input.bankReference}}",
        "idempotencyKey": "payment:{{input.bankReference}}"
      }
    }
  ]
}

Live catalog

• GET /api/v1/blocks/zuora returns the actions and fields.
• GET /api/v1/blocks/zuora/actions/<operation>/examples returns stored examples where they exist.

Errors and limits

• Zuora can answer HTTP 200 with success: false. The step then fails and shows each Zuora reason as message (code).
• A missing required field or a raw card key fails the step before Zuora is called.