Creating The Product Catalog

From API Documentation

Jump to: navigation, search

You can now create and update your product catalog via the Z-Commerce API. Creating your product catalog consist of three basic steps:

  1. Create a product
  2. Create a product rate plan for the product
  3. Create charges for the product rate plan

This topic includes examples (SOAP) of creating products, rate plans, and various charges and prices.

Contents

Create a Product

The following fields are required:

  • Name
  • Effective start date
  • Effective end date

Sample SOAP: 

<ns1:create>
  <ns1:zObjects xsi:type="ns2:Product">
    <ns2:EffectiveEndDate>2014-01-01T00:00:00-08:00</ns2:EffectiveEndDate>
    <ns2:EffectiveStartDate>2010-01-01T00:00:00-08:00</ns2:EffectiveStartDate>
    <ns2:Name>My API Product</ns2:Name>
  </ns1:zObjects>
</ns1:create>

Create a Product Rate Plan

The following fields are required:

  • Name
  • Effective Date
  • Effective Start Sate
  • Product ID

The effective dates of the rate plan must be within the effective dates of the product.

Sample SOAP: 

<ns1:create>
 <ns1:zObjects xsi:type="ns2:ProductRatePlan">
  <ns2:EffectiveEndDate>2014-01-01T00:00:00-08:00</ns2:EffectiveEndDate>
  <ns2:EffectiveStartDate>2010-01-01T00:00:00-08:00</ns2:EffectiveStartDate>
  <ns2:Name>My rate plan</ns2:Name>
  <ns2:ProductId>zuora-product-id-from-above</ns2:ProductId>
 </ns1:zObjects>
</ns1:create>

Create a Product Rate Plan Charge with Pricing Information

The following fields are required:

  • BillCycleDay – 1-31, <value for default from customer account>
  • BillingPeriod (Required for Recurring and Usage) –Month, Annual, Quarter, Semi-Annual
  • BillingPeriodAlignment - Required for Usage and Recurring Charges. Values: AlignToTermStart, AlignToSubscriptionStart, AlignToCharge
  • ChargeModel – FlatFee, PerUnit, Tiered, Volume, TieredWithOverage, Overage
  • ChargeType – OneTime, Recurring, Usage
  • Name
  • ProductRatePlanChargeTierData
  • ProductRatePlanChargeTier
  • Price
  • Currency
  • TriggerEvent – CustomerAcceptance, ContractEffective, ServiceActivation

Other fields are optional or dependent on charge model and charge type

ProductRatePlanChargeTierData is a wrapper for PrductRatePlanChargeTiers, and is only applicable for the create() call. This is for convenience and allows you to create all required tiers in a single call. ProductRatePlanChargeTierData is not applicable for querying.

The following examples demonstrate how to create different types of charges, pricing models, and how to handle multiple currencies.

Example 1: Recurring, flat fee charge for single currency

In this example, we create a monthly, recurring flat fee charge in a single currency 

<ns1:create>
 <ns1:zObjects xsi:type="ns2:ProductRatePlanCharge">
  <ns2:AccountingCode>TestAPI</ns2:AccountingCode>
  <ns2:BillCycleDay>1</ns2:BillCycleDay>
  <ns2:BillingPeriod>Month</ns2:BillingPeriod>
  <ns2:BillingPeriodAlignment>AlignToTermStart</ns2:BillingPeriodAlignment>
  <ns2:ChargeModel>FlatFee</ns2:ChargeModel>
  <ns2:ChargeType>Recurring</ns2:ChargeType>
  <ns2:Name>API_Recurring_FlatFee</ns2:Name>
  <ns2:ProductRatePlanChargeTierData>
   <ns1:ProductRatePlanChargeTier xsi:type="ns2:ProductRatePlanChargeTier">
    <ns2:Active>true</ns2:Active>
    <ns2:Currency>USD</ns2:Currency>     
    <ns2:Price>50</ns2:Price>
   </ns1:ProductRatePlanChargeTier>
  </ns2:ProductRatePlanChargeTierData>        
  <ns2:ProductRatePlanId>zuora-productrateplan-id-from-above</ns2:ProductRatePlanId>
  <ns2:TriggerEvent>ContractEffective</ns2:TriggerEvent>
 </ns1:zObjects>
</ns1:create>

Example 2: Usage charge, Tiered with Overage model, multiple currencies

This example creates a usage-based that has multiple price tiers for multiple currencies.

Note: Starting and ending units must be the same for different currencies. The different currencies must be enabled from within Z-Billing Settings.
<ns1:create>
 <ns1:zObjects xsi:type="ns2:ProductRatePlanCharge">
  <ns2:AccountingCode>TestAPI</ns2:AccountingCode>
  <ns2:BillCycleDay>1</ns2:BillCycleDay>
  <ns2:BillingPeriod>Annual</ns2:BillingPeriod>
  <ns2:BillingPeriodAlignment>AlignToTermStart</ns2:BillingPeriodAlignment>
  <ns2:ChargeModel>TieredWithOverage</ns2:ChargeModel>
  <ns2:ChargeType>Usage</ns2:ChargeType>
  <ns2:DefaultQuantity>10</ns2:DefaultQuantity>
  <ns2:Name>API_Usage_TieredWithOverage</ns2:Name>
  <ns2:ProductRatePlanChargeTierData>
   <ns1:ProductRatePlanChargeTier xsi:type="ns2:ProductRatePlanChargeTier">
    <ns2:Active>true</ns2:Active>
    <ns2:Currency>USD</ns2:Currency>     
    <ns2:EndingUnit>20</ns2:EndingUnit>
    <ns2:Price>100</ns2:Price>
    <ns2:StartingUnit>0</ns2:StartingUnit>
   </ns1:ProductRatePlanChargeTier>
   <ns1:ProductRatePlanChargeTier xsi:type="ns2:ProductRatePlanChargeTier">
    <ns2:Active>true</ns2:Active>
    <ns2:Currency>USD</ns2:Currency>
    <ns2:EndingUnit>3000</ns2:EndingUnit>
    <ns2:Price>90</ns2:Price>
    <ns2:StartingUnit>21</ns2:StartingUnit>
   </ns1:ProductRatePlanChargeTier>
   <ns1:ProductRatePlanChargeTier xsi:type="ns2:ProductRatePlanChargeTier">
    <ns2:Active>true</ns2:Active>
    <ns2:Currency>EUR</ns2:Currency>
    <ns2:EndingUnit>20</ns2:EndingUnit>
    <ns2:Price>85</ns2:Price>
    <ns2:StartingUnit>0</ns2:StartingUnit>
   </ns1:ProductRatePlanChargeTier>
   <ns1:ProductRatePlanChargeTier xsi:type="ns2:ProductRatePlanChargeTier">
    <ns2:Active>true</ns2:Active>
    <ns2:Currency>USD</ns2:Currency>
    <ns2:EndingUnit>3000</ns2:EndingUnit>
    <ns2:Price>80</ns2:Price>
    <ns2:StartingUnit>21</ns2:StartingUnit>
   </ns1:ProductRatePlanChargeTier>
  </ns2:ProductRatePlanChargeTierData>        
  <ns2:ProductRatePlanId>zuora-productrateplan-id-from-above</ns2:ProductRatePlanId>
  <ns2:TriggerEvent>ContractEffective</ns2:TriggerEvent>
  <ns2:UOM>Each</ns2:UOM>
 </ns1:zObjects>
</ns1:create>

Note: Note that you can create a ProductRatePlanChargeTier only as part of a ProductRatePlanCharge.

Retrieved from "http://apidocs.developer.zuora.com/index.php/Creating_The_Product_Catalog"