Coupons

Antavo’s Coupons module serves as a centralized platform for defining and managing all coupons within the loyalty program in one place. The coupon pools can be used across various modules, including Rewards, the Offers, and Workflows.

To access the module configuration page, search for Coupons under the Modules menu. The page will display the list of coupon pools configured within the module, along with the following details:

Creating a new coupon pool

• Click the Create coupon pool option in the sidebar

• Add the name of the coupon pool

Coupon source

• Select one of the four coupon sources: uploaded, generation, remote or bulk generation.

Generation and bulk generation

If you want Antavo to generate codes, define the coupon pattern using placeholder characters:

• # for a digit (0-9)

• @ for an alphabet character (a-z)

• ^ for a capital alphabet character (A-Z)

• * for an alphanumeric character

• $ for a capital alphanumeric character

If you would like to assign a generic coupon code to all customers, don’t use pattern characters, only literals (eg. if you set ‘SPRINGCOUPON’, all coupon codes to each customer will be generated as SPRINGCOUPON)

However, when defining the pattern of bulk-generated coupons, you must add at least 4 variables, which ensures that coupons can serve high demands.

Bulk-generation settings

Coupon pools with bulk-generated sources offer specific settings for customization:

• Exclude characters
  Specify any characters, separated by commas, that you want to exclude from coupon code generation to prevent confusion of similar characters (eg. O and 0 or 1 and I). Remember to list both lowercase and uppercase letters separately.

• Exclude phrases
  List specific phrases that you wish to exclude from coupon code generation to avoid unintentional or inappropriate text usage.

• Number of coupons
  Define the number of coupons to generate, ranging from 1 to 100 million. Note that the number of coupons generated must not exceed 1% of the possible variations within the coupon pattern. This prevents the customers from making lucky guesses on valid coupon codes. The maximum number of coupon codes is determined by the coupon pattern and is displayed in the help text. Be aware that this number might decrease if certain characters or phrases are excluded.

Upload

Select the upload option if you want to upload a set of coupons for distribution. Each coupon code can only be uploaded to one coupon pool; duplications are skipped automatically during the import process.

Remote

If you’d like to maintain control over coupon management, you can set a callback URL endpoint that serves Antavo with coupon codes to issue. When generated by the external system, it is also determined to whom the coupon is assigned, thus facilitating validation. The process requires the URL endpoint to receive POST requests from Antavo and responds with a coupon code.

Whenever the system requests a code, it will send the following request:

{
"api_key" => "DEMODEMODEMOSDJDSIFDKDF", 
   "coupon_percentage" => "20", 
   "value" => "THE COUPON VALUE", 
   "customer" => "53626328374843843", 
   "type" => "percentage"
}

• The API key must be checked against a stored API key to prevent any malicious requests to generate coupon codes

• The percentage value of the percentage-type coupon

• The value of the amount-type coupon

• Customer identifier

• Any other potential values

As a response, the system expects the code in the following format:

{
   "code" => "COUPON CODE"
}

If the system receives the coupon code, it is automatically passed on to the customer.

General settings

• Define the type of coupons in the pool

  • Fix amount

  • Percentage-off

  • Free shipping

  • Gift card
    Customers can use gift card coupons at multiple checkouts until the entire monetary value is spent.

• Define the value of the coupons in the pool - not applicable to free shipping coupons

Restrictions

• Add a minimum value – only applicable to gift card coupons
  The gift card will be invalidated if the balance falls below this amount. For example, if a $100 gift card has its minimum value of $1 and the customer uses the gift card to pay $99.5, then the card balance falls below $1 and the card will be voided.

• Add a minimum redemption value - only applicable to gift card coupons
  The customer must use at least this amount of the gift card each time they redeem it at checkout to reduce the basket value. For example, if the customer wants to redeem $10 of its $100 gift card to pay partially at purchase, but the minimum redemption value is $15, the redemption would fail with an error message.

• Add a purchase minimum
  Restrict the usage of a coupon to a minimum basket value.

• Set an expiration period
  The coupon code's expiration date is calculated from when the coupon was assigned to the customer.

• Add stores
  Pre-defined offline stores created/listed within the Stores module can be used to localize the validity of the coupon codes.

• Decide if you want to assign an aggregated coupon
  Tick the checkbox to have the same coupon code assigned each time this coupon pool issues a coupon for one specific customer.

• Add products
  It is possible to create and redeem coupons for individual products by selecting item(s) (previously added in the Product catalog module) to which the discount should apply.

Pass template

If you use the Wallet module, you might want to select a pass template to be assigned to the coupons in the currently configured pool. The coupon pass that customers can add to their wallet application will be generated based on the selected pass template.

User group

If you use the User groups module and have enabled the Coupon pool and Coupons entities in the settings, you need to assign a group to the coupon pool. Unauthorized users won’t be able to access the coupon pool in the Management UI and the corresponding coupon statistics.

Saving a coupon pool

Don’t forget to click the Save button at the end of the configuration process.

Uploading coupons

• Click the Upload coupons option in the sidebar
  You’ll be redirected to the coupon import page of the Imports module.

• Click Choose file to upload a CSV format file with one code in each row
  You can find the data fields you can include in the CSV in the Name column under the Fields section.

• Click Upload at the bottom of the page

• Configure the file import as per your need, and ensure the correct coupon pool is selected in the Coupon pool dropdown field under Module options.

• Click Start import

Right after the import is completed, coupons will appear in the list with a Not claimed yet label.

Bulk-generating coupons

• Navigate to the module configuration page

• Click the Edit button of the bulk-generated coupon pool to which you’d like to generate coupon codes

• Navigate to the Coupons tab

• Click the Click here to start generation process link in the infobox

• Enter the number of coupons you’d like to generate

You can generate a maximum of 5 million coupons at a time to ensure that all coupons in the batch are generated without delays.

• Click the Start generation button
  The coupon generation process will start immediately, and coupons will be populated on the page.

After the first coupon generation, you can generate further coupons by clicking the Bulk generation button at the top of the list.

Settings

Under the Settings tab, you can find a checkbox to enable the Auto redeem functionality. This means that the Coupon redeem event does not have to be sent to set the coupon status to redeemed. Instead, if the coupon code is included in the Checkout event, the Coupon redeem event is automatically registered.

Coupons

By navigating to the Coupons tab you can find the searchable and selectable list of coupons that have been uploaded or bulk-generated and/or assigned with the following information:

Invalidate coupons

Please note that only coupons with claimed and unassigned statuses can be invalidated.

Invalidate one single coupon

This method is available only for coupons with claimed status.

• Click the hamburger button of the coupon code

• Click Invalidate

• Confirm the invalidation action

Invalidate multiple coupons at the same time

• Tick the checkbox of each coupon code you’d like to invalidate

• Click the blue Invalidate selected button at the top of the page

• Confirm the invalidation action

The manual invalidation action updates the status of the coupon to invalid. If the coupon had been claimed and assigned to a customer, it triggers the registration of the coupon_invalidate event on the event history of the assignee of the coupon.

Unassign coupons

Please note that only assigned coupons can be unassigned.

Unassign one single coupon

• Click the hamburger button of the coupon code

• Click Unassign

• Confirm the unassign action

Unassign multiple coupons at the same time

• Tick the checkbox of each coupon code you’d like to unassign

• Click the blue Unassign selected button at the top of the page

• Confirm the unassign action

As a result, the Claimed at date will be cleared for the coupon, and a coupon_unassign event will be recorded in the customer's event history. Also, the number of claims for the coupon will be set to 0.

Transfer coupons

Please note that only coupons with claimed status can be transferred.

• Click the hamburger button of the coupon code

• Click Transfer

• Enter the ID of the customer who will receive the coupon in the Target Customer ID field, and/or enter the ID of the customer who will receive the coupon in the Target Customer email field

• Click Transfer

The manual transfer action triggers the registration of the coupon_transfer event on the event history of the previous assignee and the coupon_receive event on the event history of the new assignee.

Redeem coupons

Please note that only coupons with claimed status can be redeemed.

To redeem a coupon manually:

• Tick the checkbox of each coupon code you’d like to redeem

• Click the blue Redeem selected button at the top of the page

• Confirm the redeem action

The manual redemption triggers the registration of the coupon_redeem event on the event history of the assignee and increments the number of coupon usage.

Unredeem coupons

Please note that only coupons with redeemed status can be unredeemed.

Unredeem one single coupon

• Click the hamburger button of the coupon code

• Click Mark as unredeemed

• Confirm the unredeem action

Unredeem multiple coupons at the same time

• Tick the checkbox of each coupon code you’d like to invalidate

• Click the blue Unredeem selected button at the top of the page

• Confirm the unredeem action

The unredeeem action updates the status of the coupon to claimed, triggers the registration of the coupon_unredeem event on the event history of the assignee, and reduces the number of coupon usages.

Managing coupon pools

Editing a coupon pool

• Go to the Coupons page

• Click on the coupon pool in the list that you want to edit

• Edit the coupon pool
  Please note that the source and pattern cannot be edited once Save and generate is clicked for bulk-generated coupons

• Updating Coupons
  This section allows you to update any property of the coupon pool and apply it to all, or a specific subset of coupons in the pool.

  • Update Criteria:

    • Do not update coupons: Only the coupons that are added from now on will inherit the new pool properties

    • Update unassigned coupons: Coupons created but not yet assigned to a customer will inherit the new pool properties.

    • Update not yet redeemed coupons: Coupons that are assigned but not yet redeemed will inherit the new pool properties.

    • Update all coupons: All coupons will inherit the coupon pool’s properties.

  • Matching

    • Select this option if you want to update only those coupons with a value field that matches the original number.

Don’t forget to save your changes by clicking Save.

Deleting a coupon pool

It is important to note that once created, coupon pools cannot be deleted. If you no longer wish to use a specific coupon pool, ensure it is not selected in the configuration interface of loyalty program functionalities. This prevents the system from using the coupons from that pool.