Happy Business Starts Here

Home : developer : Tutorials

REST API USE CASES

OVERVIEW

Now that you have completed the REST API Quick Start tutorial and have become familiar with the Zuora REST API, it’s time to explore more advanced use cases. In this guide, you will find sample scenarios of the more complex tasks you will likely perform when running your subscription business.

Each use case below contains the REST request and, where relevant, a sample JSON request payload.In the sample requests, replace the variables, e.g. $Account-Id, with the appropriate values you retrieved in preceding exercises. It’ll be up to you to implement them using the language of your choice. Unlike Quick Start guide, this tutorial does not use any specific language to illustrate the use cases.

It’ll be up to you to implement them using the language of your choice. Unlike Quick Start guide, this tutorial does not use any specific language to illustrate the use cases.

Refer to Zuora REST API Reference for detail information about specific REST requests and parameters.

It is recommended that you use the same Test Drive tenant that you used in Quick Start for all the exercise to work.

CONNECT AND AUTHENTICATE

To authenticate and gain access to the Zuora REST API endpoints, you have the following options:

  • Pass the username and password with each request
  • Pass a valid Zuora session cookie with each request

Authenticate with Username and Password

You saw this method in the Quick Start. Just include the user name and the user password in all your requests to authenticate to the REST endpoints. Your request header will include the user id and password as shown below.

Request header

"apiAccessKeyId: $Your-Zuora-Id" "apiSecretAccessKey: $Your-Zuora-Password"

Although easy to get started with, this is not the most efficient method to authenticate with the REST API. See the next section about authenticating with a session token.

Authenticate with Session Cookie

Set the Zuora session cookie in the header of all your requests to authenticate and submit REST requests.

Use the following call to get a valid Zuora session cookie.

Request

POST https://rest.apisandbox.zuora.com/v1/connections

Request header

"apiAccessKeyId: $Your-Zuora-Id" "apiSecretAccessKey: $Your-Zuora-Password"

Response cookie

Retrieve the ZSession cookie ($ZSession-Cookie) returned from the successful call.

Now, include the session cookie ($ZSession-Cookie) in the header of your subsequent requests as shown below.

Request header

"Cookie: ZSession=$ZSession-Cookie"

Note that the session cookie may expire after a certain time. Refer to the Security Policies in your tenant to find out what value the Session Timeout has been configured to.

CREATE A NEW PRODUCT AND PRICING

In this scenario, you will create a product, a product rate plan, a charge, and a tier in the Product Catalog that can be used when subsequently creating subscriptions.

Creating a product in the Zuora catalog consists of the following steps:

  1. Create a product
  2. Create a product rate plan for the product
  3. Create charges and one or more tier for the product rate plan

Create a Product

First, you will create a product.

The required fields to create a product are:

  • Name
  • Effective Start Date
  • Effective End Date

Use the following request to create a product.

Request

POST https://rest.apisandbox.zuora.com/v1/object/product

JSON request body

{
  "EffectiveEndDate": "2017-10-01",
  "EffectiveStartDate": "2016-10-01",
  "Name": "The Soap Club"
}

Create a Product Rate Plan

Next, you will create a rate plan for the product you created above.

The required fields to create a product rate plan are:

  • Name
  • Effective End Date
  • Effective Start Date
  • Product ID

Issue the following request to create a rate plan for the above product. Use the product id ($Product-Id), returned in the response parameter in the previous exercise.

Request

POST https://rest.apisandbox.zuora.com/v1/object/product-rate-plan

JSON request body

{
  "EffectiveEndDate": "2017-10-01",
  "EffectiveStartDate": "2016-10-01",
  "Name": "Monthly",
  "ProductId": "$Product-Id" }

Create Charges and Tiers

After creating a product and a product rate plan, you need to create charges and tiers to set the price on the product rate plan.

The required fields to create a product rate plan charge and one tier with pricing information:

  • Bill Cycle Type
  • Billing Period
  • Charge Model
  • Charge Type
  • Name
  • Product Rate Plan Id
  • Product Rate Plan Charge Tier Data
    • Active
    • Currency
    • Price
  • Trigger Event
  • Use Discount Specific Account Code

Submit the following request to create a recurring, flat fee charge and a discount charge. You will use the action REST request to create two charges in one call. You will use the rate plan id ($ProdRatePlan-Id) returned in the Id response parameter in the previous exercise.

Request

POST https://rest.apisandbox.zuora.com/v1/action/create

JSON request body

{
  "type": "ProductRatePlanCharge",
   "objects": [{
     "BillCycleType": "DefaultFromCustomer",
     "BillingPeriod": "Month",
     "ChargeModel": "Flat Fee Pricing",
     "ChargeType": "Recurring",
     "Name": "Monthly Charge",
     "ProductRatePlanId": "$ProdRatePlan-Id", "TriggerEvent": "ContractEffective", "UseDiscountSpecificAccountingCode": false, "ProductRatePlanChargeTierData": { "ProductRatePlanChargeTier": [{ "Active": true, "Currency": "USD", "Price": 10.0 }] } }, { "BillCycleType": "DefaultFromCustomer", "BillingPeriod": "Month", "ChargeModel": "Discount-Fixed Amount", "ChargeType": "Recurring", "Name": "New Customer Discount", "ProductRatePlanId": "$ProdRatePlan-Id", "TriggerEvent": "ContractEffective", "UseDiscountSpecificAccountingCode": false, "ApplyDiscountTo": "RECURRING", "DiscountLevel": "subscription", "ProductRatePlanChargeTierData": { "ProductRatePlanChargeTier": [{ "Active": true, "Currency": "USD", "DiscountAmount": "5.0" }] } }] }

Response

A successful response contains the ids of the newly created product rate plan charges and tiers.

CREATE A SUBSCRIPTION

With a product, a product rate plan, and charges in place, you are ready to sign up customers. In this scenario, you will create a subscription for a new customer, using the Subscribe action call.

The Subscribe action performs the following tasks in a single call.

  • Create accounts
  • Create contacts
  • Create payment methods, including external payment options.

This call is similar to the Create Account call used in Quick Start, but has additional options that may be useful in certain situations. For example, the GenerateInvoice and ProcessPayment options have been set to false below, so that the next exercise can invoice and collect for this subscription. This is for illustration purposes, in most cases, you’ll want to invoice and collect from the new subscriber in the same call. This call includes a variety of other options as well, making it a very powerful tool.

Use the following request to create a customer account, contacts, and a subscription. Replace $Today with today’s date in the request body, and use $ProducRatePlan-Id and $ProductRatePlanCharge-Id from the previous exercise.

Request

POST https://rest.apisandbox.zuora.com/v1/action/subscribe

JSON request body

{
  "subscribes": 
  [{
    "Account": 
    {
      "AccountNumber": "Main123",
      "AllowInvoiceEdit": true,
      "AutoPay": false,
      "Batch": "Batch1",
      "BillCycleDay": 1,
      "CrmId": "SFDC-1230661730921",
      "Currency": "USD",
      "CustomerServiceRepName": "Jill Smith",
      "Name": "Bella Rodoni",
      "PaymentTerm": "Due Upon Receipt",
      "PurchaseOrderNumber": "PO-1230661730921",
      "SalesRepName": "Tom Chen",
      "Status": "Draft"
    },
    "PaymentMethod": 
    {
      "CreditCardAddress1": "52 Main Street",
      "CreditCardCity": "Anaheim",
      "CreditCardCountry": "United States",
      "CreditCardExpirationMonth": 1,
      "CreditCardExpirationYear": "2018",
      "CreditCardHolderName": "Bella Rodoni",
      "CreditCardNumber": "4959911773775979",
      "CreditCardPostalCode": "92808",
      "CreditCardState": "California",
      "CreditCardType": "Visa",
      "Type": "CreditCard"
    },
    "BillToContact": 
    {
      "Address1": "52 Main Street",
      "City": "Anaheim",
      "Country": "United States",
      "FirstName": "Bella",
      "LastName": "Rodoni",
      "PostalCode": "92808",
      "State": "California",
      "WorkEmail": "bella@rodoni.com",
      "WorkPhone": "4152225151"
    },
    "SubscribeOptions": 
    {
      "GenerateInvoice": false,
      "ProcessPayments": false
    },
    "SubscriptionData": 
    {
      "Subscription": 
      {
        "AutoRenew": false,
        "ContractAcceptanceDate": "$Today", "ContractEffectiveDate": "$Today", "InitialTerm": 12, "Name": "MainStreetOfficesLandscape", "RenewalTerm": 12, "ServiceActivationDate": "$Today", "TermStartDate": "$Today", "Version": "1" }, "RatePlanData": [{ "RatePlan": { "ProductRatePlanId": "$ProdRatePlan-Id" }, }] } }] }

Response

The response includes the account id ($Account-Id), the subscription id ($Subscription-Id), the invoice id ($Invoice-Id), and the payment id ($Payment-Id) created by the request. Make a note of the id values for the following exercises.

INVOICE AND COLLECT

Use the invoice-collect call in the pay now scenario when you are collecting the full outstanding balance on an account.

Submit the following invoice-collect request to generate an invoice and collect payment in a single call. You will collect a payment using the default electronic payment method you set up for the customer in the Subscribe call.

This is a quick alternative to the full process payment call covered in the later scenario.

Request

POST https://rest.apisandbox.zuora.com/v1/operations/invoice-collect

JSON request body

{ 
  "accountKey":"$Account-Id" }

Response

{
  "invoices": 
  [{
    "invoiceId": "$Invoice-Id", "invoiceNumber": "INV00000091", "invoiceAmount": 801.73 }], "paymentId": "402892053e100406013e1024ab7c00e3", "amountCollected": 801.73, "success": true }

ADJUST AN INVOICE

In this scenario, you will adjust an invoice to change the discount amount.

The process to adjust an invoice is as follows:

  1. Generate an invoice
  2. Post the invoice
  3. Adjust an invoice item

Generate an Invoice

Let’s generate the second invoice for the customer in the second months of the subscription. In most cases, invoices will be generated either when a subscription is created or, automatically, via a Bill Run. Creating a subscription has been covered already in this tutorial. For more information about Bill Runs, go to Knowledge Center.

Request

POST https://rest.apisandbox.zuora.com/v1/object/invoice

JSON request body

{
  "AccountId": "$Account-Id", "TargetDate": "$Today+1 month", "InvoiceDate": "$Today+1 month" }

Response

{
  "Success": true,
  "Id": "$Invoice-Id" }

Post an Invoice

An invoice is created in the “Draft” status. After generating an invoice, update the status of the invoice to “Posted”. You can only adjust an invoice in the “Posted” status.

Request

PUT https://rest.apisandbox.zuora.com/v1/object/invoice/$Invoice-id

JSON request body

{
  "Status": "Posted"
}

Adjust an Invoice Item

In Zuora, you adjust an invoice by adjusting one or more invoice line items. Invoice Item Adjustments allow you to create an adjustment which must always bring the invoice balance toward zero.

To adjust an invoice item, you need to specify the following information:

  • The adjustment date
  • The amount of the adjustment.
  • The invoice id that contains the line item that you want to adjust.
  • The source type, which describes whether the line item is a charge or a credit.
  • The id of the line item, either an Invoice Item Id or a Taxation Id
  • The type of adjustment, credit or debit.

Request

POST https://rest.apisandbox.zuora.com/v1/object/InvoiceItemAdjustment

JSON request body

{
  "AdjustmentDate": "$Today+1 month", "Amount": "2.00", "InvoiceId": "$Invoice-Id", "SourceId": "$InvoiceItem-Id", "SourceType": "InvoiceDetail", "Type": "Credit" }

PROCESS A PAYMENT

In this scenario, you will process an electronic payment on demand. You will apply the payment to the credit balance of a customer account and two invoices.

The process is:

  1. Get the payment method ID for the electronic payment
  2. Process the payment using that payment method ID

Get the Payment Method

Use the following request to retrieve the payment method information for the customer account with ID $Account-Id.

Request

GET https://rest.apisandbox.zuora.com/v1/payment-methods/credit-cards/accounts/$Account-Id

Response

{
  "creditCards": [
    {
      "id": "$PaymentMethod-Id",
      ...
    }
  ]
}

Above is a part of the successful response. Note the payment method ID ($PaymentMethod-Id) that you will use to collect a payment.

You can also use the Query action to retrieve any other payment method types that the customer might have.

Process an Electronic Payment

Use the following request to collect a credit card payment from the customer. A single payment of $1000 will be applied to:

  • The credit balance of the customer account with ID $Account-Id – $150
  • The invoice with ID $Invoice-Id – $500
  • A second invoice, with ID $Invoice2-Id – $350

Request

POST https://rest.apisandbox.zuora.com/v1/object/payment

JSON request body

{
  "AccountId": "$Account-Id",
  "Amount": "1000",
  "AppliedCreditBalanceAmount": "150",
  "EffectiveDate": "2017-10-01",
  "InvoicePaymentData": {
    "InvoicePayment": [
      {
        "Amount": "500",
        "InvoiceId": "$Invoice-Id"
      },
      {
        "Amount": "350",
        "InvoiceId": "$Invoice2-Id"
      }
    ]
  },
  "PaymentMethodId": "$PaymentMethod-Id",
  "Status": "Processed",
  "Type": "Electronic"
}

A request for an external payment would be similar to the above request. Set the Type field to “External” and provide a payment method ID for an external Payment Method, to process an external payment.

Response

{
  "Id": "$Payment-Id",
  "Success": "true"
}

PROCESS A REFUND

In this scenario, you will issue a referenced refund to the customer against a specific payment. A typical workflow to issue a referenced refund is:

  1. Query the invoices for the customer account
  2. Find the payment you need to refund
  3. Process an electronic refund
  4. Create one or more invoice item adjustments

Retrieve Invoices

Use the following request to query invoices for the customer account ($Account-Id).

Request

GET https://rest.apisandbox.zuora.com/v1/transactions/invoices/accounts/$Account-Id

JSON request body

Not required.

Response

{
  "invoices": 
  [{
    "id": "$Invoice-Id", "accountId": "$Account-Id", "accountNumber": "A00000002", "accountName": "XYZ, Inc", "invoiceDate": "2015-11-20", "invoiceNumber": "INV00000002", "dueDate": "2015-12-20", "invoiceTargetDate": "2015-11-20", "amount": 21.1, "balance": 21.1, "createdBy": "2c92c0f84fbac224014fc55639fe11d4", "status": "Draft", "body": null, "invoiceItems": [{ "id": "$InvoiceItem-Id", "subscriptionName": "A-S00000004", "subscriptionId": "2c92c0f9511f56b2015126814ad532cc", "serviceStartDate": "2015-11-20", "serviceEndDate": "2015-11-30", "chargeAmount": 21.1, "chargeDescription": "", "chargeName": "Annual Fee", "chargeId": "2c92c0f9511f56b2015126814af832d2", "productName": "TeamCollab Enterprise", "quantity": 1, "taxAmount": 0, "unitOfMeasure": "" }], "invoiceFiles": [] }], "success": true }

In the above response, note the invoice item id ($InvoiceItem-Id). After issuing a refund to the customer, you will adjust the invoice item of $InvoiceItem-Id.

Find the Payment

Use the following request to retrieve the payments made by the customer ($Account-Id).

Request

GET https://rest.apisandbox.zuora.com/v1/transactions/payments/accounts/$Account-Id

JSON request body

Not required

Response

{
  "success": true,
  "payments": 
  [{
    "paymentMethodId": "2c92c8f83dabf9cf013daef12dd303b0",
    "paidInvoices": 
    [{
      "invoiceId": "2c92a09539190dbe0139190f42780012",
      "invoiceNumber": "INV00000159",
      "appliedPaymentAmount": 5.0
    },
    {
      "invoiceId": "2c92a0953a3fa95d013a407c10a60100",
      "invoiceNumber": "INV00000323",
      "appliedPaymentAmount": 139722.1
    },
    {
      "invoiceId": "2c92a09739190dc60139194bcf1b0098",
      "invoiceNumber": "INV00000160",
      "appliedPaymentAmount": 10521.0
  }],
  "effectiveDate": "2013-03-27",
  "accountId": "2c92a0f9391832b10139183e277a0042",
  "accountName": "subscribeCallYan_1",
  "id": "$Payment-Id", "status": "Processed", "paymentNumber": "P-00000075", "gatewayTransactionNumber": null, "type": "Electronic", "accountNumber": "A00001115", "amount": 150248.1 }, { "paymentMethodId": "2c92a0f9391832b10139183e279e0044", "paidInvoices": [{ "invoiceId": "2c92a09539190dbe0139190f42780012", "invoiceNumber": "INV00000159", "appliedPaymentAmount": 5.0 }], "effectiveDate": "2012-08-11", "accountId": "2c92a0f9391832b10139183e277a0042", "accountName": "subscribeCallYan_1", "id": "2c92a0f9391832b101391922ad5f049d", "status": "Processed", "paymentNumber": "P-00000056", "gatewayTransactionNumber": null, "type": "Electronic", "accountNumber": "A00001115", "amount": 5.0 }] }

In the response, make a note of the payment id ($Payment-Id) that you want to refund against.

Process an Electronic Refund

Use the following request to process a refund to the customer.

Request

POST https://rest.apisandbox.zuora.com/v1/object/refund

JSON request body

{
  "Amount": "5",
  "PaymentId": "$Payment-Id", "Type": "Electronic" }

Response

{
  "Id": "$Refund-Id", "Success": "true" }

Upon successful creation of an electronic refund, money is refunded to the customer through the payment gateway that generated the original Payment.

Create an Invoice Item Adjustment

Use the following request to create a credit invoice item adjustment for the refund you issued above. You will adjust the invoice line item with $InvoiceItem-Id.

Request

POST https://rest.apisandbox.zuora.com/v1/object/InvoiceItemAdjustment

JSON request body

{
  "AdjustmentDate": "$Today",  "Amount": "5.00", "InvoiceId": "$Invoice-Id", "SourceId": "$InvoiceItem-Id", "SourceType": "InvoiceDetail" "Type": "Credit" }

USE PAGINATION TO HANDLE LARGE RESPONSES

When retrieving information using the GET method, the optional pageSize query parameter sets the maximum number of rows to return in a response.

Use the following request to retrieve two products per response.

Request

GET https://rest.apisandbox.zuora.com/v1/catalog/products?pageSize=2

Response

{
  "nextPage": "https://api.zuora.com/rest/v1/catalog/products/SKU-00000081?page=2&pageSize=2",

The nextPage parameter in the response has the URL to retrieve the next two products in the catalog.

Note that the query action has a different paging mechanism. Refer to the queryMore action for additional details on retrieving additional query action results.

APP USE CASES

If you are new to App development, follow the Quick Start tutorials to start building on Zuora Central and create your first App.

We are currently creating tutorials to help you learn more advanced topics. If you have any suggestions for App development tutorials, let us know in the Connect User Group.