Knowledge Center

Knowledge Center > API > REST API > REST API Reference > Revenue Schedules > Create a revenue schedule on a subscription charge

Create a revenue schedule on a subscription charge

This REST API reference describes how to create a revenue schedule by specifying the subscription charge. This method is for custom unlimited revenue recognition only. Request and response field descriptions and sample code are provided.

Request

  • Production: POST https://api.zuora.com/rest/v1/revenue-schedules/subscription-charges/{charge-key}
  • API Sandbox: POST 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.

Request body

revenueScheduleDate

required

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.

referenceId

optional

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.

Character Limit: 60

amount

required

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."

overrideChargeAccountingCodes

optional

When overriding accounting codes from a charge,recognizedRevenueAccountingCode and deferredRevenue AccountingCode must be in the request body and can have empty value.

True or False. A false value will be used if this field is empty in the request body.

recognizedRevenueAccountingCodeType

optional

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

optional

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

optional

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

optional

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

notes

optional

Additional information about this record.

Character Limit: 2,000

cf_txtn__c

optional

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

cf_pkn__c

optional

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

revenueDistributions

An array of revenue distributions. Represents how you want to distribute revenue for this revenue schedule. You can distribute revenue into a maximum of 250 accounting periods with one revenue schedule.

The sum of the newAmount fields must be equal to the amount field.

accountingPeriodName

required

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

The accounting period must be open.

newAmount

 

required

Amount of revenue you want to distribute into the accounting period.

The value must be formatted based on the currency, for example, JPY 30 or USD 30.15. If the value is formatted incorrectly, the following error message is returned:

"Allocation amount with wrong decimal places."

revenueEvent

Represents a change to a revenue schedule, such as posting an invoice or distributing revenue.

eventType

required

Label of the revenue event type. Revenue event type labels can be duplicated. You can configure your revenue event type labels by navigating to Settings > Z-Finance Settings > Configure Revenue Event Types in the Zuora UI. The default revenue event types are:

  • Invoice Posted
  • Invoice Item Adjustment Created
  • Invoice Canceled
  • Invoice Item Adjustment Canceled
  • Revenue Distributed

eventTypeSystemId

required

System ID of the revenue event type. Each eventType has a unique system ID. You can configure your revenue event type system IDs by navigating to Settings > Z-Finance Settings > Configure Revenue Event Types in the Zuora UI.

notes

optional

Additional information about this record.

cf_txtn__c

optional

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

cf_pkn__c

optional

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

Response

This response includes details of a revenue schedule associated with the requested revenue schedule number (rs-number). This resource is for custom unlimited revenue recognition. For all other revenue recognition rules, this call will throw an exception.

revenueScheduleNumber

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

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.

Example

HTTP/JSON request:

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

HTTP/JSON request:

{
   "revenueScheduleDate": "2013-01-01",
   "referenceId": "rs transaction ref",
   "amount": "300",
   "overrideChargeAccountingCodes": "true",
   "recognizedRevenueAccountingCodeType": "Sales Revenue",
   "recognizedRevenueAccountingCode": "Subscription Revenue",
   "deferredRevenueAccountingCodeType": "Deferred Revenue",
   "deferredRevenueAccountingCode": "Deferred Revenue",
   "cf_project__c": "project A",
   "cf_phases__c": "Phase 1",
   "revenueDistributions": [
      {
         "accountingPeriodName": "Jan'2013",
         "newAmount": "100"
         },
      {
         "accountingPeriodName": "Feb'2013",
         "newAmount": "200"
         }
      ],
  "revenueEvent": {
     "eventType": "Revenue Distributed",
     "eventTypeSystemId": "1111111",
     "notes": "Manually distribute revenue by usage",
     "cf_project__c": "project A",
     "cf_phases__c": "Phase 1"
     }
}

JSON response:

{     
   "revenueScheduleNumber": "rs-00000001",
   "success":true
}
Last modified
20:40, 22 Dec 2015

Tags

Classifications

(not set)