@datafire/zuora v6.0.0

@datafire/zuora

Client library for API Reference: Billing

Installation and Usage

npm install --save @datafire/zuora

let zuora = require('@datafire/zuora').create();

.then(data => {
  console.log(data);
});

Description

Introduction

Welcome to the reference for the Zuora Billing REST API!

To learn about the common use cases of Zuora Billing REST APIs, check out the API Guides.

In addition to Zuora API Reference; Billing, we also provide API references for other Zuora products:

• API Reference: Collect
• API Reference: Revenue

The Zuora REST API provides a broad set of operations and resources that:

• Enable Web Storefront integration from your website.
• Support self-service subscriber sign-ups and account management.
• Process revenue schedules through custom revenue rule models.
• Enable manipulation of most objects in the Zuora Billing Object Model.

Want to share your opinion on how our API works for you? Tell us how you feel about using our API and what we can do to make it better.

Access to the API

If you have a Zuora tenant, you can access the Zuora REST API via one of the following endpoints:

The Production endpoint provides access to your live user data. Sandbox tenants are a good place to test code without affecting real-world data. If you would like Zuora to provision a Sandbox tenant for you, contact your Zuora representative for assistance.

If you do not have a Zuora tenant, go to https://www.zuora.com/resource/zuora-test-drive and sign up for a Production Test Drive tenant. The tenant comes with seed data, including a sample product catalog.

API Changelog

You can find the Changelog of the API Reference: Billing in the Zuora Community.

Authentication

OAuth v2.0

Zuora recommends that you use OAuth v2.0 to authenticate to the Zuora REST API. Currently, OAuth is not available in every environment. See Zuora Testing Environments for more information.

Zuora recommends you to create a dedicated API user with API write access on a tenant when authenticating via OAuth, and then create an OAuth client for this user. See Create an API User for how to do this. By creating a dedicated API user, you can control permissions of the API user without affecting other non-API users.

If a user is deactivated, all of the user's OAuth clients will be automatically deactivated.

Authenticating via OAuth requires the following steps: 1. Create a Client 2. Generate a Token 3. Make Authenticated Requests

Create a Client

You must first create an OAuth client in the Zuora UI. To do this, you must be an administrator of your Zuora tenant. This is a one-time operation. You will be provided with a Client ID and a Client Secret. Please note this information down, as it will be required for the next step.

Note: The OAuth client will be owned by a Zuora user account. If you want to perform PUT, POST, or DELETE operations using the OAuth client, the owner of the OAuth client must have a Platform role that includes the "API Write Access" permission.

Generate a Token

After creating a client, you must make a call to obtain a bearer token using the Generate an OAuth token operation. This operation requires the following parameters:

• client_id - the Client ID displayed when you created the OAuth client in the previous step
• client_secret - the Client Secret displayed when you created the OAuth client in the previous step
• grant_type - must be set to client_credentials

Note: The Client ID and Client Secret mentioned above were displayed when you created the OAuth Client in the prior step. The Generate an OAuth token response specifies how long the bearer token is valid for. You should reuse the bearer token until it is expired. When the token is expired, call Generate an OAuth token again to generate a new one.

Make Authenticated Requests

To authenticate subsequent API requests, you must provide a valid bearer token in an HTTP header:

Authorization: Bearer {bearer_token}

If you have Zuora Multi-entity enabled, you need to set an additional header to specify the ID of the entity that you want to access. You can use the scope field in the Generate an OAuth token response to determine whether you need to specify an entity ID.

If the scope field contains more than one entity ID, you must specify the ID of the entity that you want to access. For example, if the scope field contains entity.1a2b7a37-3e7d-4cb3-b0e2-883de9e766cc and entity.c92ed977-510c-4c48-9b51-8d5e848671e9, specify one of the following headers:

• Zuora-Entity-Ids: 1a2b7a37-3e7d-4cb3-b0e2-883de9e766cc
• Zuora-Entity-Ids: c92ed977-510c-4c48-9b51-8d5e848671e9

Note: For a limited period of time, Zuora will accept the entityId header as an alternative to the Zuora-Entity-Ids header. If you choose to set the entityId header, you must remove all "-" characters from the entity ID in the scope field.

If the scope field contains a single entity ID, you do not need to specify an entity ID.

Other Supported Authentication Schemes

Zuora continues to support the following additional legacy means of authentication:

• Use username and password. Include authentication with each request in the header:

  • apiAccessKeyId
  • apiSecretAccessKey

  Zuora recommends that you create an API user specifically for making API calls. See Create an API User for more information.

• Use an authorization cookie. The cookie authorizes the user to make calls to the REST API for the duration specified in Administration > Security Policies > Session timeout. The cookie expiration time is reset with this duration after every call to the REST API. To obtain a cookie, call the Connections resource with the following API user information:

  • ID
  • Password

• For CORS-enabled APIs only: Include a 'single-use' token in the request header, which re-authenticates the user with each request. See below for more details.

Entity Id and Entity Name

The entityId and entityName parameters are only used for Zuora Multi-entity. These are the legacy parameters that Zuora will only continue to support for a period of time. Zuora recommends you to use the Zuora-Entity-Ids parameter instead.

The entityId and entityName parameters specify the Id and the name of the entity that you want to access, respectively. Note that you must have permission to access the entity.

You can specify either the entityId or entityName parameter in the authentication to access and view an entity.

• If both entityId and entityName are specified in the authentication, an error occurs.
• If neither entityId nor entityName is specified in the authentication, you will log in to the entity in which your user account is created.

To get the entity Id and entity name, you can use the GET Entities REST call. For more information, see API User Authentication.

Token Authentication for CORS-Enabled APIs

The CORS mechanism enables REST API calls to Zuora to be made directly from your customer's browser, with all credit card and security information transmitted directly to Zuora. This minimizes your PCI compliance burden, allows you to implement advanced validation on your payment forms, and makes your payment forms look just like any other part of your website.

For security reasons, instead of using cookies, an API request via CORS uses tokens for authentication.

The token method of authentication is only designed for use with requests that must originate from your customer's browser; it should not be considered a replacement to the existing cookie authentication mechanism.

See Zuora CORS REST for details on how CORS works and how you can begin to implement customer calls to the Zuora REST APIs. See HMAC Signatures for details on the HMAC method that returns the authentication token.

Requests and Responses

Request IDs

As a general rule, when asked to supply a "key" for an account or subscription (accountKey, account-key, subscriptionKey, subscription-key), you can provide either the actual ID or the number of the entity.

HTTP Request Body

Most of the parameters and data accompanying your requests will be contained in the body of the HTTP request.

The Zuora REST API accepts JSON in the HTTP request body. No other data format (e.g., XML) is supported.

Data Type

(Actions and CRUD operations only) We recommend that you do not specify the decimal values with quotation marks, commas, and spaces. Use characters of +-0-9.eE, for example, 5, 1.9, -8.469, and 7.7e2. Also, Zuora does not convert currencies for decimal values.

Testing a Request

Use a third party client, such as curl, Postman, or Advanced REST Client, to test the Zuora REST API.

You can test the Zuora REST API from the Zuora API Sandbox or Production tenants. If connecting to Production, bear in mind that you are working with your live production data, not sample data or test data.

Testing with Credit Cards

Sooner or later it will probably be necessary to test some transactions that involve credit cards. For suggestions on how to handle this, see Going Live With Your Payment Gateway.

Concurrent Request Limits

Zuora enforces tenant-level concurrent request limits. See Concurrent Request Limits for more information.

Timeout Limit

If a request does not complete within 120 seconds, the request times out and Zuora returns a Gateway Timeout error.

Error Handling

If a request to Zuora Billing REST API with an endpoint starting with /v1 (except Actions and CRUD operations) fails, the response will contain an eight-digit error code with a corresponding error message to indicate the details of the error.

The following code snippet is a sample error response that contains an error code and message pair:

 {
   "success": false,
   "processId": "CBCFED6580B4E076",
   "reasons":  [
     {
      "code": 53100320,
      "message": "'termType' value should be one of: TERMED, EVERGREEN"
     }
    ]
 }

The success field indicates whether the API request has succeeded. The processId field is a Zuora internal ID that you can provide to Zuora Global Support for troubleshooting purposes.

The reasons field contains the actual error code and message pair. The error code begins with 5 or 6 means that you encountered a certain issue that is specific to a REST API resource in Zuora Billing. For example, 53100320 indicates that an invalid value is specified for the termType field of the subscription object.

The error code beginning with 9 usually indicates that an authentication-related issue occurred, and it can also indicate other unexpected errors depending on different cases. For example, 90000011 indicates that an invalid credential is provided in the request header.

When troubleshooting the error, you can divide the error code into two components: REST API resource code and error category code. See the following Zuora error code sample:

Note: Zuora determines resource codes based on the request payload. Therefore, if GET and DELETE requests that do not contain payloads fail, you will get 500000 as the resource code, which indicates an unknown object and an unknown field. The error category code of these requests is valid and follows the rules described in the Error Category Code section. In such case, you can refer to the returned error message to troubleshoot.

REST API Resource Code

The 6-digit resource code indicates the REST API resource, typically a field of a Zuora object, on which the issue occurs. In the preceding example, 531003 refers to the termType field of the subscription object.

The value range for all REST API resource codes is from 500000 to 679999. See Resource Codes in the Knowledge Center for a full list of resource codes.

Error Category Code

The 2-digit error category code identifies the type of error, for example, resource not found or missing required field.

The following table describes all error categories and the corresponding resolution:

Pagination

When retrieving information (using GET methods), the optional pageSize query parameter sets the maximum number of rows to return in a response. The maximum is 40; larger values are treated as 40. If this value is empty or invalid, pageSize typically defaults to 10.

The default value for the maximum number of rows retrieved can be overridden at the method level.

If more rows are available, the response will include a nextPage element, which contains a URL for requesting the next page. If this value is not provided, no more rows are available. No "previous page" element is explicitly provided; to support backward paging, use the previous call.

Array Size

For data items that are not paginated, the REST API supports arrays of up to 300 rows. Thus, for instance, repeated pagination can retrieve thousands of customer accounts, but within any account an array of no more than 300 rate plans is returned.

API Versions

The Zuora REST API are version controlled. Versioning ensures that Zuora REST API changes are backward compatible. Zuora uses a major and minor version nomenclature to manage changes. By specifying a version in a REST request, you can get expected responses regardless of future changes to the API.

Major Version

The major version number of the REST API appears in the REST URL. Currently, Zuora only supports the v1 major version. For example, POST https://rest.zuora.com/v1/subscriptions.

Minor Version

Zuora uses minor versions for the REST API to control small changes. For example, a field in a REST method is deprecated and a new field is used to replace it.

Some fields in the REST methods are supported as of minor versions. If a field is not noted with a minor version, this field is available for all minor versions. If a field is noted with a minor version, this field is in version control. You must specify the supported minor version in the request header to process without an error.

If a field is in version control, it is either with a minimum minor version or a maximum minor version, or both of them. You can only use this field with the minor version between the minimum and the maximum minor versions. For example, the invoiceCollect field in the POST Subscription method is in version control and its maximum minor version is 189.0. You can only use this field with the minor version 189.0 or earlier.

If you specify a version number in the request header that is not supported, Zuora will use the minimum minor version of the REST API. In our REST API documentation, if a field or feature requires a minor version number, we note that in the field description.

You only need to specify the version number when you use the fields require a minor version. To specify the minor version, set the zuora-version parameter to the minor version number in the request header for the request call. For example, the collect field is in 196.0 minor version. If you want to use this field for the POST Subscription method, set the zuora-version parameter to 196.0 in the request header. The zuora-version parameter is case sensitive.

For all the REST API fields, by default, if the minor version is not specified in the request header, Zuora will use the minimum minor version of the REST API to avoid breaking your integration.

Minor Version History

The supported minor versions are not serial. This section documents the changes made to each Zuora REST API minor version.

The following table lists the supported versions and the fields that have a Zuora REST API minor version.

Version 207.0 and Later

The response structure of the Preview Subscription and Update Subscription methods are changed. The following invoice related response fields are moved to the invoice container:

• amount
• amountWithoutTax
• taxAmount
• invoiceItems
• targetDate
• chargeMetrics

Zuora Billing Object Model

The following diagram is a high-level view of how key business objects are related to one another within Zuora Billing.

Click the diagram to open it in a new tab and zoom in. For more information about the different sections of the diagram, see Zuora Billing business object model.

This diagram is intended to provide a conceptual understanding; it does not illustrate a specific way to integrate with Zuora.

The diagram includes the Orders feature and the Invoice Settlement feature. If your organization does not use either of these features, see Zuora Billing business object model prior to Orders and Invoice Settlement for an alternative diagram.

API Names

You can use the Describe object operation to list the fields of each Zuora object that is available in your tenant. When you call the operation, you must specify the API name of the Zuora object.

The following table provides the API name of each Zuora object:

Actions

GET_ChargeMetrics

Retrieves key charge metrics about rate plan charges that have changes in a specified time range.

The purpose of fromTimestamp and toTimestamp is to synchronize charge metrics data incrementally.

zuora.GET_ChargeMetrics({
  "fromTimestamp": "",
  "toTimestamp": ""
}, context)

Input

• input object
  • Zuora-Track-Id string: A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.
  • Zuora-Entity-Ids string: An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.
  • Accept string: Expressed as MIME types that the client is able to understand. Using content negotiation, the server then selects one of the proposals, uses it and informs the client of its choice with the Content-Type response header. The possible response MIME types are application/json-seq compatible with http://jsonlines.org/, and text/csv compatible with RFC 4180. application/json-seq is the default response MIME type. If the Accept header is not sepecified, or set /, the response body is returned in application/json-seq MIME type.
  • fromTimestamp required string: The starting date and time of a time range when changes are made to charge metrics, in yyyy-mm-ddThh:mm:ssZ format. For example, 2020-08-18T09:01:11Z. The timestamp maps to the UpdatedOn timestamp of the to-be-exported object.
  • toTimestamp required string: The end date and time of a time range when changes are made to charge metrics, in yyyy-mm-ddThh:mm:ssZ format. For example, 2020-08-20T09:01:11Z. The timestamp maps to the UpdatedOn timestamp of the to-be-exported object.

Output

• output ChargeMetricsResponse

GET_ChargeMetricsDiscountAllocationDetails

Retrieves discount allocation details rate plan charges that have changes in a specified time range.

The purpose of fromTimestamp and toTimestamp is to synchronize discount allocation details incrementally.

zuora.GET_ChargeMetricsDiscountAllocationDetails({
  "fromTimestamp": "",
  "toTimestamp": ""
}, context)

Input

• input object
  • Zuora-Track-Id string: A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.
  • Zuora-Entity-Ids string: An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.
  • Accept string: Expressed as MIME types that the client is able to understand. Using content negotiation, the server then selects one of the proposals, uses it and informs the client of its choice with the Content-Type response header. The possible response MIME types are application/json-seq compatible with http://jsonlines.org/, and text/csv compatible with RFC 4180. application/json-seq is the default response MIME type. If the Accept header is not sepecified, or set /, the response body is returned in application/json-seq MIME type.
  • fromTimestamp required string: The starting date and time of a time range when changes are made to charge metrics, in yyyy-mm-ddThh:mm:ssZ format. For example, 2020-08-18T09:01:11Z. The timestamp maps to the UpdatedOn timestamp of the to-be-exported object.
  • toTimestamp required string: The end date and time of a time range when changes are made to charge metrics, in yyyy-mm-ddThh:mm:ssZ format. For example, 2020-08-20T09:01:11Z. The timestamp maps to the UpdatedOn timestamp of the to-be-exported object.

Output

• output ChargeMetricsDiscountAllocationDetailResponse

GET_EventTriggers

Query event triggers

zuora.GET_EventTriggers({
  "Authorization": ""
}, context)

Input

• input object
  • Authorization required string: Bearer {token} for a valid OAuth token.
  • Zuora-Entity-Ids string: An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.
  • Zuora-Track-Id string: A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.
  • baseObject string: The Zuora object that trigger condition is defined upon. Should be specified in the pattern: ^A-Z*$
  • eventTypeName string: The event type name. Should be specified in the pattern: ^A-Za-z{1,}\w-*$
  • active string: The status of the event trigger.
  • start integer: The first index of the query result. Default to 0 if absent, and the minimum is 0.
  • limit integer: The maximum number of data records to be returned. Default to 10 if absent.

Output

• output object
  • data array
    • items EventTrigger
  • next string: The link to the next page. No value if it is last page.

POST_EventTrigger

When you create an event trigger, you must specify the base object and define the trigger condition.

Specify the base object

Use baseObject field to specify which object to define a trigger on. You can define an event trigger on any of the following objects:

• Account
• AccountingCode
• AccountingPeriod
• Amendment
• BillingRun
• Contact
• CreditBalanceAdjustment
• CreditMemo
• CreditMemoApplication
• CreditMemoApplicationItem
• CreditMemoItem
• DebitMemo
• DebitMemoItem
• Feature
• Invoice
• InvoiceAdjustment
• InvoiceItem
• InvoiceItemAdjustment
• JournalEntry
• JournalEntryItem
• Order
• OrderAction
• Payment
• PaymentApplication
• PaymentMethod
• PaymentPart
• Product
• ProductFeature
• ProductRatePlan
• ProductRatePlanCharge
• RatePlan
• RatePlanCharge
• Refund
• RefundApplication
• RevenueEvent
• RevenueEventItem
• RevenueSchedule
• RevenueScheduleItem
• Subscription
• SubscriptionProductFeature
• TaxationItem
• Usage

Tenant level base objects and tenant level event triggers

Zuora identifies the following base objects as the tenant level base objects:

• AccountingCode
• AccountingPeriod
• BillingRun
• Feature
• JournalEntry
• JournalEntryItem
• Product
• ProductFeature
• ProductRatePlan
• ProductRatePlanCharge

Event triggers defined on tenant level base objects are tenant level event triggers. Notifications associated with tenant level events are system notifications.

Note: Tenant level event triggers and system notifications are only available in the default profile.

Define the trigger condition

The condition field is a JEXL expression that specifies when to trigger events. The expression can contain fields from the object that the trigger is defined on.

Note: The condition cannot contain fields from data source objects that are joined to the object that the trigger is defined on.

For example, the following condition causes an event to be triggered whenever an invoice is posted with an amount greater than 1000:

changeType == 'UPDATE' && Invoice.Status == 'Posted' && Invoice.Status_old != 'Posted' && Invoice.Amount > 1000

Where:

• changeType is a keyword that specifies the type of change that occurred to the Invoice object. For all objects, the supported values of changeType are INSERT, UPDATE, and DELETE.
• Invoice.Status is the value of the Invoice object's Status field after the change occurred.
• Invoice.Status_old is the value of the Invoice object's Status field before the change occurred.

In the above example, the value of baseObject is Invoice.

Limitations

This event trigger has the following limitations:

• The maximum number of event triggers is 20. If you want to increase the limit, submit a request at Zuora Global Support.

• The INSERT change type is not supported on RatePlan base objects.

• The INSERT change type is not supported on SubscriptionProductFeature base objects.

• The UPDATE change type based on custom fields of base objects is not supported.

zuora.POST_EventTrigger({
  "Authorization": "",
  "body": {
    "baseObject": "",
    "condition": "",
    "eventType": {
      "name": "",
      "displayName": ""
    },
    "active": true
  }
}, context)

Input

• input object
  • Authorization required string: Bearer {token} for a valid OAuth token.
  • Zuora-Entity-Ids string: An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.
  • Zuora-Track-Id string: A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.
  • body required PostEventTriggerRequest

Output

• output EventTrigger

DELETE_EventTrigger

Remove an event trigger

zuora.DELETE_EventTrigger({
  "Authorization": "",
  "id": ""
}, context)

Input

• input object
  • Authorization required string: Bearer {token} for a valid OAuth token.
  • Zuora-Entity-Ids string: An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.
  • Zuora-Track-Id string: A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.
  • id required string

Output

Output schema unknown

GET_EventTrigger

Get an event trigger by ID

zuora.GET_EventTrigger({
  "Authorization": "",
  "id": ""
}, context)

Input

• input object
  • Authorization required string: Bearer {token} for a valid OAuth token.
  • Zuora-Entity-Ids string: An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.
  • Zuora-Track-Id string: A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.
  • id required string

Output

• output EventTrigger

PUT_EventTrigger

Update an event trigger

zuora.PUT_EventTrigger({
  "Authorization": "",
  "id": "",
  "body": {}
}, context)

Input

• input object
  • Authorization required string: Bearer {token} for a valid OAuth token.
  • Zuora-Entity-Ids string: An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.
  • Zuora-Track-Id string: A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.
  • id required string
  • body required PutEventTriggerRequest

Output

• output EventTrigger

GET_Query_Email_Templates

Queries email templates.

zuora.GET_Query_Email_Templates({
  "Authorization": ""
}, context)

Input

• input object
  • Authorization required string: Bearer {token} for a valid OAuth token.
  • Zuora-Track-Id string: A custom identifier for tracing the API call. If you set a value for this header, Zuora returns the same value in the response headers. This header enables you to associate your system process identifiers with Zuora API calls, to assist with troubleshooting in the event of an issue.
  • Zuora-Entity-Ids string: An entity ID. If you have Zuora Multi-entity enabled and the OAuth token is valid for more than one entity, you must use this header to specify which entity to perform the operation in. If the OAuth token is only valid for a single entity, or you do not have Zuora Multi-entity enabled, you do not need to set this header.
  • start integer: The first index of the query result.
  • limit integer: The maximum number of results the q