--- title: "Single Use Promotion Codes" slug: "single-use-promotion-codes" updated: 2025-12-29T21:18:23Z published: 2025-12-29T21:18:23Z canonical: "docs.interprose.com/single-use-promotion-codes" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.interprose.com/llms.txt > Use this file to discover all available pages before exploring further. # Single Use Promotion Codes 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 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** 1. Open an account. 2. From the Account Sidebar, click Promotion Codes. 3. Click New. 4. 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. 1. Leave the Settlement checkbox checked to apply the discount to the total balance 2. Enter: 1. Code: Total Balance Discount 2. Discount Percent or Discount Amount (only one) 3. Expiration Date 3. Save the promo code. ![](https://cdn.document360.io/6c7303ca-5ffc-4149-8868-8ea498eee635/Images/Documentation/Screenshot 2025-12-22 112012(1).png?sv=2026-02-06&spr=https&st=2026-10-31T14%3A33%3A41Z&se=2026-10-31T15%3A33%3A41Z&sr=c&sp=r&sig=fu%2FBwhZUK5BZQu5fAFCfS13OXP3t9lAiv2eU24dBS%2BA%3D) 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. 1. From the Account Sidebar, click Promotion Codes, click New. 2. Uncheck the Settlement checkbox. 3. Enter: 1. Code 2. Discount Percent or Discount Amount (only one) 3. Bucket (Principal, Fee, or Interest) 4. Expiration Date 4. Save the promo code. ![](https://cdn.document360.io/6c7303ca-5ffc-4149-8868-8ea498eee635/Images/Documentation/Screenshot 2025-12-22 113230.png?sv=2026-02-06&spr=https&st=2026-10-31T14%3A33%3A41Z&se=2026-10-31T15%3A33%3A41Z&sr=c&sp=r&sig=fu%2FBwhZUK5BZQu5fAFCfS13OXP3t9lAiv2eU24dBS%2BA%3D) 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](/v1/docs/bundle-promo-codes-etl-layout) document for additional details related to fields available to load data to. > [!NOTE] > 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. > [!NOTE] > 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. ![](https://cdn.document360.io/6c7303ca-5ffc-4149-8868-8ea498eee635/Images/Documentation/Screenshot 2025-12-23 141655.png?sv=2026-02-06&spr=https&st=2026-10-31T14%3A33%3A41Z&se=2026-10-31T15%3A33%3A41Z&sr=c&sp=r&sig=fu%2FBwhZUK5BZQu5fAFCfS13OXP3t9lAiv2eU24dBS%2BA%3D) 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. ![](https://cdn.document360.io/6c7303ca-5ffc-4149-8868-8ea498eee635/Images/Documentation/Screenshot 2025-12-23 143149.png?sv=2026-02-06&spr=https&st=2026-10-31T14%3A33%3A41Z&se=2026-10-31T15%3A33%3A41Z&sr=c&sp=r&sig=fu%2FBwhZUK5BZQu5fAFCfS13OXP3t9lAiv2eU24dBS%2BA%3D) 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: 1. Export the Logic Block output. 2. 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](/v1/docs/single-use-promotion-codes#example-sql-queries) section of this article for sample queries. ### Step 2: Load the File 1. Go to **Accounts → ETL Import → Profiles → New.** 2. Upload the file to configure the ETL Profile and map the fields. 3. Choose the following load method: 1. **BUNDLE_PROMO_CODES** 4. Test the profile to verify it loads data as expected. 5. 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. 6. 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. ![](https://cdn.document360.io/6c7303ca-5ffc-4149-8868-8ea498eee635/Images/Documentation/Screenshot 2025-04-28 103121.png?sv=2026-02-06&spr=https&st=2026-10-31T14%3A33%3A41Z&se=2026-10-31T15%3A33%3A41Z&sr=c&sp=r&sig=fu%2FBwhZUK5BZQu5fAFCfS13OXP3t9lAiv2eU24dBS%2BA%3D) Image Displays Viewing Example Promotion Codes at the Bundle Level ## Redeeming Promotion Codes in ACE Ensure your role includes the PAYMENT_SETTLE permission. > [!NOTE] > 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). 1. Open the account. 2. Click Post Transaction in the left sidebar. 3. Complete the Payment Information section: 1. Enter required credentials and contact details. 2. Select accounts to apply the payment to. 4. In the **Promotion Code** section: 1. Select the Settlement Promotion Code. 2. **Click** **Redeem.** 3. The payment amount adjusts for the discount. 5. Scroll down and verify transactions are spreading correctly. 6. 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. ![](https://cdn.document360.io/6c7303ca-5ffc-4149-8868-8ea498eee635/Images/Documentation/Screenshot 2025-04-28 102912.png?sv=2026-02-06&spr=https&st=2026-10-31T14%3A33%3A41Z&se=2026-10-31T15%3A33%3A41Z&sr=c&sp=r&sig=fu%2FBwhZUK5BZQu5fAFCfS13OXP3t9lAiv2eU24dBS%2BA%3D) 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). 1. Open the account. 2. Click Post Transaction in the left sidebar. 3. In the **Promotion Code** section: 1. Select the Promotion Code. 2. **Click Redeem.** 4. Enter the agreed upon payment amount that qualifies the consumer for the promotion. 5. Scroll down and verify transactions are spreading correctly. 6. Click Apply. **What Happens:** - The discount is automatically posted to the account before the payment is entered and applied. ![](https://cdn.document360.io/6c7303ca-5ffc-4149-8868-8ea498eee635/Images/Documentation/image_480.png?sv=2026-02-06&spr=https&st=2026-10-31T14%3A33%3A41Z&se=2026-10-31T15%3A33%3A41Z&sr=c&sp=r&sig=fu%2FBwhZUK5BZQu5fAFCfS13OXP3t9lAiv2eU24dBS%2BA%3D) 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). 1. Open the account. 2. Click Setup Payment Plan in the left sidebar. 3. In the **Promotion Code** section: 1. Select the Promotion Code. 2. **Click Redeem.** 4. Complete the payment plan details. 5. Validate the payment plan total and schedule. 6. 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] > 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). 1. Open the account. 2. Click Setup Payment Plan in the left sidebar. 3. In the **Promotion Code** section: 1. Select the Promotion Code. 2. **Click Redeem.** 4. Fill in the payment plan as agreed upon with the consumer. 5. Validate the payment plan total and schedule. 6. 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:** 1. Log into Virtual Agent 2.0 using the secure login link or credentials. 2. 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. ![](https://cdn.document360.io/6c7303ca-5ffc-4149-8868-8ea498eee635/Images/Documentation/image - 2025-09-12T124258.368.png?sv=2026-02-06&spr=https&st=2026-10-31T14%3A33%3A41Z&se=2026-10-31T15%3A33%3A41Z&sr=c&sp=r&sig=fu%2FBwhZUK5BZQu5fAFCfS13OXP3t9lAiv2eU24dBS%2BA%3D) 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. ![](https://cdn.document360.io/6c7303ca-5ffc-4149-8868-8ea498eee635/Images/Documentation/image - 2025-09-12T123921.035.png?sv=2026-02-06&spr=https&st=2026-10-31T14%3A33%3A41Z&se=2026-10-31T15%3A33%3A41Z&sr=c&sp=r&sig=fu%2FBwhZUK5BZQu5fAFCfS13OXP3t9lAiv2eU24dBS%2BA%3D) 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 ![](https://cdn.document360.io/6c7303ca-5ffc-4149-8868-8ea498eee635/Images/Documentation/amount by bucket via debt id.jpg?sv=2026-02-06&spr=https&st=2026-10-31T14%3A33%3A41Z&se=2026-10-31T15%3A33%3A41Z&sr=c&sp=r&sig=fu%2FBwhZUK5BZQu5fAFCfS13OXP3t9lAiv2eU24dBS%2BA%3D) Image Displays Column Header for Amount by Bucket Debt ID ```sql 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 ![](https://cdn.document360.io/6c7303ca-5ffc-4149-8868-8ea498eee635/Images/Documentation/amount by bucket via bundle id.jpg?sv=2026-02-06&spr=https&st=2026-10-31T14%3A33%3A41Z&se=2026-10-31T15%3A33%3A41Z&sr=c&sp=r&sig=fu%2FBwhZUK5BZQu5fAFCfS13OXP3t9lAiv2eU24dBS%2BA%3D) Image Displays Amount by Bucket via Bundle ID ```sql 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 ![](https://cdn.document360.io/6c7303ca-5ffc-4149-8868-8ea498eee635/Images/Documentation/amount for settlement via bundle id.jpg?sv=2026-02-06&spr=https&st=2026-10-31T14%3A33%3A41Z&se=2026-10-31T15%3A33%3A41Z&sr=c&sp=r&sig=fu%2FBwhZUK5BZQu5fAFCfS13OXP3t9lAiv2eU24dBS%2BA%3D) Image Displays Amount for Settlement via Bundle ID ```sql 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 ![](https://cdn.document360.io/6c7303ca-5ffc-4149-8868-8ea498eee635/Images/Documentation/amount for settlement via debt id.jpg?sv=2026-02-06&spr=https&st=2026-10-31T14%3A33%3A41Z&se=2026-10-31T15%3A33%3A41Z&sr=c&sp=r&sig=fu%2FBwhZUK5BZQu5fAFCfS13OXP3t9lAiv2eU24dBS%2BA%3D) Image Displays Amount for Settlement via Debt ID ```sql 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 ![](https://cdn.document360.io/6c7303ca-5ffc-4149-8868-8ea498eee635/Images/Documentation/percent by bucket via debt id.jpg?sv=2026-02-06&spr=https&st=2026-10-31T14%3A33%3A41Z&se=2026-10-31T15%3A33%3A41Z&sr=c&sp=r&sig=fu%2FBwhZUK5BZQu5fAFCfS13OXP3t9lAiv2eU24dBS%2BA%3D) Image Displays Percent by Bucket via Debt ID ```sql 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 ![](https://cdn.document360.io/6c7303ca-5ffc-4149-8868-8ea498eee635/Images/Documentation/percent by bucket via bundle id.jpg?sv=2026-02-06&spr=https&st=2026-10-31T14%3A33%3A41Z&se=2026-10-31T15%3A33%3A41Z&sr=c&sp=r&sig=fu%2FBwhZUK5BZQu5fAFCfS13OXP3t9lAiv2eU24dBS%2BA%3D) Image Displays Percent by Bucket via Bundle ID ```sql 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 ![](https://cdn.document360.io/6c7303ca-5ffc-4149-8868-8ea498eee635/Images/Documentation/percent for settlement via debt id.jpg?sv=2026-02-06&spr=https&st=2026-10-31T14%3A33%3A41Z&se=2026-10-31T15%3A33%3A41Z&sr=c&sp=r&sig=fu%2FBwhZUK5BZQu5fAFCfS13OXP3t9lAiv2eU24dBS%2BA%3D) Image Displays Percent for Settlement via Debt ID ```sql 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 ![](https://cdn.document360.io/6c7303ca-5ffc-4149-8868-8ea498eee635/Images/Documentation/percent for settlement via bundle id.jpg?sv=2026-02-06&spr=https&st=2026-10-31T14%3A33%3A41Z&se=2026-10-31T15%3A33%3A41Z&sr=c&sp=r&sig=fu%2FBwhZUK5BZQu5fAFCfS13OXP3t9lAiv2eU24dBS%2BA%3D) Image Displays Percent for Settlement via Bundle ID ```sql 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 > [!NOTE] > 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. ```sql 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 > [!NOTE] > Please Note: > > This report returns all promotion codes created. ```sql 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; ``` #### a group of accounts for the same consumer; the primary demographic identified for accounts grouped together should be the same person or entity