> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slm.m1amdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 the `AutoBill.modify` method to

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

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

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

*billProratedPeriod*: a Boolean flag that specifies 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 prorate regardless of the `billProratedPeriod` setting. Transactions generated as a result of this option will automatically include the `vin:AutoBillVID` and the `vin:entifier` name-value pairs.

*effectiveDate*: indicates when the modification becomes effective.

* `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.

**Note:** For Seasonal Billing Plans, Subscribe requires that the *effectiveDate* is set to `today`.

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

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

*autoBillItemModifications*: an array of `AutoBillItemModification` objects that 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, when set to `true`, returns the modified AutoBill without recording the result in the Subscribe 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 are made when *dryrun* is `true`.

*transaction*: (Optional) Transaction ID of a pre-authorized transaction (using `transaction.auth()` ). Use a pre-authorized transaction to verify and reserve full funds but modify an AutoBill at some arbitrary later date without having to cancel the prior `Auth` or submit a new one.

**Note:** This feature is supported only for the Barclaycard Smartpay Gateway.

*changeBillingDateTo*: (Optional) New billing date. Use this parameter to change the billing date and have Subscribe automatically prorate the charges. You can change the billing date to a later date (extend the billing cycle), or change the billing date to an earlier date (shorten the billing cycle). Note that you must also set *billProratedPeriod* to `true` to have Subscribe calculate prorated charges.

* 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

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

**Note:** Transactions generated as a result of this call 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 [The Return Object](The_Return_Object), 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->($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();
}
```

**Parent topic:**[AutoBill Methods](../topics/AutoBill_Methods)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.