Skip to main content

Usage

Zuora

Usage

Usage is the amount of resources a customer uses. You track the usage of metered resources, then charge based on the amount that your customers consume.

Usage is always billed in arrears. For example, you bill in November for usage consumed in October. You can bill usage on a recurring, monthly, quarterly, semi-annual, and annual basis.

Use the Usage object to import the quantity of units that customers use of a product, such as the number of page loads on a wiki. To load usage data, you send a create() call. If usage data isn't in an invoice yet, then you can modify usage data with an update() or delete() call.

You can send a maximum of 50 usage records in a single batch call. If you have a larger amount of usage data to upload, then consider creating a .csv file, then use the Import object instead of the Usage object.

Supported Calls

You can use this object with the following calls:

Walkthroughs and use cases

Here are some common ways to use this object:

  • Upload usage data of metered resources.
  • Change that usage data, including deleting it.
  • Query usage data in preparation for invoicing.
  • Update usage custom fields after usage has been processed.

Field Descriptions

All field names are case sensitive. Check enumerated values in descriptions to confirm capitalization and spacing. See Field Types for additional information.

Name Required? Allowed Operations Description

AccountId

optional

Create
Query
Filter

The ID of the account associated with the usage data. This field is required if no value is specified for the AccountNumber field.

Type: zns:ID
Character limit: 32
Version notes:--
Values: a valid account ID

AccountNumber

optional

Create
Query
Filter

The number of the account associated with the usage data. This field is required if no value is specified for the AccountId field.

Type: string
Character limit: 50
Version notes: WSDL 8.0+
Values: a valid account number

AncestorAccountId

optional

Filter

A filter option for querying all subscriptions under the same account hierarchy.

Type: zns:ID
Character limit: 32
Version notes: --
Values: a valid account ID

ChargeId

optional

Create
Query
Filter

The OrginalId of the rate plan charge related to the usage record, e.g., 2c9081a03c63c94c013c6873357a0117

Type: zns:ID
Character limit: 32
Version notes: --
Values: a valid rate plan charge OriginalID

ChargeNumber

optional

Create
Query
Filter

A unique number for the rate plan charge related to the usage record, e.g., C-00000007

Type: string
Character limit: 50
Version notes: --
Values: a unique number of 50 characters or fewer, either set by the user or automatically generated if left null.

CreatedById

optional

Query
Filter

The user ID of the person who uploaded the usage records.

Type: zns:ID
Character limit: 32
Version notes: WSDL 20.0+
Values: automatically generated

CreatedDate

optional

Query
Filter

The date when the usage was generated.

Type: dateTime
Character limit: 29
Version notes: WSDL 20.0+
Values: automatically generated

Description

optional

Create
Query
Update
Delete
Filter

A description of the usage data.

Type: string
Character limit: 200
Version notes: --
Values: a string of 200 characters or fewer

EndDateTime

optional

Create
Query
Update
Delete
Filter

The end date and time of a range of time when usage is tracked. Use this field for reporting; this field doesn't affect usage calculation.

Type: dateTime
Character limit: 29
Version notes: --
Values: a valid date and time value

Id

optional

Query
Filter

The ID of this object. Upon creation, the ID for this object is UsageId.

Type: zns:ID
Character limit: 32
Version notes: --
Values: automatically generated

ImportId

optional

Query
Filter

The ID of an import that successfully imported usage data. This value comes from using the Import object or using the web-based UI instead of using the Usage object to upload usage data.

Type: zns:ID
Character limit: 32
Version notes: WSDL 37.0+
Values: automatically generated

InvoiceId

optional

Filter

If this usage has been invoiced, the ID of the invoice.

Type: zns:ID
Character limit: 32
Version notes: WSDL 33.0+
Values: valid invoice ID

InvoiceNumber

optional

Filter

If this usage has been invoiced, the number of the invoice.

Type: string
Character limit: 32
Version notes: WSDL 33.0+
Values: an invoice number

Quantity

required

Create
Query
Update
Delete
Filter

Indicates the number of units used.

Type: decimal
Character limit: 16
Version notes: type is double for WSDL 18.0 and older
Values: a valid decimal amount equal to or greater than 0

RbeStatus

optional

Query
Filter

Indicates if the rating and billing engine (RBE) processed usage data for an invoice.

Type: string (enum)
Character limit: 9
Version notes: --
Values: automatically generated to be one of the following values: Importing, Pending, Processed

SourceName

optional

Query
Filter

The name of the source file that contains usage data. This field is generated from the name of the file uploaded in the web-based UI.

Type: string
Character limit: 50
Version notes: --
Values: automatically generated from the spreadsheet's filename

SourceType

optional

Query
Filter

Indicates if the usage records were imported from the web-based UI or the API.

Type: string (enum)
Character limit: 6
Version notes: --
Values: automatically generated to be one of the following values: APIImport

StartDateTime

required

Create
Query
Update
Delete
Filter

The start date and time of a range of time when usage is tracked. Zuora uses this field value to determine the usage date. Unlike the EndDateTime, the StartDateTime field does affect usage calculation.

Type: dateTime
Character limit: 29
Version notes: --
Values: a valid date and time value

SubmissionDateTime

optional

Query
Filter

The date when usage was submitted. The value of SubmissionDateTime field is the same as the value of UpdatedTime field.

Type: dateTime
Character limit: 29
Version notes: --
Values: automatically generated

SubscriptionId

optional

Create
Query
Filter

The OriginalId of the subscription that contains the fees related to the usage data.

Type: zns:ID
Character limit: 32
Version notes: --
Values: a valid subscription ID

SubscriptionNumber

optional

Create
Query
Filter

The name* of the subscription that contains the fees related to the usage data.

Type: string
Character limit: 100
Version notes: --
Values: the name of a subscription

*Note that the "subscription number" in the Usage object corresponds to the value of the subscription "name" field in the Subscription object.

UniqueKey optional

Create
Query
Update
Delete

Note: The field is only available if you have Prepaid with Drawdown feature enabled. 

A customer-defined specific identifier of a usage record. 

Type: string

Character limit: 255

Version notes: WSDL 114+

Values: any string value as defined by customer, for example, UK123. If not specified, its value will be ‘null’ by default. When you upload a usage record and specify the unique key, the system will check if there is an existing usage record with the same unique key. See this article for details.

UOM

required

Create
Query
Update
Delete
Filter

Specifies the units to measure usage. Units of measure are configured in the web-based UI. Your values depend on your configuration in Z-Billing > Settings.

Type: string
Character limit
Version notes: --
Values: a valid unit of measure

UpdatedById

optional

Query
Filter

The ID of the user who last updated the usage upload.

Type: zns:ID
Character limit: 32
Version notes: WSDL 20.0+
Values: automatically generated

UpdatedDate

optional

Query
Filter

The date when the usage upload was last updated.

Type: dateTime
Character limit: 29
Version notes: WSDL 20.0+
Values: automatically generated

Additional Field Detail

AccountId

The ID of the account associated with the usage data. This field is required if no value is specified for the AccountNumber field.

Usage data is associated primarily with a specific account. When you bill an account, the invoice includes all the usage-based fees in the billing period. If accounts can have multiple subscriptions, then you can specify charge and subscription information in other fields to prevent repeated counting of usage data. These other fields are the following:

  • ChargeId or ChargeNumber
  • SubscriptionId or SubscriptionNumber

ChargeId, ChargeNumber

The ID or number of the rate plan charge for fees related to the usage data. Use the ChargeId or ChargeNumber fields to connect usage to its charge. Use SubscriptionId or SubscriptionNumber to apply usage data to all charges with the same unit of measure in the subscription.

If you omit all of the fields ChargeIdChargeNumberSubscriptionId, and SubscriptionNumber, then usage is billed against all charges associated with the account that have the same UOM values. The two charge-related fields, ChargeId and ChargeNumber, connect usage with a specific charge. The two subscription-related fields, SubscriptionId and SubscriptionNumber, connect usage with a specific subscription.

ChargeId changes each time an amendment is performed, however ChargeNumber does not, which makes it useful for tracking the charge.

Id

The ID of this object. Every object has a unique identifier that Zuora automatically assigns upon creation. You use this ID later when you work with the object. For example, if you send an amend() call to modify an existing subscription, then you need to include the specific Subscription object's ID with the call.

The ID for the Usage object is UsageId.

InvoiceId, InvoiceNumber

If the usage record has been invoiced to the customer, it will contain an automatically-generated invoice ID and an invoice number. As of WSDL 33.0, you can include the invoice ID and/or the invoice number in the WHERE clause of your query. This allows you, for instance, to retrieve all the usage details for a particular invoice. Note that the invoice ID and invoice number are not queryable fields; the SOAP API will not return these fields in the result.

SubscriptionId, SubscriptionNumber

The original ID or number of the subscription that contains the fees related to the usage data. Use the ChargeId or ChargeNumber field to connect usage to its charge. Use SubscriptionId or SubscriptionNumber to apply usage data to all charges with the same unit of measure in the subscription.

If you omit all of the fields ChargeIdChargeNumberSubscriptionId, and SubscriptionNumber, then usage is billed against all charges associated with the account that have the same UOM values. The two charge-related fields, ChargeId and ChargeNumber, connect usage with a specific charge. The two subscription-related fields, SubscriptionId and SubscriptionNumber, connect usage with a specific subscription.

Note that ChargeId and SubscriptionId are original IDs of the rate plan charge and the subscription.

Custom Fields

In the Usage object, you can update custom fields using the SOAP API even if the object has a processed status. Only custom fields can be updated in this way. If you try to update any standard fields after the object has been processed, you will receive a ValidateException error.

Example

Request

<soapenv:Body>
       <api:update>
       <api:zObjects xsi:type="ns2:Usage">
            <obj:Id>402891f74c443614014c44f93bde07ae</obj:Id>
            <obj:Index1__c>Index_test</obj:Index1__c>
            <obj:Field__c>Field_test</obj:Field__c>
            <obj:Country__c>Japan</obj:Country__c>
       </api:zObjects>
      </api:update>
   </soapenv:Body>

 

Response

<soapenv:Body>
      <ns1:updateResponse xmlns:ns1="http://api.zuora.com/">
         <ns1:result>
            <ns1:Id>402891f74c443614014c44f93bde07ae</ns1:Id>
            <ns1:Success>true</ns1:Success>
         </ns1:result>
      </ns1:updateResponse>
   </soapenv:Body>

See Custom Fields for more information about custom fields.