AutoBill.modify

• create new AutoBills or Billing Plans. You can only use this method to modify existing AutoBills or Billing Plans.
• modify AutoBills that use the MerchantAcceptedPayment payment method.

• You can use AutoBill.modify to credit customers for paid but unused days of service, and debit customers for additions to their subscriptions. AutoBill.modify does not prorate debits for subscription additions. The net amount is the full cost of the debit minus the prorated credits.
• You can use AutoBill.modify to credit customers for paid but unused days of service, and debit customers a reduced amount for a new, downgraded subscription. AutoBill.modify does not prorate subscription downgrades. The net credit amount is the full amount of the prorated credits minus the cost of the debit.

• modify AutoBills that have any number of AutoBillItems.
• add, remove, edit or replace multiple AutoBillItems. You can use remove and replace in a single call, but you must use edit by itself.
• work with Campaigns. (Added items may have a Campaign Code, and the AutoBill may have a billingPlanCampaignCode; the Campaign Code is redeemable on the Billing Plan only if a new Billing Plan is sent in.)
• work with Seasonal Billing Plans to credit or debit customers for subscription changes.
• maintain a history of modified AutoBills.
• generate a single, prorated net charge or refund for the combined modification activity. (This charge or refund will appear through the API and Portal with other Transactions from this AutoBill.)
• retain the AutoBill in its original state if any aspect of the call, including the modification-based charge or refund, fails. Note: If you are using Subscribe for sales tax calculations, you must integrate your application with the Avalara Tax Engine to use the AutoBill.modify method. To integrate your application with the Avalara Tax Engine, contact your Vindicia support representative.
• change the billing date to a new date that is before or after the current billing date (or service date) within the billing cycle, and have Subscribe automatically prorate the charges.

​

Input

• nextBill initiates changes with the next Billing Cycle.
• today initiates changes effective today. With effectiveDate today, the billing date (and billing day of month) will change only if the Billing Plan is changed (in which case, Subscribe will perform the first billing for the new BillingPlan and AutoBillItems immediately). If only AutoBillItems is changed with this call Subscribe will prorate both credits and charges, and bill or refund immediately; future recurring billings will remain scheduled as before.

• editAutoBillItem: an existing AutoBillItem to modify.
• removeAutoBillItem:an AutoBillItemto remove from the AutoBill. Identify this object with its index, merchantAutoBillItemId, product or VID.
• addAutoBillItem: an AutoBillItemto add to the AutoBill.

• Extend the billing cycle. A $30 monthly subscription bills on the 1st of the month. On February 20, *changeBillingDateTo* is set to the 16th of March, effective immediately. Subscribe calculates a new charge for the period 3-1 through 3-15, for an immediate prorated charge of$15. Next regular monthly billing is on the 16th of March.
• Shorten the billing cycle. A $30 monthly subscription bills on the 1st of the month. On February 10, *changeBillingDateTo* is set to the 16th of March, effective immediately.Subscribe calculates a refund for the period 2-16 through 2-28 and applies it against the initial charge of$30 billed on February 1st. Next regular monthly billing is on the 16th of March.

​

Output

​

Returns

​

Example

// This example will replace one item, add a new item, 
// and change the billing plan effective today

$autoBillIdent = 'autobillToModify';
$annualPlanIdent = 'annualBillingPlan';

$replacementProductIdent = 'replacementProduct';
$newProductIdent = 'newProduct';

$oldAutoBillItemVID = 'd79ae3429ff102383b76d8f1eae8da52bd7dc1af';
$replacementItemIdent = 'upgradedProductItem';
$newItemIdent = 'addedProductItem';

// create and identify the AutoBill to be modified
$autobill = new AutoBill();
$autobill->($autobillIdent);

// existing item must be uniquely identified 
// (e.g., by VID, index, or by merchantAutoBillItemId or product, 
// if these last two are unique within the given AutoBill)
$oldItem = new AutoBillItem();
$oldItem->VID($oldAutoBillItemVID);

// create the product objects to be added; they only need identifying
// information (e.g., a VID or merchantProductId)
$replacementProduct = new Product();
$replacementProduct->merchantProductId($replacementProductIdent);

$newProduct = new Product();
$newProduct->merchantProductId($newProductIdent);

// now build the new AutoBillItems
$replacementItem = new AutoBillItem();
$replacementItem->merchantAutoBillItemId($upgradedProductItem);
$replacementItem->product($replacementProduct);
$replacementItem->index(1);

$newItem = new AutoBillItem();
$newItem->merchantAutoBillItemId($newItemIdent);
$newItem->product($newProduct);
$newItem->index(2);

// and the AutoBillItemModification objects
$addModification = new AutoBillItemModification();
$addModification->addedAutoBillItem($newItem);

$replaceModification = new AutoBillItemModification();
$replaceModification->removeAutoBillItem($oldItem);
$replaceModification->addAutoBillItem($newItem);

// create the object for the new billing plan
$billingPlan = new BillingPlan();
$billingPlan->merchantBillingPlanId($annualPlanIdent);

// now perform the modification, effective today, 
// prorating for any item or billing plan changes
$response = $autobill->modify('true', 'today', $billingPlan,
      [$addModification, $replaceModification], 'false');
if ($response['returnCode'] == 200)
{
   // return includes the updated autobill
   $updatedAutoBill = $response['data']->autobill();
   // return will include a transaction with all of the 
   // details for the prorated amounts
   $transaction = $response['data']->transaction();
   // if the net value of all prorated changes was negative, 
   // there will also be an array with one or more refunds 
   // against the original transactions
   $refunds = $response['data']->refunds();
}