Quickstart for Zuora Node SDK

Complete the steps described in this article to get up and running with the Zuora Quickstart API using the official Zuora Node SDK.

Prerequisites

  • You must have a working Zuora tenant such as Zuora Sandbox where you can test the Node SDK. If you do not yet have a Zuora tenant, go to Zuora Test Drive and sign up for a test environment.
  • The Node version in your environment is higher than 6.0.
  • The following features are required to be enabled on your Zuora tenant:
    • Orders . If this feature is enabled in your tenant, you can see Orders under Customers in the left navigation panel in the Zuora UI. To obtain access to this feature, submit a request at Zuora Global Support .
    • Invoice Settlement . If this feature is enabled in your tenant, you can see Credit and Debit Memos under Billing in the left navigation panel in the Zuora UI. To obtain access to this feature, submit a request at Zuora Global Support .

Get started with Node SDK

The high-level steps to start working with Zuora Node SDK include:

  1. Generate authentication credentials
  2. Install Zuora Node client library
  3. Create and initialize a Zuora client instance
  4. Create a product with a plan and a price
  5. Verify the result

Step 1: Generate authentication credentials

Zuora authenticates your API requests using user credentials which can be obtained from your Zuora tenant by anyone in your organization with administrative privileges.

Take the following steps to create authentication credentials:

  1. Create a dedicated user for making API calls. See Create an API user for details. This step must be performed by a Zuora administrator from your organization and the user should be connected to an internal email address.
  2. Create an OAuth client for the user. This step must be performed by a Zuora administrator from your organization.
    1. In Zuora, navigate to Settings > Administration > Manage Users , and click the user name that is created in step 1.
    2. In the New OAuth Client section on the user profile page, enter a client name, and click create . A new window then opens, showing the client ID and client secret.
    3. Note down the client ID and client secret. You will need them in later steps. This is the only time you can see the client secret.

Step 2: Install Zuora Node client library

The server-side Zuora client libraries allow you to interact with Zuora APIs from your code. The libraries provide helpful methods for interacting with Zuora resources, such as your customer accounts, products, and subscriptions.

Zuora's Node client library distribution is available on npm.

In your Node project folder, run the following command:

Copy
Copied
npm i @zuora-sdk/node-js

Step 3: Create and initialize a Zuora client instance

Create an example file in the root directory of your Node project. For example, createProduct.js.

Configure a Zuora client instance with your client ID, client Secret, and the base URL of your Zuora tenant, then initialize this client. The full list of enum value for each base URL is defined in index.js.

The following code sample declares the credentials and the environment of the zuoraClient instance, then initializes this instance:

Copy
Copied
const {ZuoraClient} = require("@zuora-sdk/node-js");

(async () => {
  try {
    const zuoraClient = new ZuoraClient({
      clientId:'11c6f2c0-d17a-44c5-96c4-37df3bec96f7',
      clientSecret:'RLhzFy+Hn+BrNltqlBzgs1C11nGGIZDH53Xfr4Y',
      env:'SBX',
    });

    await zuoraClient.initialize();

    //   do more things here…
    
  } catch (error) {
    console.log(error);
  }
})();

Step 4: Create a product with a plan and a price

After you have created and initialized your Zuora client instance, you can start sending your first request.

Basic concepts

Before you proceed with this step, you should understand the differences among Products, Plans, and Prices.

  • Products describe the goods or services you offer to your customers. Each product has a unique ID and SKU.
  • Plans are collections of prices. While products help you track inventory or provisioning, plans and prices help you track payment terms.
  • Prices determine how you charge your customers for the product they subscribe to.

Code examples

You offer a subscription-based software product called "Beverage Delivery Service". The product is effective from 2022-04-01 till 2032-04-01, and the product SKU is SKU1234. It contains a monthly plan which is effective from 2022-06-20 till 2030-6-19. The active currency of this plan is USD. The price included in this plan is a per-unit price, which charges the subscribers $100/month for each bottle.

The following code sample demonstrates how to create the product, plan, and the corresponding price:

  1. Create a product
Copy
Copied
const productRequest = {
    name: 'Beverage Delivery Service',
    sku: 'SKU1234',
    description: 'Beverage Delivery Service',
    start_date: '2022-04-01',
    end_date: '2032-04-01',
};

const newProduct = await zuoraClient.products.createProduct(productRequest);
console.log(newProduct);
  1. Create a plan
Copy
Copied
const planRequest = {
    name: 'Monthly Plan',
    product_id: newProduct.id,
    description: 'Beverage Delivery Service - Monthly Plan',
    start_date: '2022-06-20',
    end_date: '2031-06-19',
    active_currencies: ['USD', 'EUR'],
};

const newPlan = await zuoraClient.plans.createPlan(planRequest);
console.log(newPlan);
  1. Create a recurring per-unit price
Copy
Copied
const priceRequest = {
  name: 'Recurring Per Unit Price',
  unit_of_measure: 'Each',
  unit_amounts: {
    USD: 1.99
  },
  recurring: {
    interval: 'month',
    interval_count: 1,
    timing: 'in_advance',
  },
  quantity: 1,
  plan_id: newPlan.id,
  description: 'Reccuring per unit price of the monthly plan', 
  start_event: 'contract_effective', 
  price_base_interval: 'month',
};

const newPrice = await zuoraClient.prices.createPrice(priceRequest);
console.log(newPrice);

Then run the following command in the terminal:

Copy
Copied
node createProduct.js

Step 5: Verify the result

If the product, plan, and price are succesfully created, you can get the full data of the created objects in the response.

Copy
Copied
Product {
  name: 'Beverage Delivery Service',
  id: '8ad08e01841cf4fa01841e0f49dc0bdb',
  updated_by_id: '8ad09bce80507dab0180688bdabc20cb',
  updated_time: 2022-10-28T10:07:09.000Z,
  created_by_id: '8ad09bce80507dab0180688bdabc20cb',
  created_time: 2022-10-28T10:07:09.000Z,
  start_date: 2022-04-01T00:00:00.000Z,
  end_date: 2032-04-01T00:00:00.000Z,
  sku: 'SKU-00011798',
  description: 'Beverage Delivery Service',
  active: true
}
Plan {
  id: '8ad0887e841cf4e901841e0f52432c4a',
  updated_by_id: '8ad09bce80507dab0180688bdabc20cb',
  updated_time: 2022-10-28T10:07:11.000Z,
  created_by_id: '8ad09bce80507dab0180688bdabc20cb',
  created_time: 2022-10-28T10:07:11.000Z,
  start_date: 2022-06-20T00:00:00.000Z,
  end_date: 2031-06-19T00:00:00.000Z,
  name: 'Monthly Plan',
  description: 'Beverage Delivery Service - Monthly Plan',
  product_id: '8ad08e01841cf4fa01841e0f49dc0bdb',
  active: true
}
Price {
  id: '8ad08aef841cf50301841e0f5a0c5d53',
  charge_type: 'recurring',
  charge_model: 'per_unit',
  updated_by_id: '8ad09bce80507dab0180688bdabc20cb',
  updated_time: 2022-10-28T10:07:13.000Z,
  created_by_id: '8ad09bce80507dab0180688bdabc20cb',
  created_time: 2022-10-28T10:07:13.000Z,
  name: 'Recurring Per Unit Price',
  description: 'Reccuring per unit price of the monthly plan',
  recurring: Recurring {
    recurring_on: 'subscription_item_start_day',
    on: 'subscription_item_start_day',
    usage: false,
    interval: 'month',
    interval_count: 1,
    alignment_behavior: 'none',
    timing: 'in_advance',
    duration_interval: 'subscription_term'
  },
  start_event: 'contract_effective',
  tax_code: '',
  tax_inclusive: false,
  unit_of_measure: 'Each',
  quantity: 1,
  unit_amounts: { EUR: 0, USD: 1.99 },
  price_base_interval: 'month',
  accounting_code: 'Service Revenue',
  plan_id: '8ad0887e841cf4e901841e0f52432c4a'
}

Alternatively, you can see the result in the Zuora UI for these objects. For example, you can find the created product by navigating to Products > Product Catalog in the Zuora UI. The plans and prices can be found in the product details.

What to do next

You can then proceed to create a subscription and an account. See Sign up new subscribers for instructions.

For other use case documentation and Node code samples, refer to the Quickstart API tutorials.