Knowledge Center

Knowledge Center > API > REST API > REST API Reference > Subscriptions > Create subscription

Create subscription

This REST API reference describes how to create a new subscription for an existing customer account.

Request

  • Production: POST https://api.zuora.com/rest/v1/subscriptions
  • API Sandbox: POST https://apisandbox-api.zuora.com/rest/v1/subscriptions

Request Header

zuora-version

optional

The minor version of the Zuora REST API. 

You only need to set this parameter if you use the collect or invoice field. See REST API Basics for more information.

Accept

optional

Optionally enter application/json. Only JSON is returned.

Request body

accountKey

required

Customer account number or ID

subscriptionNumber

optional

Subscription Number. The value can be up to 1000 characters.

If you do not specify a subscription number when creating a subscription, Zuora will generate a subscription number automatically.

If the account is created successfully, the subscription number is returned in the subscriptionNumber response field.

invoiceOwnerAccountKey

optional

Invoice owner account number or ID

This feature is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support

termType

required

Possible values are: TERMEDEVERGREEN. See Subscriptions for more information.

contractEffectiveDate

required

Effective contract date for this subscription, as yyyy-mm-dd

serviceActivationDate

optional

The date on which the services or products within a subscription have been activated and access has been provided to the customer, as yyyy-mm-dd.

Default value is dependent on the value of other fields. See Notes section below for more details.

customerAcceptanceDate

optional

The date on which the services or products within a subscription have been accepted by the customer, as yyyy-mm-dd.

Default value is dependent on the value of other fields. See Notes section below for more details.

termStartDate

optional

The date on which the subscription term begins, as yyyy-mm-dd. If this is a renewal subscription, this date is different from the subscription start date.

initialTerm

conditional

The length of the period for the first subscription term. Default is 0. Default is 0. If termType is TERMED, then this field is required, and the value must be greater than 0. If termType is EVERGREEN, this field is ignored.

initialTermPeriodType

The period type for the first subscription term.

This field is used with the InitialTerm field to specify the initial subscription term.

Values are:

  • Month (default)
  • Year
  • Day
  • Week

autoRenew

optional

If true, this subscription automatically renews at the end of the subscription term. Default is false.

renewalTerm

optional

The length of the period for the subscription renewal term. Default is 0.

renewalTermPeriodType

The period type for the subscription renewal term.

This field is used with the RenewalTerm field to specify the subscription renewal term.

Values are:

  • Month (default)
  • Year
  • Day
  • Week

renewalSetting

optional

Specifies whether a termed subscription will remain termed or change to evergreen when it is renewed.

Values:

  • RENEW_WITH_SPECIFIC_TERM (default)
  • RENEW_TO_EVERGREEN

notes

optional

String of up to 500 characters

invoiceCollect

optional

This field has been replaced by the invoice field and the collect field. invoiceCollect is available only for backward compatibility.

If true (default), an invoice is generated and payment collected automatically during the subscription process. If false, no invoicing or payment takes place. The invoice generated in this operation is only for this subscription, not for the entire customer account.

This field is in Zuora REST API version control. Supported minor versions are 186.0, 187.0, 188.0, and 189.0. See Zuora REST API Versions for more information.

invoice

optional

Creates an invoice for a subscription. The invoice generated in this operation is only for this subscription, not for the entire customer account.

If the value is true, an invoice is created. If the value is false, no action is taken. The default value is true

This field is in Zuora REST API version control. Supported minor versions are 196.0 or later. To use this field in the method, you must set the zuora-version parameter to the minor version number in the request header. See Zuora REST API Versions for more information.

collect

optional

Collects an automatic payment for a subscription. The collection generated in this operation is only for this subscription, not for the entire customer account.
If the value is true, the automatic payment is collected. If the value is false, no action is taken.
The default value is true.
Prerequisite: The invoice field must be true

This field is in Zuora REST API version control. Supported minor versions are 196.0 or later. To use this field in the method, you must set the zuora-version parameter to the minor version number in the request header. See Zuora REST API Versions for more information.

invoiceSeparately

optional

Separates a single subscription from other subscriptions and invoices the charge independently. 
If the value is true, the subscription is billed separately from other subscriptions. If the value is false, the subscription is included with other subscriptions in the account invoice.
The default value is false.
Prerequisite: The default subscription setting Enable Subscriptions to be Invoiced Separately must be set to Yes.

applyCreditBalance

optional

Applies a credit balance to an invoice.
If the value is true, the credit balance is applied to the invoice. If the value is false, no action is taken.
Prerequisite: invoice must be true

Note: If you are using the field invoiceCollect rather than the field invoice, the invoiceCollect value must be true.

To view the credit balance adjustment, retrieve the details of the invoice using the Get Invoices method.

invoiceTargetDate

optional

Date through which to calculate charges if an invoice is generated, as yyyy-mm-dd. Default is current date.

OpportunityCloseDate_QT

optional

The closing date of the Opportunity. This field is populated when the subscription originates from Zuora Quotes.

This field is used only for reporting subscription metrics. 

See Subscription Data Source for more information.

OpportunityName_QT

optional

The unique identifier of the Opportunity. This field is populated when the subscription originates from Zuora Quotes.

This field is used only for reporting subscription metrics. 

See Subscription Data Source for more information.

QuoteBusinessType_QT

optional

The specific identifier for the type of business transaction the Quote represents such as New, Upsell, Downsell, Renewal, or Churn. This field is populated when the subscription originates from Zuora Quotes.

This field is used only for reporting subscription metrics. 

See Subscription Data Source for more information.

QuoteNumber_QT

optional

The unique identifier of the Quote. This field is populated when the subscription originates from Zuora Quotes.

This field is used only for reporting subscription metrics. 

See Subscription Data Source for more information.

QuoteType_QT

optional

The Quote type that represents the subscription lifecycle stage such as New, Amendment, Renew or Cancel. This field is populated when the subscription originates from Zuora Quotes.

This field is used only for reporting subscription metrics. 

See Subscription Data Source for more information.

cf_txtn__c

optional

One or more optional custom fields.

cf_pkn__c

optional

One or more optional custom fields.

subscribeToRatePlans

required 

Container for one or more rate plans for this subscription.

productRatePlanId

required

ID of a product rate plan for this subscription.

cf_txtn__c

optional

One or more optional custom fields.

cf_pkn__c

optional

One or more optional custom fields.

chargeOverrides

optional

This optional container is used to override the quantity of one or more product rate plan charges for this subscription.

productRatePlanChargeId

required

ID of a product rate-plan charge for this subscription.

Type: string

number

optional

Unique number that identifies the charge. System-generated if not provided.

Type: string up to 50 characters

description

optional

Description of the charge.  

Type: String up to 500 characters

price

optional

Price for units in the subscription rate plan.

Type: decimal (currency)

tiers

optional

Container for Volume, Tiered or Tiered with Overage charge models. Supports the following charge types:

  • One-time
  • Recurring
  • Usage-based

tier

required

Unique number that identifies the tier that the price applies to.

Type: long

startingUnit

optional

Starting number of a range of units for the tier.

Type: decimal

endingUnit

optional

End number of a range of units for the tier. 

Type: decimal

price

required

Price of the tier if the charge is a flat fee, or the price of each unit in the tier if the charge model is tiered pricing.

Type: decimal (currency)

priceFormat

optional

Indicates if pricing is a flat fee or is per unit.

Type: string (enum)

Values:

  • FlatFee
  • PerUnit

includedUnits

optional

Specifies the number of units in the base set of units for this charge. Must be >=0.

Type: long

overagePrice

optional

Price for units over the allowed amount. 

Type: decimal (currency)

listPriceBase

optional

The list price base for the product rate plan charge.

Type: string

Values:

  • Per_Billing_Period
  • Per_Month
  • Per_Week

quantity

required

Number of units. Must be >=0.

Type: decimal (quantity)

discountAmount

optional

Specifies the amount of fixed-amount discount.

Type: decimal (currency)

discountPercentage

optional

Percentage of discount for a percentage discount. 

Type: decimal

applyDiscountTo

optional

Specifies the type of charges that you want a specific discount to apply to.

Type: string (enum)

Values:

  • ONETIME
  • RECURRING
  • USAGE
  • ONETIMERECURRING
  • ONETIMEUSAGE
  • RECURRINGUSAGE
  • ONETIMERECURRINGUSAGE

discountLevel

optional

Specifies if the discount applies to the product rate plan only , the entire subscription, or to any activity in the account.

Type: string (enum)

Values:

  • rateplan

  • subscription

  • account

triggerEvent

optional

Specifies when to start billing the customer for the charge.

Type: string

Values:

  • UCE
  • USA
  • UCA
  • USD

triggerDate

optional

Specifies when to start billing the customer for the charge. Required if the triggerEvent field is set to USD.

Type: date

endDateCondition

optional

Defines when the charge ends after the charge trigger date. If the subscription ends before the charge end date, the charge ends when the subscription ends. But if the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge will end on the charge end date.

Type: string (enum)

Values:

  • Subscription_End
  • Fixed_Period
  • Specific_End_Date

upToPeriodsType

optional

The period type used to define when the charge ends. 

Type: string (enum)

Values:

  • Billing_Periods
  • Days
  • Weeks
  • Months
  • Years
  • You must use this field together with the upToPeriods field to specify the time period.
  • This field is applicable only when the endDateCondition field is set to Fixed_Period. 

upToPeriods

optional

Specifies the length of the period during which the charge is active. If this period ends before the subscription ends, the charge ends when this period ends.

Type: long

  • You must use this field together with the upToPeriodsType field to specify the time period.
  • This field is only applicable only when the endDateCondition field is set to Fixed_Period. 
  • If the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge end date will change accordingly up to the original period end.

specificEndDate

optional

Defines when the charge ends after the charge trigger date.

Type: date

  • This field is only applicable when the endDateCondition field is set to Specific_End_Date.
  • If the subscription ends before the specific end date, the charge ends when the subscription ends. But if the subscription end date is subsequently changed through a Renewal, or Terms and Conditions amendment, the charge will end on the specific end date.

billingPeriod

optional

Billing period for the charge. The start day of the billing period is also called the bill cycle day (BCD).

Type: string (enum)

Values:

  • Month
  • Quarter
  • Semi_Annual
  • Annual
  • Eighteen_Months
  • Two_Years
  • Three_Years
  • Five_Years
  • Specific_Months
  • Subscription_Term
  • Week
  • Specific_Weeks

specificBillingPeriod

optional

Specifies the number of month or week for the charges billing period. Required if you set the value of the billingPeriod field to Specific_Months or Specific_Weeks.

Type: integer

billingPeriodAlignment

optional

Aligns charges within the same subscription if multiple charges begin on different dates.

Type: string (enum)

Values:

  • AlignToCharge

  • AlignToSubscriptionStart

  • AlignToTermStart

billingTiming

optional

Billing timing for the charge for recurring charge types. Not avaliable for one time, usage and discount charges.

Type: string (enum)

Values:

  • IN_ADVANCE (default)
  • IN_ARREARS

ratingGroup

optional

Specifies a rating group based on which usage records are rated. See Usages Rating by Group for more information.

This feature is in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support

Values:

  • ByBillingPeriod (default): The rating is based on all the usages in a billing period.       
  • ByUsageStartDate: The rating is based on all the usages on the same usage start date. 
  • ByUsageRecord: The rating is based on each usage record.
  • ByUsageUpload: The rating is based on all the usages in a uploaded usage file (.xls or .csv).

Note:

  • The ByBillingPeriod value can be applied for all charge models.
  • The ByUsageStartDate, ByUsageRecord, and ByUsageUpload values can only be applied for per unit, volume pricing, and tiered pricing charge models.
  • Use this field only for Usage charges. One-Time Charges and Recurring Charges return NULL.

billCycleType

optional

Specifies how to determine the billing day for the charge. When this field is set to SpecificDayOfMonth, set the BillCycleDay field. When this field is set to SpecificDayOfWeek, set the weeklyBillCycleDay field.

Type: string (enum)

Values:

  • DefaultFromCustomer
  • SpecificDayOfMonth
  • SubscriptionStartDay
  • ChargeTriggerDay
  • SpecificDayOfWeek

billCycleDay

optional

Sets the bill cycle day (BCD) for the charge. The BCD determines which day of the month customer is billed.

Type: Integer

Values: 1-31

numberOfPeriods

optional

Specifies the number of periods to use when calculating charges in an overage smoothing charge model.

Type: Integer

overageUnusedUnitsCreditOption

optional

Determines whether to credit the customer with unused units of usage.

Type: string (enum)

Values:

  • NoCredit
  • CreditBySpecificRate

unusedUnitsCreditRates

optional

Specifies the rate to credit a customer for unused units of usage. This field applies only for overage charge models when the OverageUnusedUnitsCreditOption field is set to CreditBySpecificRate.

Type: decimal

priceChangeOption

optional

Applies an automatic price change when a termed subscription is renewed. The Z-Billing Admin setting Enable Automatic Price Change When Subscriptions are Renewed?  must be set to Yes to use this field.  See Define Default Subscription Settings for more information on setting this option.

Type: string (enum)

Values:

  • NoChange (default)
  • SpecificPercentageValue
  • UseLatestProductCatalogPricing

priceIncreasePercentage

optional

Specifies the percentage to increase or decrease the price of a termed subscription's renewal. Required if you set the PriceChangeOption field to SpecificPercentageValue.

Type: decimal between -100 and 100

weeklyBillCycleDay

optional

Specifies which day of the week is the bill cycle day (BCD) for the charge. 

Values:

  • Sunday
  • Monday
  • Tuesday
  • Wednesday
  • Thursday
  • Friday
  • Saturday

cf_txtn__c

optional

One or more rate plan charge custom fields

cf_pkn__c

optional

One or more rate plan charge custom fields

Response

success

Contains true if successful, otherwise false.

processId

Internal process ID to assist Zuora support. Only returned if success is false.

reasons

Information on one or more reasons for the result. Only returned if success is false.

code

Eight-digit numeric error code

message

Description of the error

subscriptionId

Subscription ID

subscriptionNumber

Subscription number

invoiceId

Invoice ID, if an invoice is generated during the subscription process

paymentId

Payment ID, if a payment is collected

paidAmount

Payment amount, if a payment is collected

contractedMrr

Monthly recurring revenue of the subscription

totalContractedValue

Total contracted value of the subscription

Notes

If invoiceCollect is true, the call will not return successtrue unless the subscription, invoice, and payment are all successful.

Default values for customerAcceptanceDate and serviceActivationDate are set as follows:

  serviceActivationDate (SA) specified serviceActivationDate (SA) NOT specified

customerAcceptanceDate (CA)

specified

SA uses value in the request call

CA uses value in the request call

CA uses value in the request call

SA uses CE as default

customerAcceptanceDate (CA)

NOT specified

SA uses value in the request call

CA uses SA as default

SA and CA use CE as default
 

Examples

The following JSON and CURL examples show how to create a subscription for an existing customer account. Some fields in the REST methods are supported as of Zuora REST API minor versions. The fields you can specify depends on the REST API minor version you use.

JSON Examples (REST API Minor Version 196.0 and later)

In API minor version 196.0 and later, the invoicecollect field is replaced by the invoice and collect fields. To use the collect and invoice fields,  you must set the zuora-version parameter to the minor version number in the request header. 

Examples are provided based on the following charge models:

JSON Flat Fee Example

HTTP/JSON request:

POST https://api.zuora.com/rest/v1/subscriptions

Request

{
  "renewalTerm": "3",
  "renewalTermPeriodType": "Week",
  "termType": "TERMED",
  "autoRenew": true,
  "invoiceTargetDate": "2015-12-31",
  "accountKey": "A00001115",
  "contractEffectiveDate": "2015-02-1",
  "subscribeToRatePlans":
	[
	 {
       "chargeOverrides":
	   	  [
	        {
	       	  "productRatePlanChargeId": "ff8080811ca15d19011cddad8c953b53",
	       	  "price": 12.01,
	       	  "number":"TestCharge",
	       	  "description":"This is rate plan charge description",
	       	  "triggerEvent":"SpecificDate",
	       	  "triggerDate":"2015-09-01",

	       	  "billingTiming":"IN_ARREARS",
	       	  "billCycleType":"SpecificDayofMonth",
	       	  "billCycleDay":"5",
	       	  "billingPeriodAlignment":"AlignToCharge",
	       	  "myCustomField__c" : "test"
	       		}
	       ],
	    "productRatePlanId": "ff8080811ca15d19011cdda9b0ad3b51"}
	],
  "invoice": true,
  "collect": false,
  "initialTerm": "12",
  "initialTermPeriodType": "Week",
  "notes": "Test POST subscription from z-ruby-sdk",
  "myCustomField__c" : "test"
}

Response:

{
   "success": true,
   "subscriptionId": "402890fc4fa094d5014fa0a4aa78001d",
   "subscriptionNumber": "A-S00000041",
   "contractedMrr": 1950,
   "totalContractedValue": 6227.41935465
}

JSON Tiered Example

HTTP/JSON request:

POST https://api.zuora.com/rest/v1/subscriptions

JSON request:

{
"renewalTerm": "3",
"renewalTermPeriodType": "Week",
"termType": "TERMED",
"autoRenew": true,
"invoiceTargetDate": "2015-12-31",
"accountKey": "A00001115",
"contractEffectiveDate": "2015-02-1",
"subscribeToRatePlans":
 [
  {
 "chargeOverrides":
    [
      {
       "productRatePlanChargeId": "ff8080811ca15d19011cddad8c953b53",
       "quantity": 10,
       "tiers": [
                  { "tier": 1, 
                    "startingUnit": 1, 
                    "endingUnit": 10, 
                    "price": 60, 
                    "priceFormat": 
                    "FlatFee" },
                    
                  { "tier": 2, 
                    "startingUnit": 11, 
                    "endingUnit": 20, 
                    "price":50, 
                    "priceFormat": 
                    "PerUnit" }                                           
                ],
                
       "number":"TestCharge",
       "description":"This is rate plan charge description",
       "triggerCondition":"SpecificDate",
       "triggerDate":"2016-09-01",
       "billingTiming":"IN_ARREARS",
       "billCycleType":"SpecificDayofMonth",
       "billCycleDay":"5",
       "billingPeriodAlignment":"AlignToCharge",
       "myCustomField__c" : "test"
       }
    ],
   "productRatePlanId": "ff8080811ca15d19011cdda9b0ad3b51"}
 ],
"invoice": true,
"collect": false,
"initialTerm": "12",
"initialTermPeriodType": "Week",
"notes": "Test POST subscription from z-ruby-sdk",
"myCustomField__c" : "test"
}

Response:

{
   "success": true,
   "subscriptionId": "402890fc4fa094d5014fa0a4aa78001d",
   "subscriptionNumber": "A-S00000041",
   "contractedMrr": 1950,
   "totalContractedValue": 6227.41935465
}

JSON Examples (REST API Minor Version 189.0 and earlier)

Examples are provided based on the following charge models:

JSON Flat Fee Example

HTTP/JSON request:

POST https://api.zuora.com/rest/v1/subscriptions

Request

{
  "renewalTerm": "3",
  "renewalTermPeriodType": "Week",
  "termType": "TERMED",
  "autoRenew": true,
  "invoiceTargetDate": "2015-12-31",
  "accountKey": "A00001115",
  "contractEffectiveDate": "2015-02-1",
  "subscribeToRatePlans":
	[
	 {
       "chargeOverrides":
	   	  [
	        {
	       	  "productRatePlanChargeId": "ff8080811ca15d19011cddad8c953b53",
	       	  "price": 12.01,
	       	  "number":"TestCharge",
	       	  "description":"This is rate plan charge description",
	       	  "triggerEvent":"SpecificDate",
	       	  "triggerDate":"2015-09-01",

	       	  "billingTiming":"IN_ARREARS",
	       	  "billCycleType":"SpecificDayofMonth",
	       	  "billCycleDay":"5",
	       	  "billingPeriodAlignment":"AlignToCharge",
	       	  "myCustomField__c" : "test"
	       		}
	       ],
	    "productRatePlanId": "ff8080811ca15d19011cdda9b0ad3b51"}
	],
  "invoiceCollect": false,
  "initialTerm": "12",
  "initialTermPeriodType": "Week",
  "notes": "Test POST subscription from z-ruby-sdk",
  "myCustomField__c" : "test"
}

Response:

{
   "success": true,
   "subscriptionId": "402890fc4fa094d5014fa0a4aa78001d",
   "subscriptionNumber": "A-S00000041",
   "contractedMrr": 1950,
   "totalContractedValue": 6227.41935465
}

JSON Tiered Example

HTTP/JSON request:

POST https://api.zuora.com/rest/v1/subscriptions

JSON request:

{
"renewalTerm": "3",
"renewalTermPeriodType": "Week",
"termType": "TERMED",
"autoRenew": true,
"invoiceTargetDate": "2015-12-31",
"accountKey": "A00001115",
"contractEffectiveDate": "2015-02-1",
"subscribeToRatePlans":
 [
  {
 "chargeOverrides":
    [
      {
       "productRatePlanChargeId": "ff8080811ca15d19011cddad8c953b53",
       "quantity": 10,
       "tiers": [
                  { "tier": 1, 
                    "startingUnit": 1, 
                    "endingUnit": 10, 
                    "price": 60, 
                    "priceFormat": 
                    "FlatFee" },
                    
                  { "tier": 2, 
                    "startingUnit": 11, 
                    "endingUnit": 20, 
                    "price":50, 
                    "priceFormat": 
                    "PerUnit" }                                           
                ],
                
       "number":"TestCharge",
       "description":"This is rate plan charge description",
       "triggerCondition":"SpecificDate",
       "triggerDate":"2016-09-01",
       "billingTiming":"IN_ARREARS",
       "billCycleType":"SpecificDayofMonth",
       "billCycleDay":"5",
       "billingPeriodAlignment":"AlignToCharge",
       "myCustomField__c" : "test"
       }
    ],
   "productRatePlanId": "ff8080811ca15d19011cdda9b0ad3b51"}
 ],
"invoiceCollect": false,
"initialTerm": "12",
"initialTermPeriodType": "Week",
"notes": "Test POST subscription from z-ruby-sdk",
"myCustomField__c" : "test"
}

Response:

{
   "success": true,
   "subscriptionId": "402890fc4fa094d5014fa0a4aa78001d",
   "subscriptionNumber": "A-S00000041",
   "contractedMrr": 1950,
   "totalContractedValue": 6227.41935465
}

CURL Example

CURL request:

##
## Create Subscription
##
echo
echo "=============Create subscription============="
echo
curl -i -k -H "apiAccessKeyId:$USER_NAME" -H "apiSecretAccessKey:$PASSWORD" -H "Content-Type:application/json" -H "Accept:application/json" -d '
{
  "accountKey":"A00000001",
  "contractEffectiveDate": "2013-03-01",
  "termType":"TERMED",
  "initialTerm":12,
  "initialTermPeriodType": "Week",
  "autoRenew":true,
  "renewalTerm":12,
  "renewalTermPeriodType": "Week",
  "notes":"test subscription",
  "subscribeToRatePlans":[
    {
      "productRatePlanId": "ff808081298c6e5401298c784faa0073",
      "chargeOverrides":[
        {"productRatePlanChargeId":"ff808081298c6e5401298c79727f0077", "quantity":10}
      ]
    }
  ],
  "invoiceTargetDate": "2013-12-01"
}
' -X POST $BASE_URL/v1/subscriptions

JSON response:

{
  "subscriptionNumber": "A-S00001084",
  "success": true,
  "subscriptionId": "2c92c8f83dcbd8b1013dcce0ead40071"
}
Last modified
21:44, 7 Jul 2016

Tags

Classifications

(not set)