Creating Billing Plans

The BillingPlan object describes the amount and schedule for recurring charges. Product objects describe the products or services that you sell. Both objects can include a Price. Note: An AutoBill object includes a BillingPlan, and an array of AutoBillItems. An AutoBillItem includes a Product, and the number of cycles the Product is to be included on the AutoBill. For more information, see the AutoBillItem Subobject in the Subscribe API Guide. For example, a business that sells access to online magazines—which cover different topics and are supported by different websites, but offer a standard subscription plan—might want to create a single BillingPlan that offers a one-month free trial, followed by a recurring bill of US

19.95 or C

22.40 per year. Note: Although multiple Billing Plans can be created dynamically, as shown in the following example, our best practice recommendation is to create stable BillingPlan objects that can be used when individual customers subscribe. The Subscribe Portal allows you to create and manipulate BillingPlan objects through a user interface. See the Subscribe User Guidefor details.

Create a Billing Plan with a one-month free trial, followed by a recurring bill of US $19.95 or C$ 22.40 per year

// Create a new BillingPlan
$bp = new BillingPlan();
 
$bp->setMerchantBillingPlanId('1MF1995Y');
$bp->setDescription('1 Free Month followed by $19.95(USD),
      $22.40(CAD) per year');
$bp->periods[0]=(new BillingPlanPeriod(
      type => 'Month',
      quantity => 1,
      cycles => 1, //Just once
      prices => [new BillingPlanPrices('amount' => 0,
      'currency' => 'USD'),
      new BillingPlanPrices('amount' => 0,
      'currency' => 'CAD')]));
$bp->periods[1]=(new BillingPlanPeriod(
      type => 'Year',
      quantity => 1,
      cycles => 0, //Repeat infinitely
      prices => [new BillingPlanPrices('amount' => 19.95,
      'currency' => 'USD'),
      new BillingPlanPrices('amount' => 22.40,
      'currency' => 'CAD')]));
$bp->merchantEntitlementIds[0] = (new MerchantEntitlementId (
      id => 'Standard',
      description => 'Standard subscription access'));
 
   $response = $bp->update();
 
if($response['returnCode'] == 200) {
   print "ok\n";
   $bpVid = $bp->getVID(); 
      //capture the billing plan VID for later use
}

Note: Once subscriptions have been activated in the system (that is, an AutoBill object that uses a particular BillingPlan object becomes active), do not make changes to the underlying BillingPlan object, other than to change the BillingPlan Cycle amounts. For all other changes, create a new BillingPlan object. The BillingPlan object supports several information-only attributes, such as endOfLifeTimestamp and status. These attributes can be used to sort or categorize your customers. For example, you can fetch all BillingPlan objects, and display only those objects for active customers, or for customers whose end-of-life time stamp has not yet passed. Note: Billing Plans can be processed in currency or tokens, but not in both. For example, you might set up your environment to support several token types (such as downloads and storage) and charge 50 downloads per month for access to the system. For details on how the BillingPlan object affects entitlements, see Creating Entitlements. Billing Plans can also be used to grant Seasonal Entitlements, using the SeasonSet object. For example, Create a 4-installment seasonal Billing Plan for the next 3 summers. The initial purchase must result in 2 free weeks, but subsequent years should not include a free period. (This is controlled using “skipInitialFreeWhenRepeating.”)

Create a Billing Plan with an attached Season Set

// To create this BillingPlan, you must first create the SeasonSet.
 
$ss = new SeasonSet;
$ss->merchantSeasonSetId("Summer");
 
$s2014 = new Season;
$s2014->description("Summer 2014");
$s2014->startDate("2014-05-15");
$s2014->endDate("2014-10-10");
 
$s2015 = new Season;
$s2015->description("Summer 2015");
$s2015->startDate("2015-05-12");
$s2015->endDate("2015-10-11");
 
$s2016 = new Season;
$s2016->description("Summer 2016");
$s2016->startDate("2016-05-19");
$s2016->endDate("2016-10-08");
 
$ss->seasons( [$s2014, $s2015, $s2016] );
$ss_factory->update($ss);
 
// Check the return code from update.
 
$bp = new BillingPlan;
$bp->merchantBillingPlanId("summer4installment");
$bp->description("Summer Installment Plan");
$bp->seasonSet($ss);
$bp->repeatEvery("1 Season");
$bp->timesToRun("unlimited");
$bp->skipInitialFreeWhenRepeating(1);
 
// Note that, although the code says to run this every 1 Season 
// for an unlimited number of times, there are only 3 seasons 
// in the SeasonSet. This is OK as long as you (later) add more seasons. 
// (They must be added before the time we would bill for them; 
// in this example they would have to be added by spring 2017.)
 
$bp_free = new BillingPlanPeriod;
$bp_free->free(1);
$bp_free->cycles(1);
$bp_free->quantity(2);
$bp_free->type("Week");
 
$bp_monthly = new BillingPlanPeriod;
$bp_monthly->free(0);
$bp_monthly->cycles(4);
$bp_monthly->quantity(1);
$bp_monthly->type("Month");
 
$bp->periods( [ $bp_free, $bp_monthly ] );
 
$bp_factory->update($bp);
 
// Check the return code from update.

Creating a Billing Plan with an early cancellation fee

Parent topic:Working with Billing Plans

Home

Guides

APIs

Create a Billing Plan with a one-month free trial, followed by a recurring bill of US $19.95 or C$ 22.40 per year

Create a Billing Plan with an attached Season Set

​Create a Billing Plan with a one-month free trial, followed by a recurring bill of US19.95orC19.95 or C19.95orC22.40 per year

​Create a Billing Plan with an attached Season Set

Create a Billing Plan with a one-month free trial, followed by a recurring bill of US $19.95 or C$ 22.40 per year

Create a Billing Plan with an attached Season Set