Skip to main content

Reseller Account

Zuora

Reseller Account

  1. Last updated
  2. Save as PDF

The Reseller Account feature provides the capability to delay the calculation of account metrics for an account you flagged as a partner account. This can avoid API competition errors for scalability when you create a large number of orders, standalone invoices, credit memos, and payments for a single account in parallel.

You can use this feature when you need to manage a large number of subscriptions for a single account and handle high-volume operations on the same account. For example, if the number of subscriptions exceeds 300 for a single account, you need to make parallel API calls for order changes on that account.

You can enable the feature in Sandbox and Production environments with the self-service interface. For more information, see Enable billing features by yourself.

Feature overview

The Reseller Account feature is specifically designed for businesses that work with distributors and resellers or operate in a B2B model, with a large number of subscriptions.

Typically, to prevent conflicts and being locked, you can make API calls sequentially, for example, creating orders for the same account one after another. However, as the workload increases, this sequential approach may not scale effectively. Therefore, when dealing with high-volume operations, you may need to make parallel API calls. This is where the new feature comes into play.

With this feature, you can flag an account as a partner account using the Zuora UI or REST API.

  • Through the Zuora UI, you can select the Partner Account check box in the Additional Fields section on the New Customer Account page.
  • Through the REST API, you can use the Create an account or Update an account operation to specify the partnerAccount field in the request.

If you flag a customer account as a partner account, the calculation of account metrics is performed asynchronously during operations such as subscription creation, order changes, invoice generation, and payments. Specifically, the calculation of metrics is delayed for partner accounts. However, you can still use the Retrieve an account or Retrieve an account summary operation to retrieve the time when account metrics are last updated from the value of the lastMetricsUpdate field.

This feature is particularly useful in scenarios where you have to create a large number of subscriptions or orders for reseller accounts, or when you perform data migration through standalone invoices for distributor accounts in concurrent API requests. By flagging an account as a partner account, you can streamline your operations and improve the scalability of your billing processes.

The Zuora UI, REST API, data source, AQuA, Data Query, and Object Query are enhanced to support the Reseller Account feature. The following table lists the detailed changes introduced in the Reseller Account feature.

Base object

Field/Related object

Access approaches

Account
  • partnerAccount
  • lastMetricsUpdate
  • Zuora UI
  • REST API
  • Account data source
  • AQuA
  • Data Query
  • Object Query

Order
  • partnerAccount
  • REST API

For a summary of REST API updates specific to this feature, see the "API updates for the Reseller Account feature" section in 2023 API Changelog (July 20, 2023) and REST API Reference. 

Functional behavior changes

With the Reseller Account feature, Zuora does not calculate account metrics for partner accounts synchronously when you perform the following operations:

  • Post billing documents, including invoices, credit memos, debit memos (memos only available if you have the Invoice Settlement feature enabled)
  • Create orders, including subscription creation and order changes
  • Apply or unapply payments or credit memos
  • Unpost billing documents, including invoices, credit memos, debit memos
  • Refund

If you flag an account as a partner account, the calculation of account metrics is delayed. By default, Zuora calculates account metrics every hour. The interval is configurable at the tenant level. To change the calculation interval, submit a request at Zuora Global Support. 

The account metric update needs to be performed on account lockout. A shorter interval increases the probability of competition lock errors. Therefore, it is best practice not to configure a shorter interval if you have a large volume of traffic and the traffic lasts for a long time. 

All account metrics except contractedMrr belong to the invoice owner account, while contractedMrr belongs to the subscription owner account.

The following list provides account metrics: 

  • balance
  • creditBalance
  • lastInvoiceDate
  • totalInvoiceBalance
  • totalDebitMemoBalance
  • unappliedCreditMemoAmount
  • unappliedPaymentAmount
  • contractedMrr

For details about these account metrics, see the metrics object field in the response body of the Retrieve an account operation.

Common use cases

You can use the Reseller Account feature to meet different business requirements.

Create numerous subscriptions or orders for reseller accounts

You have fleet business in reseller model. Your reseller account usually has itself as the invoice owner and its end users as different subscription owners, so you create subscriptions in batches for your reseller account. To bill your seller account, you want to execute bill runs for the reseller account at the end of each month.

To meet the requirements, you have to create multiple orders to the same subscription owner accounts for your reseller account through concurrent API requests. During the process, account metric calculation might compete on the same account. To facilitate the billing process, you can set the partnerAccount field to true for the subscription owner account. The contractedMrr account metric is calculated on the subscription owner account. Therefore, its calculation is delayed when the partnerAccount field is set as true for the subscription owner account.

To meet the business requirements, perform the following steps:

  1. Update an existing invoice owner account by setting the partnerAccount field to true. 
  2. Update subscription owner accounts by setting the partnerAccount field to true. 
  3. Create subscriptions through the REST API in multiple requests.
    1. If you have the Orders or Orders Harmonization feature enabled, use the Create an order or Create an order asynchronously operation.
    2. If you have neither the Orders or Orders Harmonization feature enabled, use the Create a subscription operation.
      No billing process is triggered when any subscription is created.
  4. Create a bill run to bill the reseller account at the end of the month.
  5. After the bill run is complete, use the Retrieve an account or Retrieve an account summary operation to check the value of the lastMetricsUpdate field for the accounts. 

Create numerous subscriptions or orders for same account

You run your business in distributor model, and your main order entry is from Electronic Data Interchange (EDI). These electronic orders come from a distributor as individual orders. A distributor can have multiple orders. To process these orders, you run a batch process every 20 minutes.

The subscriptions under the same invoice owner have different subscription owners, so no competition exists on the same subscription owner. Therefore, you can set the partnerAccount field to false for subscription owner accounts. 

To meet the business requirements, perform the following steps:

  1. Update an existing invoice owner account by setting the partnerAccount field to true. 
  2. Keep the partnerAccount field set to false for subscription owner accounts. 
  3. Create subscriptions through the REST API in multiple requests.
    1. If you have the Orders or Orders Harmonization feature enabled, use the Create an order or Create an order asynchronously operation.
    2. If you have neither the Orders or Orders Harmonization feature enabled, use the Create a subscription operation.
      No billing process is triggered when any subscription is created.
  4. Use the Retrieve an account or Retrieve an account summary operation to check the value of the lastMetricsUpdate field for the accounts. 

Migrate data through standalone invoices for distributor accounts.

You want to migrate over 200,000 invoices under an account during the migration phase. After going live, you have to process around 30,000 invoices for such accounts every day.

To meet the business requirements, perform the following steps:

  1. Update an existing invoice owner account by setting the partnerAccount field to true. 
  2. Create standalone invoices through the REST API in multiple requests.
  3. After all standalone invoices are created and uploaded, use the Retrieve an account or Retrieve an account summary operation to check the value of the lastMetricsUpdate field for the accounts.

Transfer subscription owners for reseller accounts

When transferring subscription owners between source and target accounts for reseller accounts through concurrent orders, metric calculation probably competes on the same accounts. Therefore, it is necessary to set the partnerAccount field to true for both the source and target accounts.