Knowledge Center

Knowledge Center > API > REST API > REST API Reference > Revenue Schedules > Get revenue schedule details of a subscription charge

Get revenue schedule details of a subscription charge

This REST API reference describes how to get the revenue schedule details by specifying subscription charge ID. Request and response field descriptions and sample code are provided. 

Request

  • Production: GET https://api.zuora.com/rest/v1/revenue-schedules/subscription-charges/{charge-key}
  • API Sandbox: GET https://apisandbox-api.zuora.com/rest/v1/revenue-schedules/subscription-charges/{charge-key}

Request header

The Accept request header is optional. Only JSON is returned.

Request parameters

charge-key

required

path

ID of the subscription rate plan charge; for example, 402892793e173340013e173b81000012.

pageSize

optional

path

Must be an integer. A maximum number of 300 pages can be returned in a response. Any value greater than 300 is treated as 300.

Response

This response includes details of a revenue schedule associated with the requested revenue schedule number (rs-number). 

success

Returns true if the request is successful. Otherwise, returns false.

processId

The internal process ID used to assist Zuora support. Returned only if success is false.

reasons

Information describing the reason for the result. Returned only if success is false.

code

An eight-digit numeric error code.

message

A description of the error.

If a revenue schedule does not exist for the requested subscription charge ID, then you will receive a response saying "Could not find subscription charge: {charge-key}."

revenueSchedules

Represents how revenue will be recognized over time.

This contains the details of a revenue schedule. If you do not specify the pageSize variable, the default number of revenue schedules returned per invocation is 8, and if there are more than 8 revenue schedules to be returned, the nextPage field will provide a hyperlink to view the next page(s) of revenue events. The order of revenue schedules is descending by the updatedOn field.

number

Revenue schedule number. The revenue schedule number is always prefixed with "RS", for example, "RS-00000001".

recognitionRuleName

The name of the recognition rule.

amount

The revenue schedule amount, which is the sum of all revenue items. This field cannot be null and must be formatted based on the currency, such as JPY 30 or USD 30.15. Test out the currency to ensure you are using the proper formatting otherwise, the response will fail and this error message is returned:  "Allocation amount with wrong decimal places."

recognizedRevenue

The revenue that was distributed in a closed accounting period.

unrecognizedRevenue

Revenue distributed in all open accounting periods, which includes the open-ended accounting period.

undistributedUnrecognizedRevenue

Revenue in the open-ended accounting period.

currency

The type of currency used. 

notes

Additional information about this record.

accountId

An account ID.

subscriptionId

The original subscription ID.

subscriptionChargeId

The original subscription charge ID.

productChargeId

Unique product rate plan charge ID.

createdOn

The date when the record was created in YYYY-MM-DD HH:MM:SS format.

updatedOn

The date when the revenue automation start date was set.

referenceId

Reference ID is used only in the custom unlimited rule to create a revenue schedule. In this scenario, the revenue schedule is not linked to an invoice item or invoice item adjustment.

revenueScheduleDate

The effective date of the revenue schedule. For example, the revenue schedule date for bookings-based revenue recognition is typically set to the order date or contract date.

The date cannot be in a closed accounting period. The date must be in the YYYY-MM-DD format.

linkedTransactionType

The linked transaction ID for billing transactions. This field is used for all rules except the custom unlimited or manual recognition rule models. If using the custom unlimited rule model, then the field value must be null. If the field is not null, then the referenceId field must be null. 

linkedTransactionId

The type of linked transaction for billing transactions, which can be invoice item or invoice item adjustment. This field is used for all rules except the custom unlimited or manual recognition rule models. 

linkedTransactionNumber

The number for the linked invoice item or invoice item adjustment transaction. This field is used for all rules except the custom unlimited or manual recognition rule models.  If using the custom unlimited or manual recognition rule models, then the field value is null. 

cf_txtn__c

One or more optional custom fields, where n is the maximum number of custom fields allowed.

cf_pkn__c

One or more optional custom fields, where n is the maximum number of custom fields allowed. 

 

revenueItems

Revenue items are listed in ascending order by the accounting period start date.

accountingPeriodName

Name of the accounting period. The open-ended accounting period is named Open-Ended

isAccountingPeriodClosed

 

 Indicates if the accounting period is closed or open. 

amount

The amount of the revenue item.

currency

The type of currency used. 

accountingPeriodStartDate

The accounting period start date.

accountingPeriodEndDate

The accounting period end date. The accounting period end date of the open-ended accounting period is null.

recognizedRevenueAccountingCodeType

The type associated with the recognized revenue accounting code, such as Sales Revenue or Sales Discount. Required only when overrideChargeAccountingCodes is true. Otherwise this value is ignored.

recognizedRevenueAccountingCode

The accounting code for recognized revenue, such as Monthly Recurring Charges or Overage Charges. Required only when overrideChargeAccountingCodes is true. Otherwise the value is ignored.

deferredRevenueAccountingCodeType

The type associated with the deferred revenue accounting code, such as Deferred Revenue. Required only when overrideChargeAccountingCodes is true. Otherwise this value is ignored.

deferredRevenueAccountingCode

The accounting code for deferred revenue, such as Monthly Recurring Liability. Required only when overrideChargeAccountingCodes is true. Otherwise this value is ignored.

nextPage

Provides hyperlinks to view the next pages.

revenueScheduleListURL

Returns the URLs of revenue schedules.

 

Examples

HTTP/JSON request:

GET https://api.zuora.com/rest/v1/revenue-schedules/subscription-charges/2c92c0f943977b4f0143b23487ed432e

JSON response:

{
   "revenueSchedules": [
   {
      "number": "RS-00000291",
      "recognitionRuleName": "Recognize upon invoicing",
      "amount": 50,
      "undistributedUnrecognizedRevenue": 50,
      "recognizedRevenue": 0,
      "unrecognizedRevenue": 50,
      "currency": "USD",
      "notes": null,
      "createdOn": "2014-01-21 13:59:25",
      "updatedOn": "2014-01-21 13:59:25",
      "accountId": "2c92c0f8439770960143b2141f5a584e",
      "subscriptionId": "2c92c0f943977b4f0143b23487994327",
      "subscriptionChargeId": "2c92c0f943977b4f0143b23487ed432e",
      "linkedTransactionId": "2c92c094439782460143b62c2ee90f5a",
      "linkedTransactionType": "InvoiceItem",
      "referenceId": null,
      "revenueScheduleDate": "2014-01-21",
      "cf_phases__c": "Phase 1",
      "cf_project__c": "project A",
      "revenueItems": [
         {
            "accountingPeriodName": "Open-Ended",
            "isAccountingPeriodClosed": false,
            "amount": 50,
            "currency": "USD",
            "accountingPeriodStartDate": "2013-12-11",
            "accountingPeriodEndDate": null,
            "recognizedRevenueAccountingCodeType": null,
            "recognizedRevenueAccountingCode": null,
            "deferredRevenueAccountingCodeType": null,
            "deferredRevenueAccountingCode": null
            }
         ]
      },
   {
      "number": "RS-00000290",
      "recognitionRuleName": "Recognize upon invoicing",
      "amount": 50,
      "undistributedUnrecognizedRevenue": 50,
      "recognizedRevenue": 0,
      "unrecognizedRevenue": 50,
      "currency": "USD",
      "notes": null,
      "createdOn": "2014-01-21 13:59:25",
      "updatedOn": "2014-01-21 13:59:25",
      "accountId": "2c92c0f8439770960143b2141f5a584e",
      "subscriptionId": "2c92c0f943977b4f0143b23487994327",
      "subscriptionChargeId": "2c92c0f943977b4f0143b23487ed432e",
      "linkedTransactionId": "2c92c094439782460143b62c2ee60f59",
      "linkedTransactionNumber": "INV00000838",
      "linkedTransactionType": "InvoiceItem",
      "referenceId": null,
      "revenueScheduleDate": "2014-01-21",
      "cf_phases__c": "Phase 1",
      "cf_project__c": "project A",
      "revenueItems": [
         {
            "accountingPeriodName": "Open-Ended",
            "isAccountingPeriodClosed": false,
            "amount": 50,
            "currency": "USD",
            "accountingPeriodStartDate": "2013-12-11",
            "accountingPeriodEndDate": null,
            "recognizedRevenueAccountingCodeType": null,
            "recognizedRevenueAccountingCode": null,
            "deferredRevenueAccountingCodeType": null,
            "deferredRevenueAccountingCode": null
            }
         ]
      },
"nextPage": "https://apisandbox-api.zuora.com/rest/v1/revenue-schedules/subscription-charges/2c92c0f943977b4f0143b23487ed432e?page=2&pageSize=8",
"success": true
}
Last modified
19:04, 13 Nov 2016

Tags

Classifications

(not set)