Knowledge Center

Knowledge Center > API > REST API > REST API Reference > Catalog

Catalog

This REST API reference describes how to retrieve the entire product catalog, including all products, features, and their corresponding rate plans, charges. Products are returned in reverse chronological order on the UpdatedDate field. 

The REST API does not support the creation or updating of products, product rate plans and charges; these tasks can only be performed in the web-based UI or via the SOAP API. 

With rate plans and rate plan charges, the REST API has a maximum array size. For details, see Array Size.

Request

  • Production: GET https://api.zuora.com/rest/v1/catalog/products
  • API Sandbox:  GET https://apisandbox-api.zuora.com/rest/v1/catalog/products 

Request Parameters

pageSize optional query Number of rows to return. Default is 10. Maximum is 40.

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 a failed result:

code

Eight-digit numeric error code

message

Description of the error

products

Container for one or more products:

id

Product ID

sku Unique product SKU, up to 50 characters
name

Product name, up to 100 characters

description Optional product description 

category

Category of the product. Used by Zuora Quotes Guided Product Selector.

Possible values are:

  • Base Products
  • Add On Services
  • Miscellaneous Products

effectiveStartDate

The date when the product becomes available and can be subscribed to, as yyyy-mm-dd.
effectiveEndDate The date when the product expires and cannot be subscribed to anymore, as yyyy-mm-dd.

allowFeatureChanges

Specifies whether to allow your users to add or remove features when creating or amending a subscription.

Possible values: true, false

This field is only applicable if the following settings are enabled:

cf_txtn__c

One or more custom fields

cf_pkn__c

One or more custom fields

productRatePlans

Container for one or more product rate plans:

id

Rate plan ID

status

Possible vales are: Active, Expired, NotStarted.

name

Rate plan name, up to 50 characters

description

Rate plan description

effectiveStartDate First date the rate plan is active (i.e., available to be subscribed to), as yyyy-mm-dd.  Before this date, the status is NotStarted.
effectiveEndDate

Final date the rate plan is active, as yyyy-mm-dd. After this date, the rate plan status is Expired.

cf_txtn__c

One or more custom fields

cf_pkn__c

One or more custom fields

productRatePlanCharges

Field attributes describing the product rate plan charges:

id

Unique product rate-plan charge ID

name

Name of the product rate-plan charge. (Not required to be unique.)

type

The type of charge. Possible values are: OneTime, Recurring, Usage.

model

Charge model which determines how charges are calculated.  Charge models must be individually activated in Z-Billing administration. Possible values are:

  • FlatFee
  • PerUnit
  • Overage
  • Volume
  • Tiered
  • TieredWithOverage
  • DiscountFixedAmount
  • DiscountPercentage

The Pricing Summaries section below details these charge models and their associated pricingSummary values.

uom

Describes the Units of Measure (uom) configured in Z-Billing > Settings for the productRatePlanCharges.
Values: Each, License, Seat, or null

pricingSummary

A concise description of the charge model and pricing that is suitable to show to your customers. See Pricing Summaries below for more information.

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

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.

pricing

One or more price charge models with attributes that further describe the model. 

currency

Currency used by the charge model. For example: USD or EUR

price

The decimal value that applies when the charge model is not tiered

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 when the charge model is Overage.

overagePrice

Price per unit when base set of units is exceeded. Used only when charge model is Overage or Tiered with Overage.

discountPercentage 

Percent discount applied to the price. Used only when the charge model is DiscountPercentage.

discountAmount 

Value subtracted from price in currency specified. Used only when the charge model is DiscountFixedAmount.

Some attributes show as null values when not applicable.

defaultQuantity

The default quantity of units.  This field is required if you use a per-unit charge model.

applyDiscountTo

Specifies where (to what charge type) the discount will be applied. These field values are case-sensitive.

Permissible values:

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

discountLevel

The level of the discount. Values:

  • RatePlan

  • Subscription

  • Account

billingDay

The bill cycle day (BCD) for the charge. The BCD determines which day of the month or week the customer is billed. The BCD value in the account can override the BCD in this object.

listPriceBase

The list price base for the product rate plan charge.

Values:

  • Month
  • Billing Period
  • Per_Week
billingTiming

The billing timing for the charge. You can choose to bill for charges in advance or in arrears.

Values:

  • 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.
billingPeriod

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

Values:

  • Month
  • Quarter
  • Annual
  • Semi-Annual
  • Specific Months
  • Week
  • Specific_Weeks
billingPeriodAlignment

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

Possible values:

  • AlignToCharge
  • AlignToSubscriptionStart
  • AlignToTermStart
specificBillingPeriod

When the billing period is set to Specific Months then this positive integer reflects the number of months for billing period charges.

smoothingModel

Specifies the smoothing model for an overage smoothing charge model or an tiered with overage model, which is an advanced type of a usage model that avoids spikes in usage charges. If a customer's usage spikes in a single period, then an overage smoothing model eases overage charges by considering usage and multiple periods.

One of the following values shows which smoothing model will be applied to the charge when Overage or Tiered with Overage is used:

  • RollingWindow considers a number of periods to smooth usage. The rolling window starts and increments forward based on billing frequency. When allowed usage is met, then period resets and a new window begins.
  • Rollover considers a fixed number of periods before calculating usage. The net balance at the end of a period is unused usage, which is carried over to the next period's balance.
numberOfPeriods Value specifies the number of periods used in the smoothing model calculations Used when overage smoothing model is RollingWindow or Rollover.
overageCalculationOption

Value specifies when to calculate overage charges.

Values:

  • EndOfSmoothingPeriod
  • PerBillingPeriod
overageUnusedUnitsCreditOption

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

Values:

  • NoCredit
  • CreditBySpecificRate
unusedIncludedUnitPrice

A container describes the prices to credit unused units of usage.

The fields in the container are only applicable when the following conditions are met:

  • The value of the SmoothingModel field is set to RollingWindow.
  • The value of the OverageCalculationOption field is set to PerBillingPeriod.
  • The value of the OverageUnusedUnitsCreditOption field is set to CreditBySpecificRate.

currency

The currency type that is used to credit unused usage. For example: USD or EUR
unusedUnitsCreditRate

The price per unit that is used to credit unused usage.

usageRecordRatingOption Determines how Zuora processes usage records for per-unit usage charges. 
priceChangeOption

Applies an automatic price change when a termed subscription is renewed and the following applies:

  1. AutomatedPriceChange setting is on

  2. Charge type is not one-time

  3. Charge model is not discount fixed amount


Values:

  • NoChange (default)
  • SpecificPercentageValue
  • UseLatestProductCatalogPricing
priceIncreasePercentage

Specifies the percentage to increase or decrease the price of a termed subscription's renewal. Use this field if you set the PriceChangeOption value toSpecificPercentageValue.

  1. AutomatedPriceChange setting is on

  2. Charge type is not one-time

  3. Charge model is not discount fixed amount

Values: a decimal between -100 and 100

useTenantDefaultForPriceChange

Shows the tenant-level percentage uplift value for an automatic price change to a termed subscription's renewal. You set the tenant uplift value in the web-based UI: Z-Billing > Define Default Subscription Settings

Values: truefalse

taxable

Specifies whether the charge is taxable; used by Z-Tax. Possible values are:true, false.

taxCode

Specifies the tax code for taxation rules; used by Z-Tax.

taxMode

Specifies how to define taxation for the charge; used by Z-Tax. Possible values are: TaxExclusive, TaxInclusive.

triggerEvent

Specifies when to start billing the customer for the charge.
Values: one of the following:

  • ContractEffective is the date when the subscription's contract goes into effect and the charge is ready to be billed.
  • ServiceActivation is the date when the services or products for a subscription have been activated and the customers have access.
  • CustomerAcceptance is when the customer accepts the services or products for a subscription. 
  • SpecificDateis the date specified.

description

Usually a brief line item summary of the Rate Plan Charge.

revenueRecognitionRuleName

The name of the revenue recognition rule governing the revenue schedule.

useDiscountSpecificAccountingCode

Determines whether to define a new accounting code for the new discount charge.

Values: true and false

includedUnits

Specifies the number of units in the base set of units when the charge model is Overage.

maxQuantity

Specifies the maximum number of units for this charge. Use this field and the minQuantity field to create a range of units allowed in a product rate plan charge.

minQuantity

Specifies the minimum number of units for this charge. Use this field and the maxQuantity field to create a range of units allowed in a product rate plan charge.

prepayPeriods

The number of periods to which prepayment is set. 

This field is only available if you already have the prepayment feature enabled. The prepayment feature is deprecated and available only for backward compatibility. Zuora does not support enabling this feature anymore.

financeInformation

Container for finance information of a rate plan charge.

recognizedRevenueAccountingCode The accounting code for recognized revenue, such as Monthly Recurring Charges or Overage Charges. 
recognizedRevenueAccountingCodeType The type associated with the recognized revenue accounting code, such as Sales Revenue or Sales Discount. 
deferredRevenueAccountingCode The accounting code for deferred revenue, such as Monthly Recurring Liability. 
deferredRevenueAccountingCodeType The type associated with the deferred revenue accounting code, such as Deferred Revenue. 

cf_txtn__c

One or more custom fields

cf_pkn__c

One or more custom fields

ProductFeatures

Container for one or more product features. Only available when the following settings are enabled:

id Feature ID
name Feature name, up to 255 characters long
code Feature code, up to 255 characters long
description Feature description
cf_txtn__c One or more custom fields

nextPage

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

Pricing Summaries

The pricingSummary field contains brief and auto-generated descriptions of your rate plan charges that are suitable to show to your customers.

The following table shows example returned values of the pricingSummary field for each charge model. The description of the pricing summary might vary depending on your rate plan charges. 

Charge Model Example Pricing Summary

Flat-Fee

USD100

Per-Unit

USD25/GB

Overage

Free for first 1 GB, thereafter USD0.5/GB

Volume

Up to 50 GB: USD120/GB; Up to 100 GB: USD100/GB

Tiered

0 to 6 GB: USD0 flat fee; 7 to 10 GB: USD10 flat fee; 11 to 20GB: USD9/GB; 21 to 30 GB: USD1010 flat fee

Tiered-With-Overage

0 to 50 GB: USD100/GB, thereafter USD100 per exceeding unit

Discount-Fixed-Amount

USD50 fixed amount discount

Discount-Percentage

80% discount

Examples

HTTP/JSON Request

GET https://api.zuora.com/rest/v1/catalog/products

JSON Response:

{
  "products": [
   {
     "id": "2c92c0f94f7243eb014f726032281e9a",
     "sku": "SKU-00000608",
     "name": "TeamCollab",
     "description": "Team Collaboration",
     "category": "Base Products",
     "effectiveStartDate": "2015-01-01",
     "effectiveEndDate": "2021-01-01",
     "productRatePlans": [
       {
         "id": "2c92c0f94f7243e6014f7260f69923aa",
         "status": "Active",
         "name": “TeamCollab Basic",
         "description": "",
         "effectiveStartDate": "2015-08-28",
         "effectiveEndDate": "2017-08-30",
         "productRatePlanCharges": [
           {
             "id": "2c92c0f94f7243e6014f7261f2ac24eb",
             "name": "Annual Basic",
             "type": "Recurring",
             "model": "FlatFee",
             "uom" : "Each",
             "pricingSummary": [ "USD1200/Each" ],
             "pricing" : [ 
             {
               "currency" : "USD",
               "price" : 234.000000000,
               "tiers" : null,
               "includedUnits" : null,
               "overagePrice" : null,
               "discountPercentage" : null,
               "discountAmount" : null
             } ], 
             "defaultQuantity" : 233.000000000,
             "applyDiscountTo" : null,
             "discountLevel" : null,
             "endDateCondition" : "Fixed_Period",
             "upToPeriods" : 1, 
             "upToPeriodsType" : "Years",
             "billingDay": "DefaultFromCustomer",
             "listPriceBase" : "Per_Billing_Period",
             "billingTiming" : "IN_ADVANCE",
             "billingPeriod": "Annual",
             "billingPeriodAlignment" : "AlignToCharge",
             "specificBillingPeriod" : null,
             "smoothingModel" : null,
             "numberOfPeriods" : null,
             "overageCalculationOption" : null,
             "overageUnusedUnitsCreditOption" : null,
             "usageRecordRatingOption" : null,
             "priceChangeOption" : null,
             "priceIncreasePercentage" : null,
             "useTenantDefaultForPriceChange" : true,
             "taxable": false,
             "taxCode": "",
             "taxMode": "TaxExclusive",
             "triggerEvent" : "ContractEffective",
             "description" : "",
             "revenueRecognitionRuleName": "Recognize upon invoicing",
             "useDiscountSpecificAccountingCode": null,
             "includedUnits": null,
             "maxQuantity": null,
             "minQuantity": null,
             "prepayPeriods": null,
             "financeInformation": {
             "recognizedRevenueAccountingCode": "Subscription Revenue",
             "recognizedRevenueAccountingCodeType": "SalesRevenue",
             "deferredRevenueAccountingCode": "Subscription Revenue",
             "deferredRevenueAccountingCodeType": "SalesRevenue"
           }
         ]
       }
     ]
    }
  ]
}

CURL Request

##
## export product rate plans
##
echo
echo "==========EXPORT PRODUCT=============="
echo
curl -i -k -H "apiAccessKeyId:$USER_NAME" -H "apiSecretAccessKey:$PASSWORD" -H "Accept:application/json" -X GET $BASE_URL/v1/catalog/products

JSON response:

{
  "products": [
   {
     "id": "2c92c0f94f7243eb014f726032281e9a",
     "sku": "SKU-00000608",
     "name": "TeamCollab",
     "description": "Team Collaboration",
     "category": "Base Products",
     "effectiveStartDate": "2015-01-01",
     "effectiveEndDate": "2021-01-01",
     "productRatePlans": [
       {
         "id": "2c92c0f94f7243e6014f7260f69923aa",
         "status": "Active",
         "name": “TeamCollab Basic",
         "description": "",
         "effectiveStartDate": "2015-08-28",
         "effectiveEndDate": "2017-08-30",
         "productRatePlanCharges": [
           {
             "id": "2c92c0f94f7243e6014f7261f2ac24eb",
             "name": "Annual Basic",
             "type": "Recurring",
             "model": "FlatFee",
             "uom" : "Each",
             "pricingSummary": [ "USD1200/Each" ],
             "pricing" : [
             {
               "currency" : "USD",
               "price" : 234.000000000,
               "tiers" : null,
               "includedUnits" : null,
               "overagePrice" : null,
               "discountPercentage" : null,
               "discountAmount" : null
             } ],
             "defaultQuantity" : 233.000000000,
             "applyDiscountTo" : null,
             "discountLevel" : null,
             "endDateCondition" : "Fixed_Period",
             "upToPeriods" : 1,
             "upToPeriodsType" : "Years",
             "billingDay": "DefaultFromCustomer",
             "listPriceBase" : "Per_Billing_Period",
             "billingTiming" : "IN_ADVANCE",
             "billingPeriod": "Annual",
             "billingPeriodAlignment" : "AlignToCharge",
             "specificBillingPeriod" : null,
             "smoothingModel" : null,
             "numberOfPeriods" : null,
             "overageCalculationOption" : null,
             "overageUnusedUnitsCreditOption" : null,
             "usageRecordRatingOption" : null,
             "priceChangeOption" : null,
             "priceIncreasePercentage" : null,
             "useTenantDefaultForPriceChange" : true,
             "taxable": false,
             "taxCode": "",
             "taxMode": "TaxExclusive",
             "triggerEvent" : "ContractEffective",
             "description" : "",
             "revenueRecognitionRuleName": "Recognize upon invoicing",
             "useDiscountSpecificAccountingCode": null,
             "includedUnits": null,
             "maxQuantity": null,
             "minQuantity": null,
             "prepayPeriods": null,
             "financeInformation": {
             "recognizedRevenueAccountingCode": "Subscription Revenue",
             "recognizedRevenueAccountingCodeType": "SalesRevenue",
             "deferredRevenueAccountingCode": "Subscription Revenue",
             "deferredRevenueAccountingCodeType": "SalesRevenue"
           }
         ]
       }
     ]
    }
  ]
}
Last modified

Tags

Classifications

(not set)