Quickstart for Zuora Java SDK

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

Prerequisites

• You must have a working Zuora tenant such as Zuora Sandbox where you can test the Java SDK. If you do not yet have a Zuora tenant, go to Zuora Test Drive and sign up for a test environment.
• The following features are required to be enabled on your 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 Java SDK

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

1. Generate authentication credentials
2. Add Zuora Java client library to your project
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: Add Zuora Java client library to your project

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.

To use Zuora Java SDK, you must use Maven for the build. To learn how to install Maven, see Installing Apache Maven.

Add the following dependency to the dependencies in the pom.xml file of your project:

<dependency>
    <groupId>com.zuora.sdk</groupId>
    <artifactId>zuora-sdk-java</artifactId>
    <version>${version}</version>
</dependency>

Make sure to replace ${version} with the latest Zuora API library version.

Check Zuora Java SDK on Maven Central for more information.

Step 3: Create and initialize a Zuora client instance

Configure a Zuora client instance with your client ID, client Secret, and the environment of your Zuora tenant, then initialize this client.

The following table describes all available Zuora environment enumeration values and their corresponding Base URLs:

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

public class TestClass {
  private final static ZuoraClient zuoraClient = new ZuoraClient(
    "11c6f2c0-d17a-44c5-96c4-37df3bec52a1",
    "RLhzFy+Hn+BrNltqlBzgs1C11nGGIZDH53Xr4fY",
    ZuoraEnv.SBX
  );

  public static void main(String[] args) throws ApiException {
    zuoraClient.initialize();

    // do more things here...
  }
}

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 "Gold Membership". The product is effective from 2022-04-01 till 2032-04-01, and the product SKU is SKU3677. 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 license.

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

1. Create a product

LocalDate productStartDate = LocalDate.of(2022, 4, 1);
LocalDate productEndDate = LocalDate.of(2032, 4, 1);

ProductCreateRequest productRequest = new ProductCreateRequest()
      .name("Gold Membership")
      .startDate(productStartDate)
      .endDate(productEndDate)
      .description("Gold Product")
      .sku("SKU3677");

Product newProduct = zuoraClient.products().createProduct(productRequest);

2. Create a plan

LocalDate planStartDate = LocalDate.of(2022, 6, 20);
LocalDate planEndDate = LocalDate.of(2030, 6, 19);
List<String> activeCurrencies = new ArrayList<String>();
activeCurrencies.add("USD");

PlanCreateRequest planRequest = new PlanCreateRequest()
    .name("Monthly Plan")
    .productId(newProduct.getId())
    .startDate(planStartDate)
    .endDate(planEndDate)
    .description("Monthly plan of the Gold product")
    .activeCurrencies(activeCurrencies);

Plan newPlan = zuoraClient.plans().createPlan(planRequest);

3. Create a recurring per-unit price

Map<String, BigDecimal> unitAmounts = new HashMap<String, BigDecimal>();
unitAmounts.put("USD", new BigDecimal(100.0));

PriceCreateRequest priceRequest = new PriceCreateRequest()
    .unitAmounts(unitAmounts)
    .unitOfMeasure("License")
    .name("Recurring Per Unit Price")
    .priceBaseInterval(PriceBaseIntervalEnum.MONTH)
    .planId(newPlan.getId())
    .description("Recurring per unit price of the monthly plan")
    .recurring(new Recurring()
        .intervalCount(1)
        .timing(TimingEnum.ADVANCE)
        .interval(IntervalEnum.MONTH))
    .quantity(new BigDecimal(1))
    .startEvent(StartEventEnum.CONTRACT_EFFECTIVE);

Price newPrice = zuoraClient.prices().createPrice(priceRequest);

Step 5: Verify the result

After the product, plan, and price are created, you can see the result in the Zuora UI or through the GET API operations for these objects.

For example, you can find the created product by navigating to Products > Product Catalog in the Zuora UI. Alternatively, use the Retrieve a product or List all products operation and pass in plans.prices as the expand[] parameter to verify the results. 

Product productResponse = zuoraClient.products().getProduct(newProduct.getId(), Collections.singletonList("plans.prices"));

System.out.println(productResponse);

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 Java code samples, refer to the Quickstart API tutorials.