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 Section 4.1: 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 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, CashBox authorizes the full amount immediately. In the event of a failure, CashBox responds according to the immediateAuthFailurePolicy, whose options include the following:

doNotSaveAutoBill—(default) deletes the AutoBill without saving it

putAutoBillInRetryCycle—creates AutoBill and retriesthe authorizaton


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, CashBox 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 CashBox 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() 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; CashBox automatically generates the VID when you call update(). When updating an existing AutoBill object, identify it with its VID or your AutoBill ID ().

Products can have an array of Products beneath them (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.


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.


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


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 CashBox to bill on the service period start date (the default).

billingRule: an enumerated string value (Advance or Arrears), informing CashBox 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 CashBox Programming Guide.

ImmediateAuthFailurePolicy: if the billing is scheduled for today, CashBox authorizes the full amount immediately. In the event of a failure of the initial transaction for the AutoBill, CashBox 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 CashBox continuously retries the credit card number

putAutoBillInRetryCycleIfPaymentMethodIsValid—(recommended.) Creates the AutoBill and retries the credit card only if CashBox 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 CashBox 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, CashBox defaults to 100, meaning that all transactions are acceptable and that no risk screening occurs. For more information on CashBox risk-screening, see Section 14: Common ChargeGuard Programming Tasks in the CashBox Programming Guide.

ignoreAvsPolicy: a Boolean flag which, when set to true, causes CashBox 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 CashBox 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 evaluation policy results are mapped to the AutoBill and Entitlement creation as follows:

Table 4-10: AVS / CVN Policy Evaluation Results

Policy Evaluation



AutoBill is active and entitlement is granted.


AutoBill is pending and entitlement is granted.


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 CashBox 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.)


Do not change the established currency type.

cancelReason: (Optional) reason for canceling the AutoBill. You can use predefined CashBox cancel reason codes, or define additional codes using the CashBox Portal or the API. (See "Canceling AutoBills with Reason Codes" in the CashBox Programmer’s 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 Table 1: Standard Return Codes, this call returns:

Return Code

Return String


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.


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 activate method for the AutoBill object.

fullAuthDelayedCapture: (Note: for future development, not currently implemented.) 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.


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 CashBox database, this method creates a new AutoBill object. Otherwise, CashBox 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.

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.

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


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

Return Code

Return String


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.


Unable to create AutoBill: error-description.

(This return code means that validation failed.)


Cannot update an AutoBill that has completed the retry cycle, and is past its endTimestamp.


AVS policy evaluation failed.


CVN policy evaluation failed.


AVS and CVN policy evaluations failed.


AVS and CVN policy evaluations could not be performed.


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



// Identify a previously created billing plan by your unique ID



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






// AutoBills may have multiple products

// each in an AutoBillItem as an array:


$item = new AutoBillItem();



// set the Product in the AutoBillItem



// set the Product (AutoBillItem)

$response = $autobill->setItems(array($item));



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



$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");