Usage
From API Documentation
This object tracks how many units a customer has used of a certain product, such as the number of minutes in a telephone plan. You can import the data through the Zuora application Admin console, or you can upload a CSV (comma-separated values) file. Spreadsheet programs have the capability of exporting data to CSV files.
Supported Calls
This object is used in the create, delete, query and update calls. Please note that you can only update unprocessed (un-invoiced) usage records.
Note: The API can support a maximum of 50 usage records in a single batch call. The Zuora user interface can support an unlimited number of usage records.
Fields
In addition to the following fields, zObject contributes additional fields. For information on the field types, see Field Types.
| Name | Required? | Type | Allowed Operations: ● Yes ○ No | Allowable Values | Description |
|---|---|---|---|---|---|
| AccountId | Required if AccountNumber is not specified | zns: ID | ● Create
● Query | Any valid account ID | This is the account that the usage is tied to. |
| AccountNumber | Required if AccountId is not specified when creating usage. | string | ● Create
● Query | Any account number, 255 characters maximum. | Available in version 8.0+ of the API. This is the account number that the usage is tied to. You can specify this in lieu of the AccountId when creating usage. |
| AncestorAccountId | No | zns:ID | ○ Create
○ Query | Use as a filter to query all subscriptions under the same account hierarchy. | |
| ChargeId | No. However, if omitted in the create() call, the usage will be applied to all charges that have the same UOM specified. It is strongly recommended that either CharngeNumber or ChargeId is specified when creating a usage record. | ZNS:Id | ● Create
● Query | Valid ID of RatePlanCharge | The RatePlanCharge ID. This can be used in lieu of ChargeNumber. You need not specify both. |
| ChargeNumber | No. However, if omitted in the create() call, the usage will be applied to all charges that have the same UOM specified. It is strongly recommended that either CharngeNumber or ChargeId is specified when creating a usage record. | string | ● Create
● Query | This number is automatically generated | The RatePlanCharge number. This can be used in lieu of ChargeId. You need not specify both. |
| CreatedById | System generated, always exists | ZNS:Id | ○ Create
● Query | 32 characters maximum. This field is not editable. | Available as of version 20.0 of the API. The Zuora system automatically generates this ID of the user who created the object. |
| CreatedDate | System generated, always exists | dateTime | ○ Create
● Query | This field is not editable. | Available as of version 20.0 of the API. The Zuora system automatically generates this, and denotes when the objects was first created. |
| Description | No | string | ● Create
● Query | 200 characters maximum | Description of the usage. |
| EndDateTime | No | dateTime | ● Create
● Query | A valid dateTime | If a usage is being tracked over a span of time, this is the ending date and time for that span of time. The EndDateTime has no bearing on how charge is calculated. This is solely for convenience and reporting. |
| Quantity | Yes | double (v1.0-18.0) / decimal (v19.0+) | ● Create
● Query | A valid double amount; this cannot be less than 0 | This indicates how much of the item has been used. |
| RbeStatus | No. System generated, and always exists. | string | ● Create
● Query | Pending, Processed | This indicates whether or not the usage data has been processed by Z-Billing for an invoice or not. |
| SourceName | No, system generated for file uploaded usage data via Z-Billing. | string | ○ Create
● Query | 50 characters maximum | The name of the source of the usage information (the spreadsheet's file name). |
| SourceType | No, system generated. | string | ○ Create
● Query | API, Import | This indicates how the usage information was entered into Zuora, whether uploaded via the API or imported within Z-Billing. |
| StartDateTime | Yes | dateTime | ● Create
● Query | A valid dateTime | This is the date of which the usage occurred. Zuora use the StartDateTime to determine the date of the usage, whereas EndDateTime is only used for reporting and convenience. |
| SubmissionDateTime | No, system generated. | dateTime | ● Create
● Query | A valid dateTime | This is the date on which the usage was submitted. |
| SubscriptionId | No | ZNS:Id | ● Create
● Query | A valid subscription Id. | This is not required, with ChargeNumber or ChargeId the preferred method for connecting the usage to its charge. In lieu of ChargeNumber or ChargeId, SubscriptionId or SubscriptionNumber can be used. NOTE: If SubscriptionId or SubscriptionNumber is used in lieu of ChargeNumber or ChargeId, the usage will be applied to ALL charges with the same unit of measure. |
| SubscriptionNumber | No | string | ● Create
● Query | A valid subscription/code. | This is not required, with ChargeNumber or ChargeId the preferred method for connecting the usage to its charge. In lieu of ChargeNumber or ChargeId, SubscriptionId or SubscriptionNumber can be used. NOTE: If SubscriptionId or SubscriptionNumber is used in lieu of ChargeNumber or ChargeId, if the usage will be applied to ALL charges with the same unit of measure. |
| UOM | Yes | string | ● Create
● Query | Allowable "unit of measure" values which have been configured within Z-Billing Settings. 255 characters maximum. | This is the unit of measure that is being used to measure this usage. |
| UpdatedById | System generated, always exists | ZNS:Id | ○ Create
● Query | 32 characters maximum. This field is not editable. | Available as of version 20.0 of the API. The Zuora system automatically generates this Id of the user who last updated the object. |
| UpdatedDate | System generated, always exists | dateTime | ○ Create
● Query | This field is not editable. | Available as of version 20.0 of the API. The Zuora system automatically generates this, and denotes when the objects was last updated. |
