Skip to main content
Vindicia Knowledge Center

AutoBill Data Members

AutoBill Data Members

AutoBill Data Members

 

The following table describes the data members of the AutoBill object.

Data Members

Data Type

Description

account

Account

Required. The Account object to which this AutoBill object applies. If you do not specify a valid VID or merchantAccountId, CashBox creates a new Account object.

billingDay

int

The day of the month on which to bill the customer, which, if unspecified, defaults to the day of the startTimestamp. The value ranges from 1 to 31. CashBox automatically handles calendaring anomalies. For example, if you set this value to 31 but the month in question contains only 30 days, recurring billing automatically adjusts to day 30 for that month.

This attribute is useful if AutoBill has a yearly or monthly billing plan, and if the customer desires to be billed on a specific day of the month. If the billing plan is in terms of a daily or weekly cycle, the next billing day is determined by the duration and length of the cycle.

Note If the Billing Plan for the AutoBill includes a Season Set, and if the Billing Periods are set to repeat according to Seasons, this data member will be automatically reset by CashBox, according to the defined repetition cycle.

billingPlan

BillingPlan

The billing plan to be used for this AutoBill object. This attribute determines the frequency and amount of periodic billing transactions generated by this AutoBill object.

If you do not specify this attribute, CashBox uses the default billing plan associated with the primary Product object in this AutoBill object. If you have not defined a default billing plan for Product, be sure to specify it here.

If the BillingPlan object already exists, simply populate it with its VID or merchantBillingPlanId. If the BillingPlan does not yet exist, CashBox creates a new BillingPlan object along with this AutoBill object.

See BillingPlan Data Members.

billingPlanCampaignCode

string

The Campaign code redeemed on this AutoBill against the price of the Billing Plan. To apply a Campaign, use this field to pass in a valid Coupon or Promotion code.

Note This data member will not be returned.

billingPlanCampaignId

string

Read only. The unique identifier for a Campaign applied to this AutoBill's BillingPlan. This is a read-only field returned by CashBox for informational purposes. Values sent in with a SOAP call will be ignored.

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

billingState

BillingState

 

(Required) The billingState data member presents the financial billing condition of an AutoBill. This data member expands on the current billing condition of the subscription, and in combination with the Status field, provides a definitive representation of the current condition of an AutoBill.

See the AutoBill billingState Data Member Detail section for descriptions of the enumerated values of the billingState data member.

billingStatementIdentifier

string

The identifier on a customer’s billing statement when the customer is charged for this AutoBill object.

If GlobalCollect, MeS, Chase Paymentech or Litle is your payment processor, see Custom Billing Statement Identifier Requirements in the CashBox Programming Guide for the rules for this string.

CancelReason

string

A subobject containing a cancel reason code and description for canceling the AutoBill.

See the CancelReason Subobject.

credit

Credit

This data member encapsulates credit available to the AutoBill.

Token-based credits stored in this attribute may be applied toward Transactions generated by this AutoBill for Billing Plans which are defined with a Payment Method of the same Token Type.

Currency-based credits must be of the same Currency type listed in the Billing Plan associated with this AutoBill, to be used toward Transactions generated by the AutoBill.

Time-based credits are stored in this attribute only until the next Billing Period, at which point they are immediately and fully applied toward the AutoBill.

Do not manipulate this attribute directly. Instead, use methods such as grantCredit or revokeCredit to manipulate the amount of credit available to the AutoBill object.

See the Credit Subobject.

currency

string

The ISO 4217 currency code (see www.xe.com/iso4217.htm) for this AutoBill object. The default is USD. You should not change the currency type of an AutoBill object via the addChargemakePayment, or update methods.

customerAutoBillName

string

Optional. A name you specify (on your customer’s behalf) for this AutoBill object, such as 'Home Subscription.'

endTimestamp

dateTime

This is a read-only attribute in fetched AutoBill objects.

CashBox will automatically set this timeStamp based on the AutoBill’s last successful billing date, plus the length of the next Billing Period, and any grace period you have defined. This value is reset with every successful billing.

Note Do not set this value when creating or updating an AutoBill.

invoiceTerms

int

The number of days after the invoice date that a bill is considered delinquent, if the AutoBill payment method is MerchantAcceptedPayment. This value will be ignored for all other AutoBill payment methods.

items

AutoBillItem

An array of AutoBillItems to be included in the AutoBill.

See the AutoBillItem Subobject.

merchantAffiliateId

string

Your ID (a free-form string of 128 characters or less) for the affiliate that submitted this AutoBill object, if any.

merchantAffiliateSubId

string

Your ID (a free-form string of 128 characters or less) for the subaffiliate that submitted this AutoBill object. This ID enables more detailed tracking of affiliate programs, such as promotional campaigns.

merchantAutoBillId

string

Your unique identifier for this AutoBill object.

minimumCommitment

int

The number of billing cycles the customer is contractually obligated to complete before cancelling the subscription. For example, if you offer special pricing for a certain number of automatic billing renewals, you can track a customer’s initial agreement to those terms with this data member.

When you make a call to cancel an AutoBill object, CashBox checks this attribute. If AutoBill has not completed the minimum commitment period, CashBox performs the cancellation only if the force parameter in the cancel() call is set to true.

nameValues

NameValuePair

An (optional) array of name–value pair items for this AutoBill object. Some names are reserved for specific purposes.

Use vin:Division to route this AutoBill’s transactions to your payment processor as part of a business division, unit, or group you have registered with the processor.

CashBox provides the following name-value pairs for use with SEPA European Direct Debit and UK Direct Debit payment methods:

  • Use name vin:MandateFlag and value 1 to associate the SEPA or UK Direct Debit Payment Method with the AutoBill.

  • Use name vin:MandateVersion and value 1.0.1 to associate a mandate document of version 1.0.1 with the object.
  • Use name vin:MandateID to pass the Mandate ID field of the SEPA or UK Direct Debit Extension record to Chase Paymentech.
  • Use name vin:MandateApprovalDate to pass the Signature Date field of the SEPA or UK Direct Debit Extension Record to Chase Paymentech.
  • Use vin:ValidateFullAmt to pass whether full amount authorization needs to be done before charging. This must be enabled if the processor is Global Collect.

Note All name-value pairs included with an AutoBill object will be automatically copied to any resultant Transactions.

See The NameValuePair Object.

nextBilling

Transaction

An object of type Transaction that represents the next projected billing for this AutoBill, if any.

See Transaction Data Members.

paymentMethod

PaymentMethod

Vindicia’s identifier (VID) for the PaymentMethod object for this AutoBill. If you do not specify an existing VID or merchantPaymentMethodId, CashBox creates a new PaymentMethod object with this AutoBill object, and adds it to this AutoBill object’s account.

If you do not specify this attribute, the AutoBill will automatically use the preferred PaymentMethod object associated with the Account.

See PaymentMethod Data Members.

sourceIp

string

The IP address of the machine from which the customer requested the creation of this AutoBill object. This attribute is required if you wish to score a transaction associated with the AutoBill for risk screening. Some payment methods, such as European Direct Debit, also require this attribute.

specifiedBillingDay int An integer (1-31) specifying the fixed day of the month on which to bill (values 29-31 will automatically work as the last day of the month in 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 as usual.

startTimestamp

dateTime

A time stamp that specifies the start date and time for this AutoBill object. If unspecified, the value defaults to today and the current time.

statementFormat

StatementFormat

Defines the billing format used to send statements to a customer. Defaults to DoNotSend if not specified.

Valid input:

  • DoNotSend
  • Inline
  • Attachment

statementOffset

int

Days prior to billing that a statement will be sent. This value must be "null" or "0" if the AutoBill’s PaymentMethodType is MerchantAcceptedPayment. For conventionally-funded AutoBills, this value must be less than the prebilling notification days (if specified). The value will be ignored if statementFormat is DoNotSend.

statementTemplateId

string

Your identifier for a pre-defined statement template. If this value is null (or does not match any pre-defined statement templates), the CashBox-default template will be used.

status

AutoBillStatus

Provides a clear and mutually exclusive indicator of the current service status of an AutoBill, and of its place in its life cycle. See AutoBill status Data Member Detail for descriptions of the enumerated values of the status data member.

VID

string

Vindicia's Globally Unique Identifier (GUID) for this object. When creating a new AutoBill object, leave this field blank; it will be automatically populated by CashBox.

warnOnExpiration

Boolean

A flag that, if set to true, specifies that the customer be warned by email of an upcoming expiration of a trial period or subscription. The default is false. For more information, see the expireWarningDays attribute in the BillingPlanPeriod object.

For Users

Learn More
For Users

Cashbox Features

Learn More
Cashbox Features
Back to Top