Knowledge Center

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

Preview subscription

The REST API reference describes how to create a new subscription in preview mode. This call does not require a valid customer account. It can be used to show potential new customers a preview of a subscription with complete details and charges before creating an account, or to let existing customers preview a subscription with all charges before committing.

Request

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

Request body

accountKey

optional

Customer account number or ID.

You must specify the account information either in this field or in the previewAccountInfo field with the following conditions:

  • If you already have a customer account, specify the account number or ID in this field.
  • If you do not have a customer account, provide account information in the previewAccountInfo field.

previewAccountInfo

optional

A container for providing a customer account information if you do not have an existing customer account. This customer account information is only used for subscription preview.

You must specify the account information either in this field or in the accountKey field

 with the following conditions:

  • If you already have a customer account, specify the account number or ID in the accountKey field.
  • If you do not have a customer account, provide account information in this field.

This container contains the following fields.

currency

optional

A currency as defined in Z-Billing Settings in the Zuora UI

billCycleDay

required

The account's bill cycle day (BCD), when bill runs generate invoices for the account.  Specify any day of the month (1-31, where 31 = end-of-month), or 0 for auto-set.

billToContact

required

Container for bill-to contact information of this account. 

It contains the following fields:

  • city: (optional) The city of the bill-to address. The value should be 40 characters or less.
  • county: (conditional) The country of the bill-to address. The value must be a valid country name or abbreviation
  • state: (optional) The state of the bill-to address. The value must be a valid state or province name or 2-character abbreviation.
  • taxRegion: (optional) If using Z-Tax, a region string as optionally defined in your tax rules. 
  • zipCode: (optional) The zip code of the bill-to address. The value should be 20 characters or less.
  • country: (optional) The county of the bill-to address. The value should be 32 characters or less. 

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

Duration of the first term of the subscription, in whole months. 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 of the initial term. 

Supported values are:

  • Month
  • Year
  • Day
  • Week

notes

optional

String of up to 500 characters

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.

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 subscription previews.

Values

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

subscribeToRatePlans

required 

Container for one or more rate plans for this subscription.

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)

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

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

amount

Invoice amount

amountWithoutTax

Invoice amount minus tax

taxAmount

Tax amount on the invoice

invoiceTargetDate

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

invoiceItems

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

contractedMrr

Monthly recurring revenue of the subscription

totalContractedValue

Total contracted value of the subscription

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

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

CURL request:

HTTP/JSON request:

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

JSON request:

{
  "termType": "TERMED",
  "invoiceTargetDate": "2013-12-31",
  "contractEffectiveDate": "2013-1-15",
  "previewAccountInfo":
    {"currency": "USD",
     "billToContact":
      {"zipCode": "94549",
       "country": "United States",
       "city": "Walnut Creek",
       "county": "Contra Consta",
       "state": "California"},
     "billCycleDay": 31},
  "subscribeToRatePlans":
    [{"chargeOverrides":
       [{"productRatePlanChargeId": "ff8080811ca15d19011cddad8c953b53",
         "quantity": 100}],
      "productRatePlanId": "ff8080811ca15d19011cdda9b0ad3b51"}],
  "initialTerm": 12,
  "initialTermPeriodType": "Week"
}
JSON response:
{
  "success": true,
  "amountWithoutTax": 16695.65,
  "amount": 16695.65,
  "invoiceTargetDate": "2013-12-31",
  "taxAmount": 0.0,
  "invoiceItems": [
    {
      "unitOfMeasure": "ONE_DOWN",
      "serviceStartDate": "2013-01-15",
      "chargeName": "TieredPrice",
      "chargeDescription": "",
      "chargeAmount": 695.65,
      "serviceEndDate": "2013-01-30",
      "productName": "Recurring Charge",
      "productRatePlanChargeId": "2c9081a03c6d7b51013c6d7c6373000b",
      "quantity": 100.0
    },
    {
      "unitOfMeasure": "",
      "serviceStartDate": "2013-01-15",
      "chargeName": "TieredPrice Prepayment Charge",
      "chargeDescription": null,
      "chargeAmount": 8000.0,
      "serviceEndDate": "2013-01-15",
      "productName": null,
      "quantity": 1
    },
    {
      "unitOfMeasure": "ONE_DOWN",
      "serviceStartDate": "2013-01-31",
      "chargeName": "TieredPrice",
      "chargeDescription": "",
      "chargeAmount": 4000.0,
      "serviceEndDate": "2013-04-29",
      "productName": "Recurring Charge",
      "quantity": 100.0
    },
    {
      "unitOfMeasure": "ONE_DOWN",
      "serviceStartDate": "2013-04-30",
      "chargeName": "TieredPrice",
      "chargeDescription": "",
      "chargeAmount": 4000.0,
      "serviceEndDate": "2013-07-30",
      "productName": "Recurring Charge",
      "quantity": 100.0
    },
    {
      "unitOfMeasure": "ONE_DOWN",
      "serviceStartDate": "2013-07-31",
      "chargeName": "TieredPrice",
      "chargeDescription": "",
      "chargeAmount": 4000.0,
      "serviceEndDate": "2013-10-30",
      "productName": "Recurring Charge",
      "quantity": 100.0
    },
    {
      "unitOfMeasure": "ONE_DOWN",
      "serviceStartDate": "2013-10-31",
      "chargeName": "TieredPrice",
      "chargeDescription": "",
      "chargeAmount": 4000.0,
      "serviceEndDate": "2014-01-30",
      "productName": "Recurring Charge",
      "quantity": 100.0
    },
    {
      "unitOfMeasure": "ONE_DOWN",
      "serviceStartDate": "2013-04-30",
      "chargeName": "TieredPrice",
      "chargeDescription": "",
      "chargeAmount": -3304.35,
      "serviceEndDate": "2013-07-30",
      "productName": "Recurring Charge",
      "quantity": 1
    },
    {
      "unitOfMeasure": "ONE_DOWN",
      "serviceStartDate": "2013-01-31",
      "chargeName": "TieredPrice",
      "chargeDescription": "",
      "chargeAmount": -4000.0,
      "serviceEndDate": "2013-04-29",
      "productName": "Recurring Charge",
      "quantity": 1
    },
    {
      "unitOfMeasure": "ONE_DOWN",
      "serviceStartDate": "2013-01-15",
      "chargeName": "TieredPrice",
      "chargeDescription": "",
      "chargeAmount": -695.65,
      "serviceEndDate": "2013-01-30",
      "productName": "Recurring Charge",
      "quantity": 1
    }
  ]
}

CURL request:

##
## Subscription Preview
##
echo
echo "=============Preview Subscription============="
echo
curl -i -k -H "apiAccessKeyId:$USER_NAME" -H "apiSecretAccessKey:$PASSWORD" -H "Content-Type:application/json" -H "Accept:application/json" -d '
{
    "accountKey":"A00000001",
    "termType":"TERMED",
    "initialTerm":15,
    "initialTermPeriodType": "Week",
    "subscribeToRatePlans":[
        {
            "productRatePlanId":"ff808081298c6e5401298c784faa0073",
            "chargeOverrides":[
                {
                    "productRatePlanChargeId":"ff808081298c6e5401298c79727f0077",
                    "quantity":7
                }
            ]
        }
    ],
    "contractEffectiveDate":"2013-08-01",
    "invoiceTargetDate":"2013-12-20"
}
' -X POST $BASE_URL/v1/subscriptions/preview

JSON response:

{
  "success": true,
  "amountWithoutTax": 16695.65,
  "amount": 16695.65,
  "invoiceTargetDate": "2013-12-31",
  "taxAmount": 0.0,
  "invoiceItems": [
    {
      "unitOfMeasure": "ONE_DOWN",
      "serviceStartDate": "2013-01-15",
      "chargeName": "TieredPrice",
      "chargeDescription": "",
      "chargeAmount": 695.65,
      "serviceEndDate": "2013-01-30",
      "productName": "Recurring Charge",      
      "productRatePlanChargeId": "2c9081a03c6d7b51013c6d7c6373000b",
      "quantity": 100.0
    },
    {
      "unitOfMeasure": "",
      "serviceStartDate": "2013-01-15",
      "chargeName": "TieredPrice Prepayment Charge",
      "chargeDescription": null,
      "chargeAmount": 8000.0,
      "serviceEndDate": "2013-01-15",
      "productName": null,
      "quantity": 1
    },
    {
      "unitOfMeasure": "ONE_DOWN",
      "serviceStartDate": "2013-01-31",
      "chargeName": "TieredPrice",
      "chargeDescription": "",
      "chargeAmount": 4000.0,
      "serviceEndDate": "2013-04-29",
      "productName": "Recurring Charge",
      "quantity": 100.0
    },
    {
      "unitOfMeasure": "ONE_DOWN",
      "serviceStartDate": "2013-04-30",
      "chargeName": "TieredPrice",
      "chargeDescription": "",
      "chargeAmount": 4000.0,
      "serviceEndDate": "2013-07-30",
      "productName": "Recurring Charge",
      "quantity": 100.0
    },
    {
      "unitOfMeasure": "ONE_DOWN",
      "serviceStartDate": "2013-07-31",
      "chargeName": "TieredPrice",
      "chargeDescription": "",
      "chargeAmount": 4000.0,
      "serviceEndDate": "2013-10-30",
      "productName": "Recurring Charge",
      "quantity": 100.0
    },
    {
      "unitOfMeasure": "ONE_DOWN",
      "serviceStartDate": "2013-10-31",
      "chargeName": "TieredPrice",
      "chargeDescription": "",
      "chargeAmount": 4000.0,
      "serviceEndDate": "2014-01-30",
      "productName": "Recurring Charge",
      "quantity": 100.0
    },
    {
      "unitOfMeasure": "ONE_DOWN",
      "serviceStartDate": "2013-04-30",
      "chargeName": "TieredPrice",
      "chargeDescription": "",
      "chargeAmount": -3304.35,
      "serviceEndDate": "2013-07-30",
      "productName": "Recurring Charge",
      "quantity": 1
    },
    {
      "unitOfMeasure": "ONE_DOWN",
      "serviceStartDate": "2013-01-31",
      "chargeName": "TieredPrice",
      "chargeDescription": "",
      "chargeAmount": -4000.0,
      "serviceEndDate": "2013-04-29",
      "productName": "Recurring Charge",
      "quantity": 1
    },
    {
      "unitOfMeasure": "ONE_DOWN",
      "serviceStartDate": "2013-01-15",
      "chargeName": "TieredPrice",
      "chargeDescription": "",
      "chargeAmount": -695.65,
      "serviceEndDate": "2013-01-30",
      "productName": "Recurring Charge",
      "quantity": 1
    }
  ]
}
Last modified
23:23, 14 Mar 2016

Tags

Classifications

(not set)