AutoBill.modify

The AutoBill.modify call allows you to modify existing AutoBills, and generate any resultant charges or refunds to your customers, with a single call.

You cannot use AutoBill.modify to do the following:

• Create new AutoBills or Billing Plans. You can only use AutoBill.modify to modify existing AutoBills or Billing Plans.
• Modify AutoBills that use the MerchantAcceptedPayment payment method.

For AutoBills that use Seasonal Billing Plans, note the following considerations for subscription changes:

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

Note When you use AutoBill.modify for Seasonal Billing Plans, the effectiveDate must be equal to "today."

AutoBill.modify allows you to:

• 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 the 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 CashBox 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.

Input

srd: sparse response description, a SOAP string (which must be a JSON object), in which you specify the elements you want returned.This parameter enables the calling system to constrain a method call to return only components you specify. This gives you greater control over returned content, and improves response time within the Vindicia platform by reducing the processing needed for the call.

Some fields are required, either practically or in the WSDL, and will be returned regardless of the srd. A null srd returns the complete response.

autobill: the AutoBill object to modify. Identity this object with its VID or merchantAutoBillId.

billProratedPeriod: a Boolean flag which sets whether to prorate the price for the modification. If true, and effectiveDate is today, new items will be billed for the prorated remainder of the current Billing Period, and prorated credits will be issued for previously billed items. If false, your customer will not be billed for any changes to the AutoBill for the current Billing Period. Defaults to false if not specified.

Changing a billing plan with effectiveDate = today will always prorate regardless of the billProratedPeriod setting.

Transactions generated as a result of this option will automatically include the vin:AutoBillVID and the vin:MerchantAutoBillIdentifier name-value pairs.

effectiveDate: indicates when the modification should become effective.

• nextBill begins changes with the next Billing Cycle.
• today begins changes effective today.

With effectiveDate of today, the billing date (and billing day of month) will change only if the Billing Plan is changed (in which case, CashBox will perform the first billing for the newBillingPlan and AutoBillItems immediately). If only AutoBillItems are changed with this call, CashBox will prorate both credits and charges and bill/refund immediately; future recurring billings will remain scheduled as before.

Note For Seasonal Billing Plans, CashBox requires that the effectiveDate is set to today.

changeBillingPlanTo: the BillingPlan to replace the current on the AutoBill, identified by its merchantBillingPlanId or VID. (The new Billing Plan must already exist in your CashBox system before making this call.)

Note Changing the Billing Plan will prorate any difference in cost between the original and the new Billing Plans, and reset the billing date for the AutoBill to today.

autoBillItemModifications: an array of AutoBillItemModification objects, which define the changes to be made to the existing AutoBill.

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

Note The transitionedFromMerchantAutoBillItemVid and transitionedToMerchantAutoBillItemId data members will be populated only if a removed item is paired with an added item in a single AutoBillItemModification object. If submitted with separate objects, they will not be linked.

dryrun: a Boolean flag that, if set to true, will return the modified AutoBill, without recording the result in the CashBox database. Use this variable to compute the cost of an AutoBill modification without committing to the change.

Note No payment method validations, authorizations or charges will be performed if dryrun is true.

Output

return: an object of type Return that indicates the success or failure of the call.

autobill: the AutoBill object that was modified.

transaction: the Transaction object created (if billProratedPeriod was true) for the non-recurring charge or credit. Transactions generated as a result of this call will include a name-value pair with name vin:type and value modify.

refunds: an array of Refund objects created for the AutoBill as a result of the billProratedPeriod option.

Returns

In addition to those listed in Standard Return Codes, this call returns:

Return Code	Return String
400	One of the following: Could not load the AutoBill. Invalid value for effectiveDate: value. BillingPlan used in modify must already exist. No AutoBillItem found for criteria. Could not determine a unique item for criteria. The currency field on an added AutoBillItem does not match the currency on the AutoBill. Could not convert added item: error message. Can only apply a billingPlanCampaignCode to a new BillingPlan. Cannot modify an AutoBill in Stopped|Upgraded|PendingCustomerAction state. AutoBill has ended and cannot be modified. PaymentMethod on AutoBill does not support recurring billing. Cannot create new BillingPlan as part of an AutoBill::modify(). AutoBill cannot be modified for 'nextBill'; no further billing periods remain. Can only apply a campaign code to a new billing plan. Campaign code code could not be redeemed. Cannot redeem a time grant campaign on a BillingPlan via AutoBill::modify(). BillingPlan merchantPlanId is not eligible for campaign code code. Modifications would result in an AutoBill with no active AutoBillItems. Cannot remove items or change the BillingPlan effective today for an AutoBill with a Token PaymentMethod. Could not set AutoBill to 'Processing' status. Saving modified AutoBill failed; rolling back. AutoBillItem to be removed has already been removed. Could not determine start date for AutoBillItem. Campaign code code could not be redeemed. Cannot redeem a time grant campaign on a single AutoBillItem via AutoBill::modify(). Product merchantProductId is not eligible for campaign code code. Product merchantProductId is not eligible for an active time grant campaign.
402	Modify transaction authorization failed.

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->merchantAutoBillId($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();

}