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

# Working with Billing Events

Subscribe can be configured to automatically send email notifications to your customers for various billing events, including upcoming Transactions, Subscription (AutoBill) expiration or renewal, or payment processing.

To enable these events, you must set the corresponding flags through the Subscribe API, and supply Vindicia with the corresponding email templates. If no template is supplied, no email can be sent.

Contact Vindicia Client Technical Services for more information.

* **[Subscribe Billing Events](../topics/Working_with_Billing_Eve#)**

* **[Billing Event Settings](../topics/Working_with_Billing_Eve#)**

* **[Parent-Child Account Billing Notifications](../topics/Working_with_Billing_Eve#)**

* **[Creating Billing Notification Templates](../topics/Working_with_Billing_Eve#)**

**Parent topic:**[Customer Notifications](../topics/ProgGuide_CustomerNotifications)

## Subscribe Billing Events

Subscribe can be configured to issue email notification of the following billing events. To generate the email, the appropriate flag must be set to `true`, and the corresponding email template must be available to Subscribe.

The following table lists the Subscribe billing events and suggested email content.

| Notice / Event | Suggested Content |
| - | - |
| Prebilling The billing event is pending. | Product information, AutoBill expiration date, the date on which billing will occur, the amount of the bill, the opt-out procedure, and contact information for your support team. To specify when to send this notification, Define it in the **Billing Plan** by using : - the `prenotifyDays` setting for SOAP. - the `billing_notification_days` setting for REST. |
| Initial Success The first billing event for a new Subscription (AutoBill) has been successful. | Use this email to welcome new customers to the business. The date of the next billing attempt, with product information, billing address, and transaction details (transaction number, billing date, and payment information), and the total amount for the transaction. (If the payment method is Tokens, replace the currency with the Token type.) |
| Success A successful billing event has occurred. | The date of the next billing attempt, with product information, billing address, and transaction details (transaction number, billing date, and payment information), and the total amount for the transaction. (If the payment method is Tokens, replace the currency with the Token type.) |
| Soft Fail The billing attempt has failed. The payment processor’s return code indicates that if the card is resubmitted, the billing might succeed. Subscribe will retry. | The date of the next billing attempt, with product information, billing address, and transaction details (transaction number, billing date, and payment information), and the total amount for the transaction. Include instructions for your customer to update their billing information. |
| Hard Fail The billing attempt has failed. The payment processor’s return code indicates that no more transactions will be accepted. | Product information, billing address, and transaction details (transaction number, billing date, and payment information), and the total amount for the transaction. Include instructions for your customer to update their account information to remain in good standing. |
| Cancellation The customer has opted out of the (AutoBill) Subscription, and an upcoming bill has been cancelled. (Sent only if a prebilling notification has already been issued.) | Notification that the transaction has been cancelled, and that your customer will not be billed on the next billing date (if a recurring bill.) Include contact information for re-subscribing to your service. |
| Billing Delay Issued upon a billing delay (extension of entitlements, without captured payment), only if the customer has not been pre-notified of the billing event. | The date of the next billing attempt, with product information, billing address, and transaction details (transaction number, billing date, and payment information), and the total amount for the transaction. |
| Prenotification: No Payment Method Issued as a Prebilling Notification, when no Payment Method is listed for the Subscription (AutoBill). | Product information, Subscription (AutoBill) expiration date, the date on which billing will occur, the amount of the bill, the opt-out procedure, and contact information for your support team. Include instructions for your customer to update their billing information. Specify when to send this notification in the prenotifyDays data member of the BillingPlan object. |
| Failure: No Payment Method The billing attempt has failed due to lack of a defined Payment Method. | The date of the next billing attempt, with product information, billing address, and transaction details (transaction number, billing date, and payment information), and the total amount for the transaction. Include instructions for your customer to update their billing information. |
| Credit Card Expiration Warning The customer’s credit card will expire in **x** months, where **x** is the number of months warning you want to give the customer. | The name on the credit card, the last four digits of the card number, the expiration date of the card, the customer identifier. Include instructions for your customer to update their credit card. |
| Expiration The billing plan is about to expire with no more periods defined. | Product information, an expiration date for the subscription, and information on how to extend the subscription. |
| End of Trial The customer’s free trial period is about to expire. | Product information, the duration and expiration date of the free trial, subscription amount, and other billing details for the paying subscription that is about to begin. Include opt-out instructions. |
| Real-Time Inbound Failure A real-time transaction initiated by a customer for you has failed. | Product information, billing address, and transaction details, including the transaction number, billing date, account number, amount, currency and sales tax (if applicable). Include instructions on how to update the account and remedy any issues. |
| Real-Time Inbound Success A real-time transaction initiated by a customer for you has succeeded. | Product information, billing address, and transaction details, including the transaction number, billing date, account number, amount, currency and sales tax (if applicable). |
| Real-Time Outbound Failure A real-time transaction initiated by you for a customer has failed. | Line-item details on the transaction and on the account to which the payment applies. |
| Real-Time Outbound Success A real-time transaction initiated by you for a customer has succeeded. | Line-item details on the transaction and on the account to which the payment applies. |
| Refund A refund to the customer has succeeded. | Product information, billing address, and refund details: transaction number, refund date, payment method, and amount. (If the Payment Method is Tokens, provide a Token balance in the message.) |
| Push Initiation A push payment has begun. | Product information, and instructions on how to complete the transaction, including the URL for the payment slip form. |
| Push Reminder The customer has not completed a push payment transaction within the allotted time. | Product information, and instructions on how to complete the transaction, including the URL for the payment slip form. |
| Failure: Insufficient Tokens Not enough tokens are available to pay for a recurring Transaction. | Token information, and instructions on how to obtain additional tokens. |
| Failure: Insufficient Tokens Not enough tokens are available to pay for a one-time Transaction. | Token information, and instructions on how to obtain additional tokens. |
| **Parent topic:**[Working with Billing Events](../topics/Working_with_Billing_Eve#) | |

## Billing Event Settings

The following table lists the customizations available to your notification timing through the Subscribe API.

| Notification | Settings |
| - | - |
| Prebilling | Set the number of days before billing will occur to send the notification. Define it in the **Billing Plan** by using : - the `prenotifyDays` setting for SOAP. - the `billing_notification_days` setting for REST. If the attribute is defined as `0` or not defined, Subscribe sends no prebilling notifications. Define whether or not to send prebilling notifications. Define in the **Account** object, by using: - `Account.warnBeforeAutobilling:` setting for SOAP. - `notify_before_billing` setting for REST. Determine whether to send a billing notification for the initial period. Define it in the **Billing Plan** by using : - `doNotNotifyOnFirstBill:` setting for SOAP. - `skip_initial_billing_notification` boolean setting for REST. This will prevent the customer from receiving a prebilling notification on the same day that they sign up. |
| Initial Success | None. |
| Success | None. |
| Hard Fail | A hard fails (Reject response) is a payment capture attempt that failed and indicates that additional attempts will subsequently fail as well. The classification of the type of fail is performed according to the error code returned by the payment provider. Work with Vindicia to map the payment provider reason codes to hard fails, to define the number of days after the billing attempt fails Subscribe should retry, and to define the number of retries. By default, Subscribe retries hard fails only once, and sends notifications if the first retry fails. (Subscribe may also be set to send hard-fail notifications for push payment methods after the transaction has expired, for example, if a customer does not perform the tasks necessary to complete the transaction.) |
| Soft Fail | Soft fails (Decline response) is a payment capture attempt that failed but may indicate that an additional attempt may succeed such as when the customer has insufficient funds. The classification of the type of fail is performed according to the error code returned by the payment provider and follows industry standards and recommendations. Work with Vindicia to map the payment provider reason codes to soft fails, to define the number of days after the billing attempt fails Subscribe should retry, and to define the number of retries. Subscribe retries soft fails until it exhausts the number of retries specified. If the final retry fails, Subscribe sets the Soft Fail to Hard Fail. |
| Cancellation | None. |
| End of Trial | Sets the number of days before a subscription ends to send a warning email. Define it in the **Billing Plan** by using:- `BillingPlan.expireWarningDays:` setting in SOAP. - `trial_end_notification_days` setting in REST. |
| Expiration | `BillingPlan.expireWarningDays:` Sets the number of days before a subscription ends to send a warning email. |
| Refund | None. |
| Real-Time Inbound Success | None. |
| Real-Time Outbound Success | None. |
| Real-Time Inbound Failure | None. |
| Push Initiation | None. |
| Push Reminder | Contact Vindicia Client Technical Services to set the number of days after initiation to send this reminder, and to specify the number of reminders (retry times). |
| Insufficient Tokens | None. |
| Tokens Granted | None. |
| **Parent topic:**[Working with Billing Events](../topics/Working_with_Billing_Eve#) | |

## Parent-Child Account Billing Notifications

Subscribe automatically determines which Accounts will receive Billing Notifications in a Parent-Child relationship, depending on which Account is the holder of the Payment Method attached to the AutoBill.

(In all cases, email generation is dependent upon your notification settings.)

For AutoBills held by a Child Account, but paid by the Parent’s Payment Method, the following notifications are sent to both the Parent and the Child Account:

* Billing Delay, No Payment Method?
* Cancellation
* Expiration
* Failure (Insufficient Tokens or No Payment Method)
* Pre-billing, No Payment Method

The following notifications are sent only to the Parent Account (the holder of the Payment Method associated with the AutoBill):

* Billing Delay
* End of Trial
* Hard Fail
* Pre-billing
* Real-Time Tx Outbound Fail
* Real-Time Tx Outbound Success
* Real-Time Tx, Insufficient Tokens
* Refund Success
* Soft Fail
* Success

**Note:** If a Child Account is the holder of the Payment Method, only the Child Account will receive these notifications.

**Parent topic:**[Working with Billing Events](../topics/Working_with_Billing_Eve#)

## Creating Billing Notification Templates

To create a notification template, use variables, or “tags,” that pull information from Subscribe to provide customer- and Account-specific information. Work with Vindicia Client Technical Services to submit your templates for inclusion in your Subscribe system.

Create billing notification templates in HTML. Vindicia recommends that you use an industry-standard HTML editor (do not use Word HTML). Host graphics, if any, from your site and point to them in the templates using HTML `href` tags.

### Billing Event Template Tags

Tags are used to provide a place holder in the template where Subscribe data will be inserted when the billing event notification is rendered. Subscribe notification templates support looping, to allow for multiple charges, credits, or payments.

The following tags may be used in a Billing Event template:

| Subscribe Tag | Description |
| - | - |
| \<tpl name="address"/> | The billing address (multiple lines). \*\*Note:\*\*This tuple will print the customer’s name, as well as all lines included in the billing address. |
| \<tpl name="amount"/> | The total transaction amount. **Note:** This is a deprecated tag. Specify `grand_total` instead. |
| \<tpl name="billing\_plan\_desc"/> | The Billing Plan’s description. |
| \<tpl name="billing\_plan\_id"/> | The `merchantBillingPlanId`. |
| \<tpl name="ccnum"/> | The credit-card number (the last four digits only). |
| \<tpl name="cctype"/> | The credit-card type, such as Visa or MasterCard. |
| \<tpl name="currency"/> | The currency code, for example, USD, or the description of the token type that serves as payment, for example, Award Points, Downloads, or Transférer. |
| \<tpl name="currency\_symbol"/> | The Billing Plan’s currency, as indicated by the ISO 4217 currency code entered for the `BillingPlanPrice` object’s `currency` data member. |
| \<tpl name="date"/> | The billing date (MM-DD-YYYY). |
| \<tpl name="desc\[n]"/> | An array of line-item descriptions that accompany real-time transaction notifications. Specify each item of the array and provide the maximum number of line items expected. For example: \<tpl name="desc\[0]"/> \<tpl name="desc\[1]"/> \<tpl name="desc\[2]"/> |
| \<tpl name="expirationdate"/> | The subscription’s expiration date (MM-DD-YYYY). |
| \<tpl name="formaction"/> | The URL for a push payment method slip from the payment processor. |
| \<tpl name="grand\_total"/> | The grand total of the transaction. For prebilling and postbilling notifications, this is the total cost (subtotal plus tax). For tokens, this value is the same as `amount`. |
| \<tpl name="interval"/> | The length of the billing period, such as 12 months. |
| \<tpl name="invoiceno"/> | The transaction ID, available only after you have submitted a transaction. |
| \<tpl name="ISOdate"/> | The billing date (YYYY-MM-DD). |
| \<tpl name="ISOexpirationdate"/> | The subscription’s expiration date (YYYY-MM-DD). |
| \<tpl name="ISOnextdate"/> | The next billing date, that is, the next retry after failure or the next scheduled billing (YYYY-MM-DD). |
| \<tpl name="length"/> | The length of the current billing period, for example, 2-week or 1-month. Subscribe supports this tag only in the End of Trial and Expiration templates. |
| \<tpl name="merchant"/> | Merchant’s name. |
| \<tpl name="merchant\_affiliate"/> | The partner or affiliate associated with the Billing event. |
| \<tpl name="name"/> | The customer’s first and last names. |
| \<tpl name="name\_on\_entitlement\_account"/> | The Account name (`merchantAccountId`) referenced in the email. (The Account holding the entitlements referenced in the email.) When a parent Account is notified about a child Account's entitlements, this field will display the child Account's name. |
| \<tpl name="name\_on\_payer\_account"/> | The name of the payer account. When a child account is sent an email notification, this field will display the parent Account's name. |
| \<tpl name="nextdate"/> | The next billing date, that is, the next retry after failure or the next scheduled billing (MM-DD-YYYY). |
| \<tpl name="payment\_provider"/> | The Payment Provider who handled the Billing event. |
| \<tpl name="payment\_token\_balance"/> | Valid for tokens only, this tag, which supports English only, returns the sentence “Your token-account balance is X,” where token-account is the description of the token type and X is the balance. For example: “Your Award Points balance is 50.00.” Note that the balance is the token balance after the transaction. If multiple token types apply to the customer account, this tag returns multiple lines, with each line corresponding to a different token type. Note: If included in an email notification template but tokens are not in use, this tag returns a blank. |
| \<tpl name="payment\_type"/> | A descriptor of the payment method, as follows: - For credit cards, the descriptor is **credit card** - For ECP, the descriptor is **bank account** - For PayPal, the descriptor is**PayPal account** - For direct debits, the descriptor is **direct debit accounts** - For Boleto Bancário, the descriptor is **conta bancária** (Portuguese only). - For tokens, the descriptor is the token type for payment, followed by account. For example, if the token type is Award Points, the descriptor is **Award Points account.** |
| \<tpl name="price"/> | An array of product prices that accompanies recurring or real-time transaction notifications. If used in conjunction with multiple line items and the desc tag, specify the maximum number of line items for each item, for example: \<tpl name="price\[0]"/> \<tpl name="price\[1]"/> \<tpl name="price\[2]"/> |
| \<tpl name="product"/> | The product name. \*\*Note:\*\*This tuple will be populated only for AutoBills, and not for One-Time Transactions. |
| \<tpl name="refid"/> | The Refund ID. |
| \<tpl name="refund\_amount"/> | The amount of the refund. In the case of tokens, this is the number of units of the token type that serves as payment. |
| \<tpl name="refund\_approval\_code"/> | The Payment Processor’s refund approval code. |
| \<tpl name="refund\_capture\_timestamp"/> | The `Refund` object’s `timestamp`. |
| \<tpl name="refund\_currency"/> | The currency of the refund. In the case of tokens, this is the description of the token type that serves as payment, for example, Award Points, Downloads, or Transférer. |
| \<tpl name="refund\_currency\_symbol"/> | The refund’s currency symbol, as indicated by the ISO 4217 currency code of the `Refund` object’s currency data member. |
| \<tpl name="refund\_merchant\_identifier"/> | The Refund object’s `merchantRefundId`. (Note that use of the forward slash character (/) in merchant identifiers is not allowed. |
| \<tpl name="refund\_note"/> | A note on the refund. |
| \<tpl name="refund\_payment\_provider"/> | The Payment Processor for the refund. |
| \<tpl name="refund\_pp\_order\_number"/> | The Payment Provider’s order number for the refund. |
| \<tpl name="refund\_status"/> | The refund’s status. |
| \<tpl name="refund\_timestamp"/> | The timestamp in the format “2008-09-19 15:20:04.” |
| \<tpl name="send\_to\_email"/> | The email address to which the Billing Event email should be sent. |
| \<tpl name="serialnum"/> | Your identifier for the `AutoBill` object. |
| \<tpl name="sku"/> | Your product identifier. |
| \<tpl name="statementno"/> | The statement number for the Billing event. |
| \<tpl name="subtotal"/> | The pretax amount. For tokens, this value is the same as `amount`. |
| \<tpl name="tax"/> | The applicable tax. If the payment method is tokens, the value is 0. |
| \<tpl name="token\_balance"/> | Available remaining Tokens for the Account. |
| \<tpl name="token\_change"/> | The change in number of Tokens available to the Account as a result of this Billing event. |
| \<tpl name="token\_id"/> | The `merchantTokenId` for the Tokens transferred in this Billing event. |
| \<tpl name="uri"/> | The URL the Payment Processor returned in response to the presentment of a fiscal number (for Boleto Bancario.) |
| \<tpl name="vid"/> | Subscribe’s unique identifier for the `AutoBill` object, which is useful if embedded in a URL to which your site is redirected when you call `AutoBill.fetchByVid()`. |
| **Note:** Not all Billing Event tags are available to all Billing events. For example, refund tuples may not be available to pre-billing notifications. Please work with your Vindicia Client Technical Services representative for more information. | |

**Parent topic:**[Working with Billing Events](../topics/Working_with_Billing_Eve#)


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