Qixol Promo Help > Campaigns/Coupons

 

Source Codes and Vouchers

 

 

 

 

Coupons in Promo are containers for Codes.  Each Coupon can contain an unlimited number of Codes (except for evaluating companies), and when creating Promotions it is the Coupon that is associated with the promotion, not the individual codes.  This simplifies the link between the promotion and the codes, meaning that if you add additional codes after the promotion was created, the promotion does not need to be updated.

 

Coupons in Promo are split in to two types:  Source Codes and Vouchers.  

 

Both types of Coupon manage the following fields:

 

Field

Description

 

Name

The name of the Coupon.  Visible to users creating promotions to help them understand the codes that the coupon contains.

 

Type

Select from:

 

Voucher

Source Code

 

Additional fields may be presented based on the selected Type.

 

Import/Export Key

When interacting with the Coupon via the Promo API services, the Import/Export Key must be provided.

 

Reporting Code

A reporting code for the Coupon.    See Reporting Groups and Codes for further information.

 

 

 

Source Codes

 

Source Code type Coupons allow for codes which are completely managed by the user.  The user can choose the codes that they add to the Coupon, the expiration date and maximum number of uses and more.   Typically Source Codes are used where the codes are intended to be published in marketing collateral, or there are a small number of codes.

 

When creating a Source Code type Coupon, the first code must also be created.  Source codes support the following statuses:

 

Status

Description

 

Active

The code is available based on the maximum number of uses and the Valid from/to dates and can be utilized by promotions.

 

Redeemed

The code has been completed redeemed, based on the maximum number of uses.

 

Expired

The code's Valid To date/time is prior to the current date/time, and as such the code is expired and not available for redemption.

 

Withdrawn

The code has been withdrawn by a user of the Promo Portal, or by an interaction with the Promo API and as such is not available for redemption.

 

 

Additional codes can be created as required, from the Sub-Codes list.  For further information on the available fields for a code, and the supported actions that can be performed against codes, see Managing Codes.

 

 

Vouchers

 

Voucher type Coupons allow for a list of codes managed by Promo.  The codes are generated based on the settings of the Voucher (for example as a serialized number series, codes generated using a mask, or as random GUIDs). and can have a fixed number of uses and calculated expiration date.  Voucher codes have a more controlled life-cycle than Source Codes, where they will be in the following statuses:

 

 

Status

Description

 

Created

The code has been generated ready to be issued to a customer.  A code cannot be redeemed when in this status.  Only codes that have a status of Created can be issued to a customer.

 

Reserved

The code has been reserved by a refer-a-friend Issue Voucher Code promotion applied to a confirmed basket, and as such is dependant upon the referral codes being redeemed before it can be issued.  The code will automatically be issued once the referral code(s) have been fully redeemed.  The CouponCodes.ReservedActivated Webhook will be triggered when the code is issued.

 

Issued

The code has been issued to a customer and is available to be redeemed.  Based on the configuration of the Voucher, the code's Valid To date may be calculated at the point when the code is issued.

 

Redeemed

The code has been fully redeemed by the customer.

 

Expired

The code's Valid To date/time is prior to the current date/time, and as such the code is expired and not available for redemption.

 

Withdrawn

The code has been withdrawn by a user of the Promo Portal, or by an interaction with the Promo API and as such is not available for redemption.

 

 

 

Voucher Configuration

 

The voucher configuration specifies how codes will be configured when they are generated.   This controls the number of times generated codes may be used and the calculated start and end date/time of generated codes.

 

The following fields are available for Voucher configuration:

 

Field

Description

 

Generate Codes Using

Select from:

 

New short GUID

 

Codes will be generated using a generated unique identifier which is guaranteed to be unique within the company.

 

Incremented number series

 

Codes will be generated by incrementing the selected Number Series.  The code may also mask the number series value, depending on the configuration of the Number Series.

 

Mask

 

Codes will be generated using a mask containing randomized characters.

 

Generate on demand?

Flag indicating whether codes can be generated on demand.  The generation of codes on demand can occur where an Issue Voucher Code type promotion is applied to a basket, and where there are no existing codes with a status of Created.  Only available where the Generate Codes Using has a value of New Short GUID or Incremented Number Series.

 

Limit uses for generated codes?

Select whether the codes that are generated will by default have a fixed number of permitted uses.  Where codes are generated with a limited number of uses, their status will automatically be updated to Redeemed when they have been utilized by promotions the defined number of times.

 

Default maximum uses

Available where Limit uses for generated codes? has a value of true.   Specify the default maximum number of times codes can be utilized by promotions before they are updated to have a status of Redeemed.

 

Restrict uses per customer?

Select whether the codes that are generated will by default have a restricted number of uses per customer.  Note that promotions that utilize the code should ideally be configured with the Customer required in basket? flag selected to ensure that a customer ID is available to track the uses of the promotion and associated code.  See Configuring Promotions / Details and Benefits for more information.

 

Uses per customer

Available where Restrict uses per customer? has a value of true.  Specify the default maximum number of times codes can be utilized by a customer.

 

Number series

Where Generate Codes Using has a value of Incremented number series, specify the number series which will be incremented when codes are generated.

 

Mask

Where Generate Codes Using has a value of Mask, specify the mast text to be used when generating codes.  The Mask must include one or more replacement characters which will be replaced with a randomized character when the code is generated. 

 

The following replacement characters are available:

 

#   -  replace with an alpha-numeric character (a to z, or 0 to 9)

*   -  replace with an alpha character (a to z)

+  -  replace with a numeric character (0 to 9)

^  -  replace with a special character (@#*=-+)

 

Additional values can be used in the mask as prefixes, suffixes or mixed with the replacement characters.  A maximum of 10 replacement characters may be included in the Mask.

 

Excluded characters

Where Generate Codes Using has a value of Mask, specify characters to be excluded from the replacement characters.  Typically this may be to exclude characters that customer's tend to confuse (for example an I and a 1).   Multiple characters can be specified.

 

Upper-case only?

Where Generate Codes Using has a value of Mask, specify whether the replacement alpha characters should be selected from upper case A to Z only.  By default a to z and A to Z are supported.

 

Maximum possible unique codes

Where Generate Codes Using has a value of Mask.  [Read only]

Displays the maximum possible codes that can be generated for the current mask configuration.

 

Available unique codes

Where Generate Codes Using has a value of Mask.  [Read only]

Displays the maximum available codes that can be generated for the current mask configuration, based on the codes already generated.

 

Code validity

Specify the rules to be used when calculating a code's Valid from and Valid to dates (the date after which the code can no longer be used).  The date is calculated at the point when the code is Issued

 

Select from:

 

[Always]

The code will not expire.

 

Fixed date range

The code Valid from and Valid to will be set based on the fixed Valid from and Valid to values.

 

Period of hours

Period of days

Period of weeks

Period of months

Period of years

The code Valid from will be set to the current UTC date and time when the code is issued, and the Valid to will be calculated as a period of hours/days/weeks/months/years in the future (based on the Period value) from the current UTC date and time when the code is Issued.

 

End of current day

End of current week

End of current month

End of current year

The code Valid from will be set to the current UTC date and time when the code is issued, and the Valid to will be calculated as the end of the current day/week/month/year based on the current UTC date and time when the code is Issued.

 

 

Period

Where the Code validity is for a Period of hours/days/weeks/months/years, specify the period value.

 

Valid from

Where the Code validity is for Fixed date range, specify the Valid from date/time.

 

Valid to

Where the Code validity is for Fixed date range, specify the Valid to date/time.

 

Issue only?

Specify whether the generated codes are intended for use in a third party system, and as such cannot be redeemed by promotions applied by the Promo basket validation routines.  The option is typically only selected where the generation and management of the codes is being performed in Promo, and the redemption/utilization of codes is being undertaken by a third party system.

 

 

 

 

 

 

 

 

 

Copyright © 2021 Qixol Ltd.