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

# Update

The `update` method is used to create a new `AutoBill` object. An `AutoBill` object represents a customer subscription with recurring billing. Be sure to properly construct the AutoBill (see [AutoBill Data Members](AutoBill_Data_Members)) before passing it into this call.

Call this method to first risk-screen the related Payment Method for the `AutoBill` object. Enabling risk screening causes this method to score a Transaction for the related Payment Method. (See the [Transaction.score](Transaction_score) method.) If the score is below the threshold specified in the `minChargebackProbability` parameter, the `AutoBill` object will be created. If the score is equal to or greater than the threshold, the object will not be created. For scoring to succeed, you must specify, in the `AutoBill` object, the source IP address from which the customer requested this subscription, and, in the associated payment method, the billing address.

If the billing is scheduled for today, Subscribe authorizes the full amount immediately. In the event of a failure, Subscribe responds according to the *immediateAuthFailurePolicy*, whose options include the following:

* `doNotSaveAutoBill`—(default) deletes the AutoBill without saving it
* `putAutoBillInRetryCycle`—creates AutoBill and retriesthe authorizaton
* `putAutoBillInRetryCycleIfPaymentMethodIsValid`—(recommended)

If billing is scheduled for a future date, the *validateForFuturePayment* flag is used to determine whether to do a minimal authorization ($0/$1) immediately. To request an immediate validation for a new or existing AutoBill when billing is not scheduled for *today*, set the *validateForFuturePayment* flag to `true`. An immediate minimal authorization will be performed. This flag is ignored when creating a new AutoBill with an immediate billing (scheduled for *today*) in favor of the full amount authorization.

By default, if a new AutoBill creation or modification requires billing within 25-hours, Subscribe does an immediate billing with full authorization. The purpose of this behavior is to minimize processing fees by combining the validation transaction with the billing transaction. This behavior has the added benefit of enabling you to respond to payment failures in real time—that is, while the customer is on line.

If, however, you offer a one-day initial billing cycle, or if you require that the initial transaction date be *tomorrow* rather than *today*, use the `DelayFullAuthToInitialBillingDate` option to prevent immediate billing when an AutoBill is created. This causes Subscribe to initiate a validation transaction *today*, and a billing transaction *tomorrow* (the specified start date of AutoBill/subscription). This option is `false` by default. See *initialAuth* below.

You can also use the `AutoBill.update()` method to specify a regular billing in advance of, or after, the Service Period start date. You can allow the service dates to be maintained according to the billing plan, while billing for those periods on specified days of the month, before or after the scheduled service date, using the *specifiedBillingDay* and *billingRule* parameters.

To create an `AutoBill` object, initialize the object and set the values for its data members as appropriate, then call the `update()` method to create the object on the Vindicia server. When creating a new `AutoBill` object, do not set a value for `VID`; Subscribe automatically generates the `VID` when you call `update()`. When updating an existing `AutoBill` object, identify it with its VID or your AutoBill ID (`merchantAutoBillId`).

A `Product` can have an array of products beneath it (sub-products). When a sub-product is placed on an `AutoBill`, all attributes of the top-level product will apply to the AutoBill, except for entitlements, which will be the union of the entitlements of all of the products and sub-products.

**Note:** The `AutoBill.update` method can not be used to add Products to an AutoBill. To add Products, use `AutoBill.modify`.

To apply a Campaign discount to an AutoBill, the Billing Plan must have prices defined in a currency that matches the currency set on the AutoBill. If the Billing Plan price is defined in currencies different from those used for the AutoBill, the discount will not be applied.

**Note:** The customer’s Account must exist before any Hosted Page related call references that Account.

## 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 create or update. Identify this object with its VID or .

To specify a regular billing in advance of, or after, the regularly scheduled Service Period start date, use the following parameters:

* *specifiedBillingDay*: an integer (1-31) specifying the day of the month on which to bill (values 29-31 automatically work as the last day of the month for calendar months that do not have 29, 30, or 31 days). Providing no value or null in this parameter instructs Subscribe to bill on the service period start date (the default).
* *billingRule*: an enumerated string value (`Advance` or `Arrears`), informing Subscribe in which direction from the scheduled billing date to select the specified billing date. If no `specified_billing_day` is provided, this parameter is ignored.

You can also use these parameters to change the billing date at migration of an AutoBill object. For more information, see Advance and Arrears Billing Option for AutoBills in the Subscribe Programming Guide.

*ImmediateAuthFailurePolicy*: if the billing is scheduled for *today*, Subscribe authorizes the full amount immediately. In the event of a failure of the initial transaction for the AutoBill, Subscribe responds according to the *ImmediateAuthFailurePolicy*, whose options include the following:

* *doNotSaveAutoBill*—(default) deletes the AutoBill. Select this setting if you want to start over, ask the consumer for a new credit card number, and create a new AutoBill.
* *putAutoBillInRetryCycle*—creates the AutoBill and places it in a "retry" cycle, in which Subscribe continuously retries the credit card number
* *putAutoBillInRetryCycleIfPaymentMethodIsValid*—(recommended.) Creates the AutoBill and retries the credit card only if Subscribe has evidence that the authorization will succeed

*validateForFuturePayment*: if billing is scheduled for a future date, this flag is used to determine whether to do a minimal authorization ($0/$1) immediately.

*minChargebackProbability*: a number between 0 and 100 by which you specify your fraud risk tolerance level. A chargeback probability (also called the risk-screening score or risk score) of 100 indicates that Subscribe is 100% certain a transaction is fraudulent and will result in a chargeback. Specify your acceptable threshold for chargeback probability with this parameter. If the score evaluates to more than your tolerance level, the `update` call will fail.

If you do not set *minChargebackProbability*, Subscribe defaults to 100, meaning that all transactions are acceptable and that no risk screening occurs. For more information on Subscribe risk-screening, see Common ChargeGuard Programming Tasks in the Subscribe Programming Guide.

*ignoreAvsPolicy*: a Boolean flag which, when set to `true`, causes Subscribe to override the AVS policy and update the `paymentMethod`, regardless of the AVS return code. If set to `false` or `null`, (and if *validateForFuturePayment* is set to `true`) the AVS return code will be used to determine whether to update the `paymentMethod`.

*ignoreCvnPolicy*: an optional Boolean flag which, when set to `true`, causes Subscribe to override the CVN policy and update the `paymentMethod`, regardless of the CVN return code. If set to `false` or `null`, (and if *validateForFuturePayment*is set to `true`) the CVN return code will be used to determine whether to update the `paymentMethod`.

If both *ignoreAvsPolicy* and *ignoreCvnPolicy* are `true`, no policy evaluation will be done. If only one of the flags is set to `true`, policy evaluation will not be considered for that element (AVS or CVN). If no value is passed in for either parameter, they will default to `false`, and the AVS and CVN policy evaluations will be used to determine `PaymentMethod` validation status.

**Note:**

The `AutoBill` will not be saved if validation is requested and fails.

The AVS and CVN Policy Evaluation policy Results are mapped to the `AutoBill` and `Entitlement` creation as follows:

| Policy Evaluation | Result |
| - | - |
| Success | AutoBill is active and entitlement is granted. |
| Pending | AutoBill is pending and entitlement is granted. |
| Fail | AutoBill is canceled and entitlement is inactive. |

For more detail on AVS and CVN Return Codes, please work with your Vindicia Client Services representative.

*campaignCode*: an optional Coupon or Promotion code, used in conjunction with a Campaign, to obtain a discount on this AutoBill.

*dryrun*: a Boolean flag that, if set to `true`, will return the updated AutoBill, without recording the result in the Subscribe database. Use this method to compute the cost of an AutoBill without committing to the change. (The projected billing amount will be returned in the `Transaction` object of the `nextBilling` data member of the returned `AutoBill` object.)

If the `AutoBill`did not exist before, it will not exist afterward; if it did exist before, it will not change. (No payment method validations, authorizations or charges will be performed if *dryrun* is `true`).

**Note:** Do not change the established currency type.

*cancelReason*: (Optional) reason for canceling the AutoBill. You can use predefined Subscribe cancel reason codes, or define additional codes using the Subscribe Portal or the API. (See Canceling AutoBills with Reason Codes in the Subscribe Programming Guide.) Supplying an undefined cancel reason code may result in an error.

*initialAuth*: (Optional) An enumerated value that specifies how to manage authorization and capture when the scheduled initial billing is within 25 hours. Default behavior is equivalent to `AuthImminentBilling`:

* `AuthImminentBilling`: By default, charges to be billed within 25 hours are authorized and captured immediately to save on processing fees. The immediate full amount authorization provides the validation.Returns.
* `DelayFullAuthToInitialBillingDate`: This value forces the specified validation behavior now, delaying the full authorization and capture attempt until the specified AutoBill Start Date.

In addition to those listed in [The Return Object](The_Return_Object), this call returns:

| Return Code | Return String |
| - | - |
| `400` | One of the following: - `Can not use this reason code: $reasonCode if its reserved for Vindicia use only.` - `Unable to load cancel reason code.` |
| *transaction*: (Optional) Transaction ID of a pre-authorized transaction (using `transaction.auth()` ).Use a pre-authorized transaction to verify and reserve full funds but create or 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.

*unknownStart*: (Optional) a Boolean flag that, when set to `True`, will create an `AutoBill` with no start date and status `Pending Activation`. An AutoBill created with an unknown start date must be activated with an `AutoBill.Activate()` call. Otherwise the `AutoBill` will persist in the pending activation state for up to two years from the creation date, and then be automatically canceled.

The unknown start functionality is currently supported only for credit card and debit card payment methods, and for season based entitlements. See the [AutoBill.activate](activate) method for the `AutoBill` object.

*fullAuthDelayedCapture*: If true and the AutoBill has a future start date or a free trial period, the AutoBill will be created with an `auth` for the full amount of the first paid-for period.

*enable3ds*: Disable 3DS authentication flow for this transaction if false; if true or undefined, the 3DS authentication flow will be determined by the merchant option flag `use3ds`.

## Output

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

*autobill*: the `AutoBill` object that was created or updated. If you specify a VID or your `AutoBill` ID for `autobill,` but that ID does not exist in the Subscribe database, this method creates a new `AutoBill` object. Otherwise, Subscribe updates the `AutoBill` object whose ID matches the input.

*created*: a Boolean flag that, if set to `true`, indicates that this method has created a new `AutoBill` object. A `false` setting indicates that `update` or `upgrade` has updated an existing `AutoBill` object.

*authStatus*: contains the response from the payment processor (either the initialTransaction auth response or that of the validation response). For example, the Address Verification Service (AVS) and Card Verification Number (CVN) response codes.

For some payment methods that do not support immediate payment (MerchantAcceptedPayment/invoicing), the Transaction is still included to provide the relevant Transaction and item details, including taxes and discounts, to support display in quotes (using `dryrun`) or confirmation pages.

*score*: the risk score for the payment method used for the `AutoBill` if you enabled risk scoring by specifying the value of the input parameter `minChargebackProbability` to be less than 100.

Normally, this value is between 0 and 100, where 100 is the highest risk score, indicating maximum chargeback probability. A value of -1 indicates that Subscribe could not evaluate the score because of missing data such as an IP address or a full billing address. A value of -2 indicates an error condition.

*scoreCodes*: an array of `ScoreCode` objects, each of which includes a code and corresponding message explaining why the risk score evaluated to a certain value.

*initialTransaction*: The initial transaction for new AutoBills. Creates an initial transaction for immediate billing, even if the amount is zero. Outputs a transaction object that contains complete information about the transaction, including the date, amount, and currency of the first billing.

*strongCustomerAuthentications*: Further instructions to client to authorize a Transaction that was subjected to SCA.

## 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: - `Failed to translate credit*error-description*.` - `Unable to create AutoBill:*error-description*.` - `Data validation error: Failed to create Payment-Type-Specific Payment Record: Credit Card conversion failed: Credit Card failed Luhn check.` - `Unable to create autobill: Must specify product to create autobill with!` - `Campaign code XYZ is not usable: Code XYZ is not valid.` - `No eligible, undiscounted items found for campaign code.` - `This Credit Card already exists—Policy Violation" (eradicate the newly created but failed one or ensure it is set INACTIVE).` You receive this error message when you have the Credit\_Card\_Constraints merchant option enabled on your site. This message means that someone is attempting to use a credit card that is already being used as the payment method on an existing account. This is not allowed. |
| `402` | `Unable to create AutoBill:*error-description*.` (This return code means that validation failed.) |
| `403` | `Cannot update an AutoBill that has completed the retry cycle, and is past its endTimestamp.` |
| `407` | `AVS policy evaluation failed.` |
| `408` | `CVN policy evaluation failed.` |
| `409` | `AVS and CVN policy evaluations failed.` |
| `410` | `AVS and CVN policy evaluations could not be performed.` |

## Example

```

// To create a subscription, to an existing product, for an 
// existing customer, using an existing billing plan

$autobill = new AutoBill();
$account = new Account();
$product = new Product();
$billPlan = new BillingPlan();

// Identify a previously created product by your unique ID
$product->setMerchantProductId('12345');

// Identify a previously created billing plan by your unique ID
$billPlan->setMerchantBillingPlanId('bp12345');

// Identify a previously created account by your unique ID
// Assumption: Account already has a payment method attached to it
// which will be used by the AutoBill automatically

$account->setMerchantAccountId('acct12345');

$autobill->setAccount($account);

// AutoBills may have multiple products 
// each in an AutoBillItem as an array:

$item = new AutoBillItem();
$item->setIndex(0);

// set the Product in the AutoBillItem
$item->setProduct($product); 

// set the Product (AutoBillItem)
$response = $autobill->setItems(array($item)); 

$autobill->setBillingPlan($billPlan);
$autobill->set('ab-44822'); // your ID for the AutoBill
$autobill->setCurrency('USD');

$validate = true;
$fraudScore = 100 ; // do not want to do risk screening

$response = $autobill->update('putAutoBillInRetryCycleIfPaymentMethodIsValid', 
   $validate, $fraudScore, true, true);

if($response['returnCode'] == 200 && $response['created'] ) {
   print "AutoBill created with VID " 
         . $response['data']->autobill->getVID() . "\n";
   if ( $response['authStatus'] != null ) {
      $txnStatus = $response['authStatus'];
      log (" CVN return code: " 
         . $txnStatus->getCreditCardStatus()->getCvnCode() 
         . "AVS return code" 
         . $txnStatus->getCreditCardStatus()->getAvsCode() . "\n");
   }
}
```


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