Skip to main content

Make asynchronous requests

Zuora

Make asynchronous requests

This article explains the benefits of the asynchronous API, and guides you on making asynchronous requests and using callout notifications to track the success or failure of these requests.

Advantages of asynchronous API

Most API endpoints documented in the Zuora Billing API Reference process requests synchronously. In high-throughput scenarios, your requests to these endpoints are usually rate limited. 

One strategy for avoiding rate limits is to make these requests asynchronously, and Zuora provides this option to you.

Making asynchronous requests allows you to scale your applications more efficiently by leveraging the infrastructure of Zuora to enqueue and execute requests without blocking. With built-in retry semantics, these requests are much less likely to fail for non-deterministic reasons, even in extreme high-throughput scenarios. Meanwhile, when sending a request to one of these asynchronous endpoints, you can receive a response in less than 150 milliseconds, and these calls are unlikely to trigger rate limit errors. 

You can make asynchronous requests to the POST, PUT, and DELETE operations (except Actions) for all resources documented in the Zuora Billing API Reference.

Note: This asynchronous option is in addition to the previously introduced endpoints that support asynchronous request processing. You should continue to use the following operations:

Work with asynchronous API

Prerequisites

  • Ensure that you are familiar with corresponding synchronous API operations documented in the Zuora Billing API Reference, and the Events and notifications feature of Zuora. 
  • Ensure that you have your system used to receive callouts in place. You need to specify a URL that uses the HTTP Secure (https://) protocol when setting up notifications.

Procedure

Take the following steps to work with the asynchronous API:

  1. Set up notifications for asynchronous requests
  2. Make asynchronous requests

Set up notifications

Before making asynchronous requests, you should create callout notifications based on the following custom events through the Zuora UI or REST API:

  • Async Request Succeeded
  • Async Request Failed

With these notifications set up, your system will receive a callout when an asynchronous request succeeds or fails.

Set up notifications through Zuora UI

To create callout notifications through the Zuora UI:

  1. Navigate to Settings > Billing, Settings > Finance, or Settings > Payments.
  2. Click Setup Profiles, Notifications and Email Templates
  3. Click add new notifications.
  4. Configure the new notification. Note that the following list only describes the required steps and does not include the configuration for optional fields. For more detailed information, see Configure callout notifications.
    1. Select Async Request Succeeded (custom event) from the Related Event dropdown list.
    2. Specify a name for the callout notification in the Name field.
    3. Select the Active check box.
    4. In the Delivery Options section, select the Callout check box.
    5. Enter the path to the receiver service of the callout in the Base URL field. You must specify a URL using the HTTP Secure (https://) protocol. Do not specify a port when entering the URL. Zuora does not support custom ports.
    6. Select POST from the Http Method dropdown list.
  5. Click add new notification to save your configuration.
  6. Repeat Step 3 to Step 5 to create the notification for Async Request Failed custom event. Note that in Step 4.a, you should select Async Request Failed (custom event)
Set up notifications through API

To create callout notifications through the API, use the Create a notification definition operation, and specify the following required fields and other conditional or optional fields as needed:

  • calloutBaseurl
  • eventTypeName
  • httpMethod
  • name
  • requiredAuth

The following code snippet is a sample request payload to create a callout notification definition:

{
  "callout": {
    "active": true,
    "calloutAuth": {
      "domain": "example_domain",
      "password": "example_password",
      "preemptive": true,
      "username": "example_user"
      },
    "calloutBaseurl": "https://www.example.com/callout/123456",
    "calloutRetry": true,
    "eventTypeName": "Async Request Succeeded",
    "httpMethod": "POST",
    "name": "Callout for Async Request Succeeded",
    "requiredAuth": true
  },
  "calloutActive": true,
  "communicationProfileId": "6e569e1e05f040eda51a927b140c0ac5",
  "description": "Notification sent out when an async request succeeds",
  "eventTypeName": "Async Request Succeeded"
}

Make asynchronous requests

The POST, PUT, and DELETE operations (except Actions) for all resources documented in the Zuora Billing API Reference support asynchronous request processing.

By design, asynchronous requests differ from their synchronous counterparts in endpoints, and the HTTP status response codes and response body they return. ​​The header parameters and request body schema for asynchronous API operations are the same as their synchronous counterparts. 

  • The endpoints for asynchronous API operations contain /async in the path after /v1. See the following table for examples:
API operation Existing synchronous endpoint Asynchronous endpoint
Create an account /v1/accounts /v1/async/accounts
CRUD: Create an account /v1/object/account /v1/async/object/account
  • Unlike the 200 OK response for synchronous requests, Zuora returns a 202 Accepted response for all asynchronous requests, and the response body contains only a request ID.

Results

With callout notification definitions set up and asynchronous requests sent, Zuora sends a callout to your system once an asynchronous request succeeds or fails.

This section showcases the callout payload for the Async Request Success event and Async Request Failure event respectively.

Callout payload for Async Request Succeeded

On successful completion, an Async Request Succeeded callout notification is triggered. The following code snippet is an example of the triggered callout for Async Request Succeeded:

{
    "createTime": "2021-10-03T10:33:12Z",
    "completeTime": "2021-10-03T10:34:22Z",
    "request": {
        "id": "<request-id>",
        "method": "<request-method>",
        "url": "<request-url>"
    }
}

Callout payload for Async Request Failed

On failure, an Async Request Failed callout notification is triggered. The following code snippet is an example of the triggered callout for Async Request Failed:

{
    "createTime": "2021-10-03T10:33:12Z",
    "completeTime": "2021-10-03T10:34:22Z",
    "request": {
        "id": "<request-id>",
        "method": "<request-method>",
        "url": "<request-url>"
    },
    "state": "failed",
    "reasons": [{
       "code": "<error-code>",
       "message": "<error-message>"
    }],
    "processId": "<process-id>"
}