Usage

Last updated
Save as PDF

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: `API`, `Import`
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 ChargeId, ChargeNumber, SubscriptionId, 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.

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.