Knowledge Center

Knowledge Center > API > REST API > REST API Reference > Subscriptions > Get subscriptions by key

Get subscriptions by key

This REST API reference describes how to retrieve detailed information about a specified subscription in the latest version.

Request

  • Production: GET https://api.zuora.com/rest/v1/subscriptions/{subscription-key}?charge-detail={charge-detail}​
  • API Sandbox: GET https://apisandbox-api.zuora.com/rest/v1/subscriptions/{subscription-key}?charge-detail={charge-detail}​

Request parameters

subscription-key

required

path

Possible values are:

  • a subscription number
  • a subscription ID

charge-detail

optional

query

The segmented rate plan charges.

When an amendment results in a change to a charge, Zuora creates a segmented rate plan charge. Use this field to track segment charges.

Possible values are:

  • last-segment: (Default) The last rate plan charge on the subscription. The last rate plan charge is the last one in the order of time on the subscription rather than the most recent changed charge on the subscription.
  • current-segment: The segmented charge that is active on today’s date (effectiveStartDate <= today’s date < effectiveEndDate).
  • all-segments: All the segmented charges.
  • specific-segment&as-of-date=date: The segmented charge that is active on a date you specified (effectiveStartDate <= specific date < effectiveEndDate). The format of the date is yyyy-mm-dd.

Response

success

Contains true if successful, otherwise false.

id

Internal process ID to assist Zuora support.

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

subscriptions

Contains information about the subscriptions. 

id Subscription ID
accountId Account ID
accountNumber Account number associated with the subscription key.
accountName Account name
subscriptionNumber Subscription number
termType Possible values are: TERMED, EVERGREEN. See Subscriptions for more information
contractEffectiveDate Effective contract date for this subscription, as yyyy-mm-dd

currentTerm

The length of the period for the current subscription term. 

currentTermPeriodType

The period type for the current subscription term.

Values are:

  • Month (default)
  • Year
  • Day
  • Week
serviceActivationDate 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
customerAcceptanceDate The date on which the services or products within a subscription have been accepted by the customer, as yyyy-mm-dd
subscriptionStartDate Date the subscription becomes effective
termStartDate Date the subscription term begins. If this is a renewal subscription, this date is different from the subscription start date.
termEndDate Date the subscription term ends. If the subscription is evergreen, this is null or is the cancellation date (if one has been set).
initialTerm The length of the period for the first subscription term.
initialTermPeriodType The period type for the first subscription term.

Values are:

  • Month (default)
  • Year
  • Day
  • Week
autoRenew If true, the subscription automatically renews at the end of the term. Default is false.

renewalSetting

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 The length of the period for the subscription renewal term.

renewalTermPeriodType

The period type for the subscription renewal term.

Values are:

  • Month (default)
  • Year
  • Day
  • Week
contractedMrr Monthly recurring revenue of the subscription
totalContractedValue Total contracted value of the subscription
notes A string of up to 65,535 characters

status

Subscription status; possible values are:

  • Draft
  • PendingActivation
  • PendingAcceptance
  • Active
  • Cancelled
  • Expired
  • Suspended (This value is in Limited Availability.)

You can only track expired subscriptions when using subscription IDs in the Get Subscriptions request.

invoiceSeparately

Separates a single subscription from other subscriptions and creates an invoice for the subscription. 

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.

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 One or more custom fields
cf_pkn__c One or more custom fields

ratePlans

Container for rate plans:

id Rate plan ID

lastChangeType

The last amendment on the rate plan.

Possible Values:

  • Add
  • Update
  • Remove
productId Product ID
productName Product name

productSku

The unique SKU for the product.
ProductRatePlanId The ID of the product rate plan associated with this product rate plan.\
ratePlanName Name of the rate plan
cf_txtn__c One or more rate plan custom fields
cf_pkn__c One or more rate plan custom fields

ratePlanCharges

Container for one or more charges:

id Rate plan charge ID
originalChargeId The original ID of the rate plan charge.
productRatePlanChargeId Product rate plan charge ID
number Charge number
name Charge name
type Charge type;
possible values are: 
OneTime, Recurring, Usage.
model

Charge model; possible values are:

  • FlatFee
  • PerUnit
  • Overage
  • Volume
  • Tiered
  • TieredWithOverage
  • DiscountFixedAmount
  • DiscountPercentage
uom Specifies the units to measure usage. Units of measure are configured in the web-based UI: Z-Billing > Settings.
version The version of the rate plan.
pricingSummary Concise description of rate plan charge model
priceChangeOption

When the following is true:

  1. AutomatedPriceChange setting is on

  2. Charge type is not one-time

  3. Charge model is not discount percentage

Then an automatic price change can have a value for when a termed subscription is renewed.
Values (one of the following):

  • NoChange (default)

  • SpecificPercentageValue

  • UseLatestProductCatalogPricing

priceIncreasePercentage A planned future price increase amount as a percentage.
currency Currency used by the account. For example: USD or EUR
price The price associated with the rate plan charge expressed as a decimal when the rate plan is not a tiered type.

Tiers

Container for one or many defined tier ranges with distinct pricing.  Applies when model is TieredTieredWithOverage, or Volume.

tier

Unique number of the tier

startingUnit

Decimal defining start of tier range

endingUnit

Decimal defining end of tier range

price

The decimal value of the tiered charge model. If the charge model is not a tiered type then this price field will be null and the price field directly under the productRatePlanCharges applies.

priceFormat

Tier price format.

Allowed values:

  • flat fee
  • per unit
includedUnits

 Specifies the number of units in the base set of units.

OveragePrice The price for units over the allowed amount.
discountPercentage The amount of the discount as a percentage.
discountAmount The amount of the discount.
applyDiscountTo

Specifies the type of charges a specific discount applies to. 

This field is only used when applied to a discount charge model. If you are not using a discount charge model, the value is null.

Possible values:

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

discountLevel

The level of the discount. Values:

  • RatePlan
  • Subscription
  • Account

billingDay

Billing cycle day (BCD), which is when bill runs generate invoices
for charges associated with the product rate plan charge or the account.  Possible values are:

  • DefaultFromCustomer
  • SpecificDayofMonth(#)
  • SubscriptionStartDay
  • ChargeTriggerDay
  • SpecificDayOfWeek/dayofweek : dayofweek is the day in the week you define your billing periods to start.

In the response data, a day-of-the-month value (1-31) appears in place of the hash sign above ("#"). If this value exceeds the number of days in a particular month, the last day of the month is used as the BCD.

listPriceBase

List price base. Possible values are:

  • Per_Billing_Period
  • Per_Month
  • Per_Week
billingPeriod

Allows billing period to be overridden on rate plan charge. specificBillingPeriod Customizes the number of month or week for the charges billing period. This field is required if you set the value of the BillingPeriod field to Specific Months or Specific_Weeks.

specificBillingPeriod Customizes the number of month or week for the charges billing period. This field is required if you set the value of the BillingPeriod field to Specific Months or Specific_Weeks.

billingPeriodAlignment

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

  • AlignToCharge
  • AlignToSubscriptionStart
  • AlignToTermStart
quantity

 The quantity of units, such as the number of authors in a hosted wiki service. Valid for all charge models except for Flat Fee pricing. smoothingModel

Specifies when revenue recognition begins. When charge model is Overage or TieredWithOverage smoothingModel will be one of the following values:

  • ContractEffectiveDate
  • ServiceActivationDate
  • CustomerAcceptanceDate
smoothingModel

Specifies when revenue recognition begins. When charge model is Overage or TieredWithOverage smoothingModel will be one of the following values:

  • ContractEffectiveDate
  • ServiceActivationDate
  • CustomerAcceptanceDate
numberOfPeriods

Specifies the number of periods to use when calculating charges in an overage smoothing charge model. overageCalculationOption Determines when to calculate overage charges. overageUnusedUnitsCreditOption Determines whether to credit the customer with unused units of usage. unusedUnitsCreditRates Specifies the rate to credit a customer for unused units of usage. This field is applicable only for overage charge models when the OverageUnusedUnitsCreditOption field value is CreditBySpecificRate. usageRecordRatingOption Determines how Zuora processes usage records for per-unit usage charges.  segment The identifying number of the subscription rate plan segment. Segments are numbered sequentially, starting with 1. effectiveStartDate The effective start date of the rate plan charge. effectiveEndDate The effective end date of the rate plan charge. processedThroughDate

The date until when charges have been processed.

When billing in arrears, such as usage, this field value is the the same as the ChargedThroughDate value. This date is the earliest date when a charge can be amended.

overageCalculationOption Determines when to calculate overage charges.
overageUnusedUnitsCreditOption Determines whether to credit the customer with unused units of usage.
unusedUnitsCreditRates Specifies the rate to credit a customer for unused units of usage. This field is applicable only for overage charge models when the OverageUnusedUnitsCreditOption field value is CreditBySpecificRate.
usageRecordRatingOption Determines how Zuora processes usage records for per-unit usage charges.
segment The identifying number of the subscription rate plan segment. Segments are numbered sequentially, starting with 1.
effectiveStartDate The effective start date of the rate plan charge.
effectiveEndDate The effective end date of the rate plan charge.
processedThroughDate

The date until when charges have been processed.

When billing in arrears, such as usage, this field value is the the same as the ChargedThroughDate value. This date is the earliest date when a charge can be amended.

chargedThroughDate

 The date through which a customer has been billed for the charge.

done A value of true indicates that an invoice for a charge segment has been completed. A value of falseindicates that an invoice has not been completed for the charge segment
triggerDate The date that the rate plan charge will be triggered
triggerEvent The event that will c.ause the rate plan charge to be triggered
endDateCondition

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.

Values:

  • Subscription_End
  • Fixed_Period
  • Specific_End_Date

upToPeriodsType

The period type used to define when the charge ends. 

Values:

  • Billing_Periods
  • Days
  • Weeks
  • Months
  • Years

upToPeriods

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.

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

The specific date on which the charge ends.

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.

mrr Monthly recurring revenue of the rate plan charge.
dmrc  A delta monthly recurring charge is the change in monthly recurring revenue caused by an amendment or a new subscription.
tcv The total contract value.
dtcv After an Amendment, the change in the total contract value (TCV) amount for this charge, compared with its previous value.
description
 
Description of the rate plan charge
cf_txtn__c One or more rate plan custom fields
cf_pkn__c One or more rate plan custom fields
billingTiming

The billing timing for the charge. This field is only used if the ratePlanChargeType value is Recurring.

Possible values are:

  • In Advance
  • In Arrears

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

ratingGroup

Specifies a rating group based on which usage records are rated. 

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

Possible values are:

  • ByBillingPeriod (default)
  • ByUsageStartDate
  • ByUsageRecord
  • ByUsageUpload

Note:

  • This field is only used 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.

subscriptionProductFeatures

Container for one or more features. 

Only available when the following settings are enabled:

id SubscriptionProductFeature ID
name Feature name, up to 255 characters long
featureCode Feature code, up to 255 characters long
description Feature description

nextPage

URL for requesting the next page of the response, if it exists; otherwise absent

Examples

HTTP/JSON request:

GET https://api.zuora.com/rest/v1/subscriptions/A-S00000004

JSON response:

{
  "success" : true,
  "id" : "2c9081a03c63c94c013c687b864e0195",
  "accountId" : "2c9081a03c63c94c013c66688a2c00bf",
  "accountNumber" : "RestAPI",
  "accountName" : "RestAPI",
  "subscriptionNumber" : "A-S00000004",
  "termType" : "TERMED",
  "contractEffectiveDate" : "2012-02-01",
  "serviceActivationDate" : "2012-02-01",
  "customerAcceptanceDate" : "2012-02-01",
  "subscriptionStartDate" : "2012-02-01",
  "termStartDate" : "2012-02-01",
  "termEndDate" : "2013-02-01",
  "initialTermPeriodType": "Week",
  "currentTerm": 12,
  "currentTermPeriodType": "Week",
  "autoRenew": false,
  "renewalSetting": "RENEW_WITH_SPECIFIC_TERM",
  "renewalTerm": 0,
  "renewalTermPeriodType": "Week",
  "contractedMrr" : 26.67,
  "totalContractedValue" : 404.00,
  "notes" : "",
  "status" : "Active",
  "ratePlans" : [ {
    "id" : "2c9081a03c63c94c013c687b868901a4",
    "productId" : "2c9081a03c63c94c013c66499ef0001b",
    "productName" : "OneTime",
    "productSku": "SKU-00000022",
    "productRatePlanId" : "2c9081a03c63c94c013c665102e5003a",
    "ratePlanName" : "OT_Tiered",
    "ratePlanCharges" : [ {
      "id" : "2c9081a03c63c94c013c687b868901a5",
      "originalChargeId" : "2c9081a03c63c94c013c687a92d70175",
      "productRatePlanChargeId" : "2c9081a03c63c94c013c6651d677003c",
      "number" : "C-00000010",
      "name" : "OT_Tiered",
      "type" : "OneTime",
      "model" : "Tiered",
      "uom" : "Each",
      "version" : 1,
      "pricingSummary" : "0 to 10 Each: USD20 flat fee;  11 Each or more: USD4/Each",
      "priceChangeOption" : null,
      "priceIncreasePercentage" : null,
      "currency" : "USD",
      "price" : null,
      "tiers" : [ {
        "tier" : 1,
        "startingUnit" : 0E-9,
        "endingUnit" : 10.000000000,
        "price" : 20.000000000,
        "priceFormat" : "FlatFee"
      }, {
        "tier" : 2,
        "startingUnit" : 11.000000000,
        "endingUnit" : null,
        "price" : 4.000000000,
        "priceFormat" : "PerUnit"
      } ],
      "includedUnits" : null,
      "overagePrice" : null,
      "discountPercentage" : null,
      "discountAmount" : null,
      "applyDiscountTo" : null,
      "discountLevel" : null,
      "billingDay" : null,
      "listPriceBase" : null,
      "billingPeriod" : null,
      "specificBillingPeriod" : null,
      "billingTiming" : null,
      "billingPeriodAlignment" : null,
      "quantity" : 11.000000000,
      "smoothingModel" : null,
      "numberOfPeriods" : null,
      "overageCalculationOption" : null,
      "overageUnusedUnitsCreditOption" : null,
      "unusedUnitsCreditRates" : null,
      "usageRecordRatingOption" : null,
      "segment" : 1,
      "effectiveStartDate" : "2012-02-01",
      "effectiveEndDate" : "2012-02-02",
      "processedThroughDate" : "2012-02-02",
      "chargedThroughDate" : "2012-02-02",
      "done" : true,
      "triggerDate" : null,
      "triggerEvent" : "ContractEffective",
      "endDateCondition" : "One_Time",
      "upToPeriodsType" : null,
      "upToPeriods" : null,
      "specificEndDate" : null,
      "mrr" : null,
      "dmrc" : null,
      "tcv" : 24.000000000,
      "dtcv" : 24.000000000,
      "description" : "",
      "pecker__c" : "good",
      "point__c" : "6"
    } ]
  }, ]
}

CURL request:

##
## Get Subscription By SubscriptionKey
##
echo
echo "=============Get subscription by subscription key============="
echo
curl -i -k -H "apiAccessKeyId:$USER_NAME" -H "apiSecretAccessKey:$PASSWORD" -H "Accept:application/json" -X GET $BASE_URL/v1/subscriptions/ff808081298c6e5401298c7a845c007b

JSON response:


{
  "success" : true,
  "id" : "2c9081a03c63c94c013c687b864e0195",
  "accountId" : "2c9081a03c63c94c013c66688a2c00bf",
  "accountNumber" : "RestAPI",
  "accountName" : "RestAPI",
  "subscriptionNumber" : "A-S00000004",
  "termType" : "TERMED",
  "contractEffectiveDate" : "2012-02-01",
  "serviceActivationDate" : "2012-02-01",
  "customerAcceptanceDate" : "2012-02-01",
  "subscriptionStartDate" : "2012-02-01",
  "termStartDate" : "2012-02-01",
  "termEndDate" : "2013-02-01",
  "initialTerm": 50,
  "initialTermPeriodType": "Week",
  "autoRenew": false,
  "renewalSetting": "RENEW_WITH_SPECIFIC_TERM",
  "renewalTerm": 0,
  "renewalTermPeriodType": "Week",
  "contractedMrr" : 26.67,
  "totalContractedValue" : 404.00,
  "notes" : "",
  "status" : "Active",
  "ratePlans" : [ {
    "id" : "2c9081a03c63c94c013c687b868901a4",
    "productId" : "2c9081a03c63c94c013c66499ef0001b",
    "productName" : "OneTime",
    "productSku": "SKU-00000022",
    "productRatePlanId" : "2c9081a03c63c94c013c665102e5003a",
    "ratePlanName" : "OT_Tiered",
    "ratePlanCharges" : [ {
      "id" : "2c9081a03c63c94c013c687b868901a5",
      "originalChargeId" : "2c9081a03c63c94c013c687a92d70175",
      "productRatePlanChargeId" : "2c9081a03c63c94c013c6651d677003c",
      "number" : "C-00000010",
      "name" : "OT_Tiered",
      "type" : "OneTime",
      "model" : "Tiered",
      "uom" : "Each",
      "version" : 1,
      "pricingSummary" : "0 to 10 Each: USD20 flat fee;  11 Each or more: USD4/Each",
      "priceChangeOption" : null,
      "priceIncreasePercentage" : null,
      "currency" : "USD",
      "price" : null,
      "tiers" : [ {
        "tier" : 1,
        "startingUnit" : 0E-9,
        "endingUnit" : 10.000000000,
        "price" : 20.000000000,
        "priceFormat" : "FlatFee"
      }, {
        "tier" : 2,
        "startingUnit" : 11.000000000,
        "endingUnit" : null,
        "price" : 4.000000000,
        "priceFormat" : "PerUnit"
      } ],
      "includedUnits" : null,
      "overagePrice" : null,
      "discountPercentage" : null,
      "discountAmount" : null,
      "applyDiscountTo" : null,
      "discountLevel" : null,
      "billingDay" : null,
      "listPriceBase" : null,
      "billingPeriod" : null,
      "specificBillingPeriod" : null,
      "billingTiming" : null,
      "billingPeriodAlignment" : null,
      "quantity" : 11.000000000,
      "smoothingModel" : null,
      "numberOfPeriods" : null,
      "overageCalculationOption" : null,
      "overageUnusedUnitsCreditOption" : null,
      "unusedUnitsCreditRates" : null,
      "usageRecordRatingOption" : null,
      "segment" : 1,
      "effectiveStartDate" : "2012-02-01",
      "effectiveEndDate" : "2012-02-02",
      "processedThroughDate" : "2012-02-02",
      "chargedThroughDate" : "2012-02-02",
      "done" : true,
      "triggerDate" : null,
      "triggerEvent" : "ContractEffective",
      "endDateCondition" : "One_Time",
      "upToPeriodsType" : null,
      "upToPeriods" : null,
      "specificEndDate" : null,
      "mrr" : null,
      "dmrc" : null,
      "tcv" : 24.000000000,
      "dtcv" : 24.000000000,
      "description" : "",
      "pecker__c" : "good",
      "point__c" : "6"
    } ]
  }, ]
}
Last modified
19:20, 27 Dec 2016

Tags

Classifications

(not set)