Promotion Codes allow you to offer discounts to consumers associated with payments and/or settlements. These can be configured manually or uploaded via ETL. Promo Codes can be redeemed by an agent or directly by the consumer in Virtual Agent 2.0.

How Promotion Codes Work

Promotion codes are associated with a {{glossary.Bundle}}.
Discounts can be:
- A fixed dollar amount, or
- A percentage
Promotion Codes can be applied:
- To the total balance owed, or
- To a specific bucket (Principal, Fee, or Interest)
Promotion Codes are valid until their expiration date
Expiration dates can be modified if the code has not been redeemed
Promotion Code usage can be tracked and reported using SQL

How Promotion Codes Are Created

Promotion Codes can be created in two ways:

Manually in ACE
By uploading an ETL profile using the BUNDLE_PROMO_CODES load method

Promo Code Settlement Behavior

Promo Code settlement behavior is controlled using the value stored in the Settlement field, whether the promotion code is created manually or uploaded via ETL.

When Settlement Is Checked / Set to True
- The discount applies to the total balance owed
  - If the settlement is paid as a single payment:
    - The Payment Amount automatically adjusts to reflect the settlement discount.
    - The discount is applied at the time of posting, resulting in a $0 balance on the selected accounts.
  - If the settlement is paid through a payment plan:
    - The Payment Plan Total and Settle Amount automatically adjust to reflect the discount.
    - The discount is applied after the payment plan is completed.
When Settlement Is Unchecked / Set to False
- The discount applies only to the specific bucket selected: i.e.
  - Principal
  - Fee
  - Interest

Setting Up Promotion Codes Manually

Before You Begin:

Ensure your user role includes the “Manage - Promotion Codes” permission.

Access Promotion Codes

Open an account.
From the Account Sidebar, click Promotion Codes.
Click New.
Then follow one of the examples to achieve the desired resulting promo code

Example A: Settlement Applied to Total Balance

Scenario: Apply a 25% discount to the total balance owed after a required number of payments.

Leave the Settlement checkbox checked to apply the discount to the total balance
Enter:
1. Code: Total Balance Discount
2. Discount Percent or Discount Amount (only one)
3. Expiration Date
Save the promo code.

Image Display Example Promotion Code Configuration with Settlement Field Checked

Example B: Settlement Applied to a Specific Bucket

Scenario: Waive 100% of the interest owed.

From the Account Sidebar, click Promotion Codes, click New.
Uncheck the Settlement checkbox.
Enter:
1. Code
2. Discount Percent or Discount Amount (only one)
3. Bucket (Principal, Fee, or Interest)
4. Expiration Date
Save the promo code.

Image Displays Example Promotion Code with Settlement Field Unchecked

Uploading Promotion Codes via ETL

Promotion Codes can also be uploaded using the BUNDLE_PROMO_CODES ETL load method.

ETL-based Promotion Codes behave the same as manually created Promotion Codes. Promo Code settlement behavior is controlled by values provided in the import file.

Refer to the Bundle Promo Codes ETL Layout document for additional details related to fields available to load data to.

Please Note
Please review the examples below to see the fields required for the results identified in each example.

Configuring Settlement in ETL Files

When uploading Promotion Codes via ETL, promo code settlement behavior is associated with the value loaded to the Promo Code Settlement field from the import file.

Settlement field: bundlePromoCode.settlement
Accepted values: T or F
- Settlement = T → Discount applies to total balance
  - The Bucket field/value is not required
- Settlement = F → Discount applies to specified bucket
  - The Bucket field/value is required.

Best Practice: Including the Settlement field is recommended to explicitly define how the promotion code should behave.

Example: Settlement Applied to Total Balance (Settlement = T)

This example applies a 25% settlement discount to the total balance owed.

Image Displays an Example of Loading Bundle Promo Codes via ETL

Example: Settlement Applied to a Specific Bucket (Settlement = F)

This example applies a settlement discount to the Interest bucket only.

Image Displays an Example of Loading Bundle Promo Codes via ETL

Step 1: Prepare Your File

You can prepare the import file using either a Logic Block or SQL Designer (descriptions of each method are included in the details below). Both options allow you to identify eligible accounts and ensure the file includes the required columns for your promotion code configuration.

Option A: Use a Logic Block

Use a Logic Block to define eligibility criteria and export matching accounts. After validating results:

Export the Logic Block output.
Add promotion code columns that apply to the promotion codes you are loading (Code, Settlement, Bucket when applicable, Discount, Expiration).

Option B: Use SQL Designer

Use SQL Designer to identify eligible accounts along with the promotion code columns that apply to the promotion codes you are loading. In this scenario you will need to add to the SQL query, eligibility criteria (similar to the criteria you might use in a logic block).

Refer to the Example SQL Queries section of this article for sample queries.

Step 2: Load the File

Go to Accounts → ETL Import → Profiles → New.
Upload the file to configure the ETL Profile and map the fields.
Choose the following load method:
1. BUNDLE_PROMO_CODES
Test the profile to verify it loads data as expected.
If you will be loading promo codes via a job, configure and test that after you have verified the ETL profile is meeting your expectations.
Save the profile for future use.

Viewing a Bundle’s Promotion Codes

Click Promotion Codes from the account sidebar.
View a list of promotion codes for the bundle.

Image Displays Viewing Example Promotion Codes at the Bundle Level

Redeeming Promotion Codes in ACE

Ensure your role includes the PAYMENT_SETTLE permission.

Always redeem the promotion code before posting a payment or completing a payment plan.

1. Post a Payment

Option A: Settlement Applied to Total Balance

Use this method if the promotion code is set up as a Settlement (Settlement = True).

Open the account.
Click Post Transaction in the left sidebar.
Complete the Payment Information section:
1. Enter required credentials and contact details.
2. Select accounts to apply the payment to.
In the Promotion Code section:
1. Select the Settlement Promotion Code.
2. Click Redeem.
3. The payment amount adjusts for the discount.
Scroll down and verify transactions are spreading correctly.
Click Apply.

What Happens:

The Payment Amount automatically adjusts for the settlement discount.
The discount is applied at the time of posting, resulting in a $0 balance on the selected accounts.

Image Displays Redeem Button for Promotion Code

Option B: Settlement Applied to a Specific Bucket

Use this method if the promotion code applies to a specific bucket (Settlement = False).

Open the account.
Click Post Transaction in the left sidebar.
In the Promotion Code section:
1. Select the Promotion Code.
2. Click Redeem.
Enter the agreed upon payment amount that qualifies the consumer for the promotion.
Scroll down and verify transactions are spreading correctly.
Click Apply.

What Happens:

The discount is automatically posted to the account before the payment is entered and applied.

Image Displays Message for Promotion Code Once Redeemed (Step 3b)

2. Set Up a Payment Plan

Option A: Settlement Applied to Total Balance

Use this method if the promotion code is set up as a Settlement (Settlement = True).

Open the account.
Click Setup Payment Plan in the left sidebar.
In the Promotion Code section:
1. Select the Promotion Code.
2. Click Redeem.
Complete the payment plan details.
Validate the payment plan total and schedule.
Click Apply.

What Happens:

The Payment Plan Total and Settle Amount auto-adjust to reflect the discount.
The discount is applied after the plan is completed.

Caution
If a Promotion Code settlement payment plan has a failed payment or is modified by an agent in ACE, the promotion discount may no longer be associated with the plan, even though the Promotion Code will continue to appear as redeemed. Depending on the type or amount of the discount, the agent may be able to offer the discount by configuring new settlement terms. Otherwise, it may be necessary to obtain a new Promotion Code in order to offer the consumer the same or a similar discount.

Option B: Redeem a Promotion Code — Settlement Applied to a Specific Bucket

Use this method if the promotion code applies to a specific bucket (Settlement = False).

Open the account.
Click Setup Payment Plan in the left sidebar.
In the Promotion Code section:
1. Select the Promotion Code.
2. Click Redeem.
Fill in the payment plan as agreed upon with the consumer.
Validate the payment plan total and schedule.
Click Apply.

What Happens:

The discount is automatically posted to the account when the plan is created.
The plan total is not adjusted; the agent must enter the agreed upon plan terms.

Redeeming Promotion Codes in VA 2.0

How Consumers Redeem:

Log into Virtual Agent 2.0 using the secure login link or credentials.
Enter the promo code in the “Have a promo code?” field and click Redeem.

VA 2.0 Behavior

Settlement Applied to a Specific Bucket

Directs the consumer to a single payment page.
The discount applies immediately to the payment amount.

Note: If the single payment fails on the VA side, the promo code remains available for future use, and the discount is not applied to the failed payment.

Image Displays Redeeming a Settlement Promo Code in VA 2.0

Settlement Applied to Total Balance

When a consumer redeems a settlement promo code:

The discount is applied to the total balance owed.
The consumer is guided into setting up a payment plan to complete the settlement terms.

Image Displays Redeeming a Settlement Promo Code in VA 2.0

Example SQL Queries

The following example SQL queries are provided for reference only. They can be used to quickly export the column headers you may choose to include when building your ETL file, along with the eligible accounts you want to export and the promotion code fields required for your use case.

Example: Amount by Bucket via Debt ID

Image Displays Column Header for Amount by Bucket Debt ID

SELECT
   debt.debt_id,
   bundle_promo_code.code,
   bundle_promo_code.discount_amount,
   bundle_promo_code.expiration,
   bundle_promo_code.bucket
FROM debt
LEFT OUTER JOIN bundle_promo_code ON bundle_promo_code.bundle_id = debt.bundle_id
WHERE bundle_promo_code.discount_amount <> 0
ORDER BY debt.last_update DESC
LIMIT 1;

Example: Amount by Bucket via Bundle ID

Image Displays Amount by Bucket via Bundle ID

SELECT
   debt.bundle_id,
   bundle_promo_code.code,
   bundle_promo_code.discount_amount,
   bundle_promo_code.expiration,
   bundle_promo_code.bucket
FROM debt
LEFT OUTER JOIN bundle_promo_code ON bundle_promo_code.bundle_id = debt.bundle_id
WHERE bundle_promo_code.discount_amount <> 0
ORDER BY debt.last_update DESC
LIMIT 1;

Example: Amount for Settlement via Bundle ID

Image Displays Amount for Settlement via Bundle ID

SELECT
   debt.bundle_id,
   bundle_promo_code.code,
   bundle_promo_code.discount_amount,
   bundle_promo_code.expiration,
   bundle_promo_code.settlement
FROM debt
LEFT OUTER JOIN bundle_promo_code ON bundle_promo_code.bundle_id = debt.bundle_id
WHERE bundle_promo_code.discount_amount <> 0
  AND bundle_promo_code.settlement = 't'
ORDER BY debt.last_update DESC
LIMIT 1;

Example: Amount for Settlement via Debt ID

Image Displays Amount for Settlement via Debt ID

SELECT
   debt.debt_id,
   bundle_promo_code.code,
   bundle_promo_code.discount_amount,
   bundle_promo_code.expiration,
   bundle_promo_code.settlement
FROM debt
LEFT OUTER JOIN bundle_promo_code ON bundle_promo_code.bundle_id = debt.bundle_id
WHERE bundle_promo_code.discount_amount <> 0
  AND bundle_promo_code.settlement = 't'
ORDER BY debt.last_update DESC
LIMIT 1;

Example: Percent by Bucket via Debt ID

Image Displays Percent by Bucket via Debt ID

SELECT
   debt.debt_id,
   bundle_promo_code.code,
   bundle_promo_code.discount_percent,
   bundle_promo_code.expiration,
   bundle_promo_code.bucket
FROM debt
LEFT OUTER JOIN bundle_promo_code ON bundle_promo_code.bundle_id = debt.bundle_id
WHERE bundle_promo_code.discount_percent <> 0
ORDER BY debt.last_update DESC
LIMIT 1;

Example: Percent by Bucket via Bundle ID

Image Displays Percent by Bucket via Bundle ID

SELECT
   debt.bundle_id,
   bundle_promo_code.code,
   bundle_promo_code.discount_percent,
   bundle_promo_code.expiration,
   bundle_promo_code.bucket
FROM debt
LEFT OUTER JOIN bundle_promo_code ON bundle_promo_code.bundle_id = debt.bundle_id
WHERE bundle_promo_code.discount_percent <> 0
ORDER BY debt.last_update DESC
LIMIT 1;

Example: Percent for Settlement via Debt ID

Image Displays Percent for Settlement via Debt ID

SELECT
   debt.debt_id,
   bundle_promo_code.code,
   bundle_promo_code.discount_percent,
   bundle_promo_code.expiration,
   bundle_promo_code.settlement
FROM debt
LEFT OUTER JOIN bundle_promo_code ON bundle_promo_code.bundle_id = debt.bundle_id
WHERE bundle_promo_code.discount_percent <> 0
  AND bundle_promo_code.settlement = 't'
ORDER BY debt.last_update DESC
LIMIT 1;

Example: Percent for Settlement via Bundle ID

Image Displays Percent for Settlement via Bundle ID

SELECT
   debt.bundle_id,
   bundle_promo_code.code,
   bundle_promo_code.discount_percent,
   bundle_promo_code.expiration,
   bundle_promo_code.settlement
FROM debt
LEFT OUTER JOIN bundle_promo_code ON bundle_promo_code.bundle_id = debt.bundle_id
WHERE bundle_promo_code.discount_percent <> 0
  AND bundle_promo_code.settlement = 't'
ORDER BY debt.last_update DESC
LIMIT 1;

Reporting Promotion Code

The following SQL examples are provided for reference and reporting purposes only.

SQL Report Example 1: Promotion Code Redemption and Post-Redemption Payments

This report returns account-level details for a specific redeemed promotion code, including the first payment posted after redemption and related payment information.

When to Use This Report

Confirm that a specific promotion code was redeemed
Review payment activity after redemption
Validate commission amounts tied to post-redemption payments
Analyze how a promotion code performs once applied

Please Note:
This report is filtered to a single promotion code. Holiday is an example value and should be updated to the promotion code you want to report on.

SELECT
  debt.debt_id,
  debt.bundle_id,
  bundle_promo_code.code,
  bundle_promo_code.discount_amount,
  bundle_promo_code.discount_percent,
  bundle_promo_code.expiration,
  bundle_promo_code.settlement,
  bundle_promo_code.redeemed,
  bundle_promo_code.bucket,
  bundle_promo_code.number_of_payments,
  (SELECT payment.amount
     FROM payment
     WHERE payment.debt_id = debt.debt_id
       AND payment.trans_date >= bundle_promo_code.redeemed
     LIMIT 1) AS "Payment Amount",
  (SELECT debt_trans.commission_amount
     FROM debt_trans, payment
     WHERE payment.payment_trans_id = debt_trans.payment_trans_id
       AND payment.debt_id = debt.debt_id
       AND payment.trans_date >= bundle_promo_code.redeemed
     LIMIT 1) AS "Commission Amount",
  (SELECT payment_plan.source
     FROM payment_plan, payment
     WHERE payment.debt_id = debt.debt_id
       AND payment.payment_plan_id = payment_plan.payment_plan_id
       AND payment.trans_date >= bundle_promo_code.redeemed
     LIMIT 1) AS "Payment Source"
FROM debt
LEFT OUTER JOIN bundle_promo_code ON bundle_promo_code.bundle_id = debt.bundle_id
WHERE bundle_promo_code.code = 'Holiday'
  AND bundle_promo_code.redeemed IS NOT NULL
ORDER BY debt.last_update DESC
LIMIT 10;

SQL Report Example 2: Find all Promo Codes

This report returns all promo codes created regardless of whether or not the promo code has been redeemed. A where clause should be added to limit results based on specific codes or criteria at your discretion.

When to Use This Report

Review how promotion codes are configured
Verify discount amounts or percentages
Confirm settlement behavior and bucket selection
Check whether promotion codes have been redeemed

Please Note:
This report returns all promotion codes created.

SELECT
  debt.bundle_id,
  bundle_promo_code.code,
  bundle_promo_code.discount_amount,
  bundle_promo_code.discount_percent,
  bundle_promo_code.expiration,
  bundle_promo_code.settlement,
  bundle_promo_code.redeemed,
  bundle_promo_code.bucket,
  bundle_promo_code.number_of_payments
FROM debt
LEFT OUTER JOIN bundle_promo_code ON bundle_promo_code.bundle_id = debt.bundle_id
ORDER BY debt.last_update DESC
LIMIT 10;

Bundling and Responsible Party Relationships