Knowledge Center

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

Update subscription

 

Use this call to make the following kinds of changes to a subscription:

  • Add a note
  • Change the renewal term or auto-renewal flag
  • Change the term length or change between evergreen and termed
  • Add a new product rate plan
  • Remove an existing subscription rate plan
  • Change the quantity or price of an existing subscription rate plan

Request

  • Production: PUT https://api.zuora.com/rest/v1/subscriptions/{subscription-key}
  • API Sandbox: PUT https://apisandbox-api.zuora.com/rest/v1/subscriptions/{subscription-key}

Request parameters

subscription-key

required

path

Subscription number or ID

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

termType

optional

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

currentTerm

optional

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

currentTermPeriodType

optional

The period type for the current subscription term.

This field is used with the CurrentTerm field to specify the current subscription term.

Values are:

  • Month (default)
  • Year
  • Day
  • Week

termStartDate

optional

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

renewalSetting

optional

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

Values are:

  • RENEW_WITH_SPECIFIC_TERM (default)
  • RENEW_TO_EVERGREEN

renewalTerm

optional

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

renewalTermPeriodType

optional

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

autoRenew

optional

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

notes

optional

String of up to 500 characters

cf_txtn__c

optional

One or more optional custom fields.

cf_pkn__c

optional

One or more optional custom fields.

add 

optional

Container for adding one or more rate plans:

productRatePlanId

required

ID of a product rate plan for this subscription

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)

Supports all charge types for the Flat Fee and Per Unit charge models

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

Do not include this field if overriding a specific tier. See Update subscription for example requests.

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

Available for the following charge types for the Overage charge model:

  • Recurring
  • Usage-based

overagePrice

​optional

Price for units over the allowed amount. 

Type: decimal (currency)

Available for the following charge type for the Overage and Tiered with Overage charge models:

  • Usage-based

listPriceBase

​optional

The list price base for the product rate plan charge.

Type: string

Values:

  • Per_Billing_Period
  • Per_Month
  • Per_Week

Available for the following charge type for the Flat Fee, Per Unit, Volume Pricing, and Tiered Pricing charge models:

  • Recurring

quantity

optional

Number of units. Must be >=0.

Type: decimal (quantity)

Available for the following charge types for the Per Unit, Volume Pricing, and Tiered Pricing charge models:

  • One-time
  • Recurring

discountAmount

optional

Specifies the amount of fixed-amount discount.

Type: decimal (currency)

Available for the following charge type for the Discount-Fixed Amount charge model:

  • Recurring

discountPercentage

optionla

Specifies the percentage of a percentage discount. 

Type: decimal (currency)

Available for the following charge type for the Discount-Percentage charge model:

  • Recurring

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

Available for the following charge type for the Discount-Fixed Amount and Discount-Percentage charge models:

  • Recurring

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

Available for the following charge type for the Discount-Fixed Amount and Discount-Percentage charge models:

  • Recurring

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.

Available for the following charge type for the Discount-Fixed Amount and Discount-Percentage charge models:

  • Recurring

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

Available for the following charge types:

  • Recurring
  • Usage-based

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

Available for the following charge types:

  • Recurring
  • Usage-based

billingPeriodAlignment

optional

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

Type: string (enum)

Values:

  • AlignToCharge

  • AlignToSubscriptionStart

  • AlignToTermStart

Available for the following charge types:

  • Recurring
  • Usage-based

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

Available for the following charge types:

  • Recurring
  • Usage-based

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

Available for the following charge types:

  • Recurring
  • Usage-based

numberOfPeriods

optional

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

Type: Integer

Available for the following charge type for the Overage and Tiered with Overage charge models:

  • Usage-based

overageUnusedUnitsCreditOption

optional

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

Type: string (enum)

Values:

  • NoCredit
  • CreditBySpecificRate

Available for the following charge type for the Overage and Tiered with Overage charge models:

  • Usage-based

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

Available for the following charge type for the Overage and Tiered with Overage charge models:

  • Usage-based

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

Available for the following charge types:

  • Recurring
  • Usage-based

Not available for the Fixed-Amount Discount charge model.

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

Available for the following charge types:

  • Recurring
  • Usage-based

Not available for the Fixed-Amount Discount charge model.

cf_txtn__c

optional

cf_txtn__c

optional

cf_pkn__c

optional

One or more rate plan charge custom fields

contractEffectiveDate

required

Effective date of the new subscription, as yyyy-mm-dd

serviceActivationDate

optional

The date when the new product in the subscription is activated in yyyy-mm-dd format.

You must specify a Service Activation date if the Customer Acceptance date is set. If the Customer Acceptance date is not set, the value of the serviceActivationDate field defaults to be the Contract Effective Date.

The billing trigger dates must follow this rule:

contractEffectiveDate <= serviceActivationDate <= contractAcceptanceDate

customerAcceptanceDate

optional

The date when the customer accepts the contract in yyyy-mm-dd format.

If this field is not set:

  • If the serviceActivationDate field is not set, the value of this field is set to be the contract effective date.
  • If the serviceActivationDate field is set, the value of this field is set to be the service activation date.

The billing trigger dates must follow this rule:

contractEffectiveDate <= serviceActivationDate <= contractAcceptanceDate

cf_txtn__c

optional

One or more optional custom fields

cf_pkn__c

optional

One or more optional custom fields

update 

optional

Container for updating one or more rate plans:

ratePlanId

required

ID of a rate plan for this subscription

chargeUpdateDetails

optional

 

Container for one or more product rate plan charges

ratePlanChargeId

required

ID of a rate-plan charge for this subscription

description

optional

Description of the charge.  

Type: String up to 500 characters

quantity

optional

Quantity of units; must be greater than zero

price

optional

Price for units in the subscription rate plan.

Type: decimal (currency)

Supports all charge types for the Flat Fee and Per Unit charge models

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

Do not include this field if overriding a specific tier. See Update subscription for example requests.

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

Available for the following charge types for the Overage charge model:

  • Recurring
  • Usage-based

overagePrice

​optional

Price for units over the allowed amount. 

Type: decimal (currency)

Available for the following charge type for the Overage and Tiered with Overage charge models:

  • Usage-based

triggerEvent

optional

Specifies when to start billing the customer for the charge.

Type: string

Values:

  • UCE
  • USA
  • UCA
  • USD

This is the date when charge changes in the REST request become effective.

triggerEvent cannot be updated for the following using the REST update subscription call:

  • One-time charge type
  • Discount-Fixed Amount charge model
  • Discount-Percentage charge model

triggerDate

optional

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

Type: date

triggerDate cannot be updated for the following using the REST update subscription call:

  • One-time charge type
  • Discount-Fixed Amount charge model
  • Discount-Percentage charge model

billingPeriodAlignment

optional

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

Type: string (enum)

Values:

  • AlignToCharge

  • AlignToSubscriptionStart

  • AlignToTermStart

Available for the following charge types:

  • Recurring
  • Usage-based

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

Available for the following charge types:

  • Recurring
  • Usage-based

Not available for the Fixed-Amount Discount charge model.

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

Available for the following charge types:

  • Recurring
  • Usage-based

Not available for the Fixed-Amount Discount charge model.

cf_txtn__c

optional

One or more optional custom fields.

cf_pkn__c

optional

One or more optional custom fields.

contractEffectiveDate

required

The date when the amendment changes take effect. The format of the date is yyyy-mm-dd.

If there is already a future-dated Update Product amendment on the subscription, the specificUpdateDate field will be used instead of this field to specify when the Update Product amendment takes effect.

serviceActivationDate

optional

The date when the update amendment is activated in yyyy-mm-dd format.

You must specify a Service Activation date if the Customer Acceptance date is set. If the Customer Acceptance date is not set, the value of the serviceActivationDate field defaults to be the Contract Effective Date.

The billing trigger dates must follow this rule:

contractEffectiveDate <= serviceActivationDate <= contractAcceptanceDate

customerAcceptanceDate

optional

The date when the customer accepts the contract in yyyy-mm-dd format.

If this field is not set:

  • If the serviceActivationDate field is not set, the value of this field is set to be the contract effective date.
  • If the serviceActivationDate field is set, the value of this field is set to be the service activation date.

The billing trigger dates must follow this rule:

contractEffectiveDate <= serviceActivationDate <= contractAcceptanceDate

specificUpdateDate

conditional

The date when the Update Product amendment takes effect. This field is only applicable if there is already a future-dated Update Product amendment on the subscription. The format of the date is yyyy-mm-dd.

Req​uired: Only for Update Product amendments if there is already a future-dated Update Product amendment on the subscription.

cf_txtn__c

optional

One or more optional custom fields

cf_pkn__c

optional

One or more optional custom fields

remove

optional

Container for removing one or more rate plans:

ratePlanId

required

ID of a rate-plan charge for this subscription

contractEffectiveDate

required

Effective date of the new subscription, as yyyy-mm-dd

serviceActivationDate

optional

The date when the remove amendment is activated in yyyy-mm-dd format.

You must specify a Service Activation date if the Customer Acceptance date is set. If the Customer Acceptance date is not set, the value of the serviceActivationDate field defaults to be the Contract Effective Date.

The billing trigger dates must follow this rule:

contractEffectiveDate <= serviceActivationDate <= contractAcceptanceDate

customerAcceptanceDate

optional

The date when the customer accepts the contract in yyyy-mm-dd format.

If this field is not set:

  • If the serviceActivationDate field is not set, the value of this field is set to be the contract effective date.
  • If the serviceActivationDate field is set, the value of this field is set to be the service activation date.

The billing trigger dates must follow this rule:

contractEffectiveDate <= serviceActivationDate <= contractAcceptanceDate

invoiceCollect

optional

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

If true, an invoice is generated and payment collected automatically during the subscription process. If false (default), 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 false

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 false.
Prerequisite: invoice 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.

preview

optional

If true the update is made in preview mode. The default setting is false.

previewType

optional

The type of preview you will receive. The possible values are InvoiceItem, ChargeMetrics, or InvoiceItemChargeMetrics. The default is InvoiceItem.

 

includeExistingDraftInvoiceItems

optional

Specifies whether to include draft invoice items in amendment previews.
Values

  • true (default). Includes draft invoice items in amendment previews. 
  • false. Excludes draft invoice items in amendment previews.

​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

The ID of the resulting new subscription

invoiceId

Invoice ID, if an invoice is generated during the update

paymentId

Payment ID, if a payment is collected

paidAmount

Payment amount, if a payment is collected

totalDeltaMrr

Change in the subscription monthly recurring revenue as a result of the update

totalDeltaTcv

Change in the total contracted value of the subscription as a result of the update

amount

preview mode only

Invoice amount

amountWithoutTax

preview mode only

Invoice amount minus tax

taxAmount

preview mode only

Tax amount on the invoice

invoiceTargetDate

preview mode only

Date through which charges are calculated on the invoice, as yyyy-mm-dd

invoiceItems

preview mode only

Container for invoice items: 

serviceStartDate

Service start date as yyyy-mm-dd. If the charge is a one-time fee, this is the date of that charge.

serviceEndDate

End date of the service period for this item, i.e., the last day of the period, as yyyy-mm-dd

chargeAmount

The amount of the charge. This amount doesn't include taxes unless the charge's tax mode is inclusive.

chargeDescription

Description of the charge

chargeName

Name of the charge

productName

Name of the product associated with this item

productRatePlanChargeId

ID of the product rate plan charge

quantity

Quantity of this item

unitOfMeasure

Unit of measure; these are configured in the web-based UI: Z-Billing > Settings

chargeMetrics

Container for charge metrics:

productRatePlanId The product rate plan ID.
productRatePlanChargeId The product rate plan charge ID.
originRatePlanId The origin rate plan ID. Only available for update subscription. 
originalId The original rate plan charge ID. Only available for update subscription. 
number The charge number of the subscription. Only available for update subscription. 
mrr Monthly recurring revenue
dmrr Change in monthly recurring revenue
tcv Total contract value
dtcv Change in total contract value

​Notes

  • The Update Subscription call creates a new subscription, which has the old subscription number but a new subscription ID.  The old subscription is canceled but remains in the system.
  • In one request, this call can make:
    • Up to 9 combined add, update, and remove changes
    • No more than 1 change to terms & conditions
  • Updates are performed in the following sequence:
    1. First change the notes on the existing subscription, if requested.
    2. Then change the terms and conditions, if requested.
    3. Then perform the remaining amendments based upon the effective dates specified. If multiple amendments have the same contract-effective dates, then execute adds before updates, and updates before removes.
  • The update operation is atomic. If any of the updates fails, the entire operation is rolled back.

Override a Tiered Price

There are two ways you override a tiered price:

  • Override a specific tier number

For example: tiers[{tier:1,price:8},{tier:2,price:6}]

  • Override the entire tier structure

For example: 

tiers[{tier:1,price:8,startingUnit:1,endingUnit:100,priceFormat:"FlatFee"},

{tier:2,price:6,startingUnit:101,priceFormat:"FlatFee"}]

If you just override a specific tier, do not include the startingUnit field in the request.

Examples

The following JSON and CURL examples show how to update 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. 

HTTP request:

PUT https://api.zuora.com/rest/v1/subscriptions/A-S00001084

JSON request:

{"renewalTerm": "4",
"renewalTermPeriodType": "Month",
"termType": "TERMED",
"autoRenew": false,
"renewalSetting": "RENEW_WITH_SPECIFIC_TERM",
"currentTerm": "10",
"currentTermPeriodType": "Month",
"update":
  [{"ratePlanId": "2c92c8f83dcbd8b1013dcce0ea7e006f",
    "contractEffectiveDate": "2013-04-28",
    "chargeUpdateDetails":
     [{"ratePlanChargeId": "2c92c8f83dcbd8b1013dcce0eb510075",
       "quantity": 12}]}],
"notes": "Test UPDATE subscription from z-ruby-sdk",
"myCustomField__c" : "test",
"invoice": true,
"collect": false
}
JSON response:
{
  "success" : true,
  "subscriptionId" : "4028bb83510f8ed7015114a503cf0373",
  "totalDeltaMrr" : 100.000000000,
  "totalDeltaTcv" : 4867.741935500
}

JSON Examples (REST API Minor Version 189.0 and earlier)

HTTP request:

PUT https://api.zuora.com/rest/v1/subscriptions/A-S00001084

JSON request:

{"renewalTerm": "4",
"renewalTermPeriodType": "Month",
"termType": "TERMED",
"autoRenew": false,
"renewalSetting": "RENEW_WITH_SPECIFIC_TERM",
"currentTerm": "10",
"currentTermPeriodType": "Month",
"update":
  [{"ratePlanId": "2c92c8f83dcbd8b1013dcce0ea7e006f",
    "contractEffectiveDate": "2013-04-28",
    "chargeUpdateDetails":
     [{"ratePlanChargeId": "2c92c8f83dcbd8b1013dcce0eb510075",
       "quantity": 12}]}],
"notes": "Test UPDATE subscription from z-ruby-sdk",
"myCustomField__c" : "test"'
"invoiceCollect": false
}
JSON response:
{
  "success" : true,
  "subscriptionId" : "4028bb83510f8ed7015114a503cf0373",
  "totalDeltaMrr" : 100.000000000,
  "totalDeltaTcv" : 4867.741935500
}

CURL Example

CURL request:

##
## Update Subscription
##
echo
echo "=============Update subscription============="
echo
curl -i -k -H "apiAccessKeyId:$USER_NAME" -H "apiSecretAccessKey:$PASSWORD" -H "Content-Type:application/json" -H "Accept:application/json" -d '
{
    "termType": "TERMED",
    "currentTerm": 20,
    "currentTermPeriodType": "Month",
    "renewalTerm": 20,
    "renewalTermPeriodType": "Month",
    "autoRenew": false,
    "renewalSetting": "RENEW_WITH_SPECIFIC_TERM",
    "notes": "some new notes",
    "add": [
        {
            "productRatePlanId": "",
            "chargeOverrides": [
                {
                    "productRatePlanChargeId": "",
                    "quantity": ""
                }
            ],
            "contractEffectiveDate": "yyyy-mm-dd"
        }
    ],
    "update": [
        {
            "ratePlanId": "",
            "chargeUpdateDetails": [
                {
                    "ratePlanChargeId": "",
                    "quantity": ""
                }
            ],
            "contractEffectiveDate": "yyyy-mm-dd"
        }
    ],
    "remove": [
        {
            "ratePlanId": "",
            "contractEffectiveDate": "yyyy-mm-dd"
        }
    ],
   "invoiceCollect":true|false,
   "invoiceTargetDate":"yyyy-mm-dd",
}
' -X PUT $BASE_URL/v1/subscriptions/ff808081298c6e5401298c7a845c007b

 

Last modified
00:35, 19 Apr 2016

Tags

Classifications

(not set)