Chapter 14: Creating and Using Single-Use Promotion Codes

Purpose: In order to offer a promotion to a select group of customers and prevent the promotion from being shared on the Internet, you can make the promotion available for use only through a group of randomly generated single-use codes. Once a customer uses one of these single-use codes, it is flagged as redeemed, and cannot be used again on a different order.

Restricted from standard promotion application: Once you generate a group of single-use codes for a promotion, the promotion is no longer eligible to be applied to an order in the same way as a promotion without single-use codes, that is:

• by specifying its actual promotion code if the Promotion Code Entry Required for Discount (I63) system control value is set to Y; or,

• automatically by the system if the Promotion Code Entry Required for Discount (I63) system control value is set to N

Instead, specifying a valid, unredeemed single-use code is required to apply the promotion to an order.

Preventing additional discounting and benefits: If you apply any promotion benefits to an order on the web site before submitting the order to CWDirect through the order API or the phone order load, then you can use the Order API/No Reprice Price Override Reason (L96) system control value to prevent any additional coupon or promotion discounting or benefits from applying to the order, including the benefits related to the promotion associated with the single-use code.

Example: Customers can redeem promotion ABC123 for 10% off merchandise only by using a single-use code, and the 10% discount has already applied to the actual prices of the order lines in the CWORDERIN message. When CWDirect creates the order, it updates the single-use code record to indicate that it was redeemed, and writes Order Transaction History messages indicating that the code was redeemed and the promotion applied; however, it does not apply an additional 10% discount to the order lines.

Different from one-time-use promotion: Unlike creating single-use promotion codes, flagging a promotion for one-time use indicates that each customer can apply the promotion just once, but does not require a unique code to apply the promotion. If you have the required authority, you can override the prohibition for a one-time-use promotion and let the customer use the promotion multiple times. See the Process One Time Use Promotion Window for information on one-time-use promotions.

In this chapter:

• Setting Up Single-Use Promotion Codes

• Applying Single-Use Promotion Codes through the Order API

• Applying Single-Use Promotion Codes in Order Entry

• Applying Single-Use Promotion Codes through the Phone Order Load

• Notes for Using Single-Use Promotion Codes

• Generate Single-Use Promotion Codes (GSUP)

• Work with Single-Use Promotion Codes (WSUP)

• CWSingleUsePromoCodeCheckRequest XML Message

• CWSingleUsePromoCodeCheckReq Sample XML

• CWSingleUsePromoCodeCheckResponse XML Message

• CWSingleUsePromoCodeCheckResponse Sample XML Messages

Setting Up Single-Use Promotion Codes

Purpose: Use the following setup options to use single-use promotion codes in your company.

System control values: Set up the following system control values:

• Use Single Use Promo Codes (L95): Set this value to Y to enable applying promotions to orders through single-use promotion codes. Once you have generated any single-use codes for a promotion through the Generate Single-Use Promotion Codes (GSUP) option, you can no longer apply that promotion to an order except through a single-use code.

• Order API/No Reprice Price Override Reason (L96): Specify a valid price override reason code for this value to prevent the system from applying any coupon or promotion discount or benefits to order lines that uses the specified price override reason code. Specifying a value here also prevents promotion benefits from applying through the order API if the Promotion Code Entry Required for Discount (I63) system control value is set to Y. See the Order API/No Reprice Price Override Reason (L96) system control value for an overview.

Create the promotion: Use the Working with Promotion Values (WPRO) option to create a promotion that you will link to single-use codes.

Generate single-use codes: Use the Generate Single-Use Promotion Codes (GSUP) option to generate a batch of random single-use codes associated with a promotion. You can then distribute the single-use codes to customers through emails, website popups, or other means.

Note: After you generate single-use codes, you can use the Work with Single-Use Promotion Codes (WSUP) to review the codes, including whether individual codes were redeemed.

Integration layer control process: Configure the queue for the SUP_INQURY process if you will use the CWSingleUsePromoCodeCheckRequest XML Message and CWSingleUsePromoCodeCheckResponse XML Message to check whether single-use codes are valid and unredeemed. See Working with Integration Layer Processes (IJCT) for more information.

Applying Single-Use Promotion Codes through the Order API

Overview: You can apply single-use promotion codes to orders through the order API and avoid applying the promotion discounting or benefits when creating the order in CWDirect if the web site has already applied the discount.

Check code status: Before using the CWORDERIN message to create the order, you can use the CWSingleUsePromoCodeCheckRequest XML Message and CWSingleUsePromoCodeCheckResponse XML Message to check whether single-use codes are valid and unredeemed.

Redeeming a single-use code on an order: If the Use Single Use Promo Codes (L95) system control value is set to Y and the single_use_promo_code attribute in the CWORDERIN message specifies a valid, unredeemed single-use code, the order API uses the Order API/No Reprice Price Override Reason (L96) system control value to control the updates to the order and to the Single Use Promo Code. See the Order API section under the Order API/No Reprice Price Override Reason (L96) system control value for details.

Single use promotion code always evaluated: If the Use Single Use Promo Codes (L95) system control value is set to Y, you can use the single_use_promo_code attribute to apply a promotion to an order regardless of the setting of the Promotion Code Entry Required for Discount (I63) system control value. However, if the single_use_promo_code does not specify a code, then the order API checks the promotion attribute only if the Promotion Code Entry Required for Discount (I63) system control value is set to Y.

Editing the order:

• If the single-use code is not valid or the promotion is not currently active, the order will be in error with a reason of Invalid Single Use Promo.

• If the single-use promotion code has already been redeemed, the order will be in error with a reason of Code Previously Redeemed.

• If the order does not qualify for the related promotion, and the Order API/No Reprice Price Override Reason (L96) system control value is blank, the promotion is not redeemed or applied, but the order is not flagged for an error; instead, the system writes an Order Transaction History message such as Promotion (SUP51+) not applied.

Note: If the Order API/No Reprice Price Override Reason (L96) system control value specifies a code, the order API does not evaluate whether the order qualifies for the promotion as long as the single-use code is valid, unredeemed, and associated with a current promotion.

Apply additional promotions? If the Promotion Code Entry Required for Discount (I63) system control value is set to N, the system can potentially apply not only the promotion associated with the single-use code, but also any additional promotions for which the order qualifies, including a second promotion of the same type as the one related to the single-use code. See When the System Assigns Promotions to an Order for a discussion.

Updates when redeeming a single-use code: See the Notes for Using Single-Use Promotion Codes.

Applying Single-Use Promotion Codes in Order Entry

Overview: If the Use Single Use Promo Codes (L95) system control value is set to Y, you can use the Enter Single Use Promotion Code Window to apply a promotion to an order by entering an associated single-use code. This option is available regardless of the setting of the Promotion Code Entry Required for Discount (I63) system control value.

Entering the single-use code: When you press F21 in order entry and enter a single-use code at the Enter Single Use Promotion Code Window, the system:

• Confirms that your entry is a valid, unredeemed single-use code associated with a current promotion, and that the order currently meets the qualifying criteria for the promotion, such as merchandise total or total unit quantity.

• Applies the associated promotion benefits to the order, provided no lines on the order use a price override reason code that match the Order API/No Reprice Price Override Reason (L96) system control value.

• flags the Single Use Promo Code record as redeemed. See the Notes for Using Single-Use Promotion Codes.

Entry of single-use promotion code always available at reprice: When you press F21 in order entry, the Enter Single Use Promotion Code Window opens regardless of the setting of the Promotion Code Entry Required for Discount (I63) system control value.

Associated promotion applied to the order: The promotion associated with the single-use code:

• defaults to the Enter Promotion/Discount Window or Enter Promotion Code Window if the Promotion Code Entry Required for Discount (I63) system control value is set to Y. If you override the promotion code at either of these windows, this removes the promotion associated with the single-use code from the order.

• is displayed at the Qualified Promotions Window if the Promotion Code Entry Required for Discount (I63) system control value is set to N.

For more information: See Notes for Using Single-Use Promotion Codes.

Applying Single-Use Promotion Codes through the Phone Order Load

Overview: If the Use Single Use Promo Codes (L95) system control value is set to Y, you can use the Single use promo code field for the ship-to in the Phone Orders file to apply the related promotion to an order. Similar to order entry, the phone order supports this option regardless of the setting of the Promotion Code Entry Required for Discount (I63) system control value.

Promotion discount always applied: Regardless of the setting of the Order API/No Reprice Price Override Reason (L96) system control value, the discount associated with the promotion related to the single-use code always applies to the order if the order qualifies.

Edits for the single-use promotion code: When you submit the order batch to the edit, either through the initial load or later through batch order entry, the system confirms that Single use promo code is a valid, unredeemed code associated with a current promotion, and that the order meets the qualifying criteria for the promotion, such as merchandise total or total unit quantity. If the order does not qualify, the system creates a record in the Phone Error file:

• S7/Code Previously Redeemed: Indicates that the single_use_promo_code specified to apply a promotion to the order has already been redeemed on another order.

• S0/Invalid Single Use Promo: Indicates that the single_use_promo_code specified to apply a promotion to the order is not valid, or the related promotion is not currently active.

For more information: See Notes for Using Single-Use Promotion Codes.

Notes for Using Single-Use Promotion Codes

Overview: The following notes apply to orders redeeming single-use promotion codes, regardless of whether you create the order through the order API, order entry, or the phone order load.

Overrides automatic assignment hierarchy: If the Promotion Code Entry Required for Discount (I63) system control value is set to N, the promotion associated with the single-use code applies to the order:

• order entry and phone order load: instead of the promotion of the same type that would normally apply based on the hierarchy described under When the System Assigns Promotions to an Order

• order API: in addition to the promotion of the same type that would normally apply based on the hierarchy described under When the System Assigns Promotions to an Order

Updating the single-use promotion code as “redeemed”: The Single Use Promo Code is updated with the Redeemed date, Redeeming order, and Redeeming ship-to, and Order Transaction History messages such as the following indicate that the single-use code was redeemed and the related promotion was applied:

6/27/13 E 2361638063 - SINGLE USE CODE. 5.00 EKAPLAN

6/27/13 E SUPORD1-10% OFF ORDER SUP TEST 5.00 EKAPLAN

Reject order or batch? If you reject the order in order entry, the system removes the redemption date, order number, and ship-to from the Single Use Promo Code record, and the single-use code remains available for use on another order.

Similarly, if the order is suspended in a batch, and you reject the batch, the system removes the redemption date, order number, and ship-to from the Single Use Promo Code record, and the single-use code remains available for use on another order.

Promotion not applied? If the single-use code specified through the phone order load or the order API is valid, unredeemed, and related to a current promotion, but the order does not qualify and the Order API/No Reprice Price Override Reason (L96) system control value is blank, or if the order closes immediately after acceptance because all items on the order are sold out, the system writes an Order Transaction History message such as:

6/28/13 Y Promotion (SUP51+) not applied EKAPLAN

In these situations in which the promotion is not applied, the single-use code is not flagged as redeemed and is available for use on a future order.

Order not qualified at acceptance? If the order qualifies for the promotion when you press F21 in order entry and enter a single-use code, but is no longer qualified for the promotion at order acceptance, the single-use code is still redeemed, even though the promotion benefits do not apply. This could happen if, for example, the related promotion has a merchandise total requirement that the order met when you entered the single-use code, but no longer met at acceptance because you removed an item.

Order canceled? If you cancel an order with a single-use code, or sell out the last item on the order, the code is still redeemed.

 

Generate Single-Use Promotion Codes (GSUP)

Purpose: Use this screen to generate a batch of random single-use codes that customers can use to apply a promotion to an order.

Once you generate any single-use codes for a promotion, if the Use Single Use Promo Codes (L95) system control value is set to Y, the promotion is no longer eligible to be applied to an order by its actual promotion code; a single-use code is required. However, the system does not prevent you from generating single-use codes even when the Use Single Use Promo Codes (L95) system control value is set to N.

How to display this screen: Select Generate Single Use Promotion Codes from a menu, or enter GSUP in the Fast path field at the top of any menu.

OER1606 ENTER Single Use Promo Code Generation 6/12/13 16:46:02 EZK Mail Order Single Use Promo code . . . . 9999000000 Promo Code . . . . . . . . . Source Code . . . . . . . . . Number of codes to generate . F3=Exit F9=Accept F12=Cancel

Field	Description
Single use promo code	Optionally, enter the lowest possible number that the system should assign as a single-use code for the promotion. For example, if you enter 5555500000, the system generates codes randomly with no code lower than 5555500000. If you generate codes lower than 1000000000, they will be zero-padded (for example, 0255907849). If you do not specify a beginning number here, the resulting single-use codes will be randomly assigned starting from 1000000000 and potentially extending through 9000000000 or higher. However, you can enter a number lower than 1000000000 to include lower, zero-padded numbers in the generation. Your most recent entry in this field, from the last time you generated single-use codes, defaults here. Alphanumeric (though your entry should be numeric); optional.
Promo code	The code identifying the actual promotion that customers can redeem using the single-use codes. The promotion must be active: the current date and time must not be earlier than the promotion’s start date and time, and must not be later than the promotion’s end date and time. Promotion codes are defined in and validated against the Promotion file; see Chapter 4: Working with Promotion Values (WPRO) for background. Once you generate any single-use codes for a promotion, if the Use Single Use Promo Codes (L95) system control value is set to Y, the promotion is no longer eligible to be applied to an order by its actual promotion code; a single-use code is required. Alphanumeric, 7 positions; required.
Source code	Optionally, enter a source code to associate with the single-use codes you are generating. Your entry is stored in the Single Use Promo Code file, but does not need to be an active source code, and is informational only. Source codes are defined in and validated against the Source Code file; see Chapter 6: Working with Source Codes (WSRC) for background. Alphanumeric, 9 positions; optional.
Number of codes to generate	The total number of single-use promotion codes to generate for the promotion. Note: This number must not exceed the total remaining numbers between your entry in the Single use promo code field and the highest possible single-use promotion code (9999999999). For example, if you enter a Single use promo code of 9999990000, then you cannot generate more than 9999 single-use codes, since that is the difference between 9999990000 and 9999999999. Numeric, 10 positions; required.

Completing this screen: Complete the fields on this screen as described above and press F9. The system generates the single-use codes in the Single Use Promo Code file and returns you to the previous screen. You can use Work with Single-Use Promotion Codes (WSUP) to review the generated codes.

Work with Single-Use Promotion Codes (WSUP)

Purpose: Use this screen to review the single-use promotion codes you have generated through the Generate Single-Use Promotion Codes (GSUP) option, including information on whether a code has been redeemed on an order.

All fields on this screen are display-only, although you can scan based on all fields except the ship-to number.

How to display this screen: Select Work with Single Use Promotion Codes from a menu, or enter WSUP in the Fast path field at the top of any menu.

OER1610 DISPLAY Work with Single Use Promo Codes 6/12/13 16:49:05 EZK Mail Order Single Use Promotion Source ------ Date ------ -- Redeeming -- Code Code Code Created Redeemed Order/Ship to 3523060982 SUPORD1 SOURCE 6/12/13 6/12/13 200412 - 1 3548654389 SUPORD1 6/12/13 6/12/13 200411 - 1 3701854995 SUPORD1 6/12/13 6/12/13 200413 - 1 3724934587 SUPORD1 6/12/13 0 - 0 3737877830 SUPORD1 6/12/13 0 - 0 3745146685 SUPORD1 6/12/13 0 - 0 3939911797 SUPORD1 6/12/13 0 - 0 3968679142 SUPORD1 6/12/13 0 - 0 4000599745 SUPORD1 6/12/13 0 - 0 4017279705 SUPORD1 6/12/13 0 - 0 4091472735 SUPORD1 6/12/13 0 - 0 4306329991 SUPORD1 6/12/13 6/12/13 200415 - 1 4353770367 SUPORD1 6/12/13 6/12/13 200414 - 1 + F3=Exit F12=Cancel

Field	Description
Single use code	A single-use codes that customers can use to apply a promotion to an order., randomly generated through the Generate Single-Use Promotion Codes (GSUP) option. Enter a full or partial single-use code to display single-use codes that are equal to or higher than your entry. Numeric, 10 positions.
Promotion code	The code identifying the actual promotion that customers can redeem using the single-use codes. See Chapter 4: Working with Promotion Values (WPRO) for background. Once you generate any single-use codes for a promotion, the promotion is no longer eligible to be applied to an order by its actual promotion code; a single-use code is required. Enter a complete, valid promotion code to display single-use codes for that promotion. Alphanumeric, 7 positions.
Source code	The source code, if any, associated with the single-use promotion. Informational only. Source codes are defined in and validated against the Source Code file; see Chapter 6: Working with Source Codes (WSRC) for background. Enter a complete, valid source code to display single-use codes assigned to that source code. Alphanumeric, 9 positions.
Date created	The date when you used the Generate Single-Use Promotion Codes (GSUP) option to generate the single-use code. Enter a date to display single-use codes created on that date. Numeric (MM/DD/YY format).
Date redeemed	The date, if any, when the single-use code was used to apply the related promotion to an order. Enter a date to display single-use codes redeemed on that date. Numeric (MM/DD/YY format).
Redeeming Order/ship to	The number identifying the order, if any, on which the single-use code as used, and the number identifying the shipping address on the order. The ship-to number can be higher than 1 if the order includes multiple shipping addresses. The order number and ship-to number are separated by a hyphen (-). The order and ship-to displayed is 0 - 0 if the single-use code has not yet been redeemed. Enter a valid order number to display single-use codes redeemed on that order. Order number: numeric, 8 positions. Ship-to number: numeric, 3 positions.

CWSingleUsePromoCodeCheckRequest XML Message

The SUP_INQURY job requires an XML request laid out as follows to indicate whether a single-use promotion code is valid and whether it has already been redeemed. The web storefront typically sends this message to CWDirect before sending the CWORDERIN message that includes the single-use promotion code.

 

For more information: See Creating and Using Single-Use Promotion Codes for background, and Working with Integration Layer Processes (IJCT) for background on integration layer jobs.

Attribute Name	Type	Length	Comments
Message
source	alpha	25	Identifies the source of the XML message.
target	alpha	25	Identifies the target of the XML message.
type	alpha	25	Should be set to CWSingleUsePromoCodeCheckReq.
CWSingleUsePromoCodeCheck
company_code	numeric	3	Indicates the company associated with the single-use promotion code. Validated against the Company file; see Setting Up Companies (WCMP).
single_use_promo_ code	numeric	10	The single-use promotion code whose validity and redemption status are being requested.

CWSingleUsePromoCodeCheckReq Sample XML

A sample of this message is below.

<Message source="WEB" target="CWDirect" type="CWSingleUsePromoCodeCheckReq">

<CWSingleUsePromoCodeCheck company_code="027" single_use_promo_code="0447517951" />

</Message>

CWSingleUsePromoCodeCheckResponse XML Message

When the SUP_INQURY job receives the CWSingleUsePromoCodeCheckRequest XML Message, it generates the response message laid out as follows.

 

For more information: See Creating and Using Single-Use Promotion Codes for background, and Working with Integration Layer Processes (IJCT) for background on integration layer jobs.

Attribute Name	Type	Length	Comments
Message
source	alpha	25	Identifies the source of the XML message, such as CWDirect.
target	alpha	25	Identifies the target of the XML message, such as WEB.
type	alpha	25	Set to CWSingleUsePromoCodeCheckResponse.
date_created	numeric	8	The date when the request message was received by CWDirect. YYYY-MM-DD format.
time_created	numeric	6	The time when the request message was received by CWDirect. HH:MM:SS format.
CWSingleUsePromoCodeCheckResponse
company_code	numeric	3	The company specified in the request message.
single_use_promo_ code	numeric	10	The single-use promotion code whose validity and redemption status are being requested.
reason	alpha	10	The current status of the single-use promotion code. Possible statuses are: • Redeemed = The single-use code has been redeemed on an order. In this case, the response message specifies the details of the promotion and the redeeming order. • Unredeemed = The code is a valid single-use code that has not yet been redeemed on an order. In this case, the response message specifies information on the promotion.
promo_code	alpha	7	The code identifying the actual promotion that the customer can apply using the single-use code. Promotion codes are defined in and validated against the Promotion file; see Chapter 4: Working with Promotion Values (WPRO) for background.
promo_start_date	numeric	8	The date when the promotion goes into effect. YYYY-MM-DD format. Included only if the single-use promotion code is valid. Note: You can also specify a time of day when the promotion goes into effect.
promo_end_date	numeric	8	The date when the promotion ends. YYYY-MM-DD format. Included only if the single-use promotion code is valid. Note: You can also specify a time of day when the promotion ends.
source_code	alpha	9	The source, if any, associated with the single-use promotion code. Included only if the single-use promotion code is valid and you specified a source code when you used the Generate Single-Use Promotion Codes (GSUP) option. Source codes are defined in and validated against the Source Code file; see Chapter 6: Working with Source Codes (WSRC) for background.
date_redeemed	numeric	8	The date, if any, when the single-use promotion code was redeemed on an order. YYYY-MM-DD format. Included only if the single-use promotion code has been redeemed.
redeeming_order_id	numeric	8	The order number, if any, on which the single-use promotion code was redeemed.
redeeming_ship_to_number	numeric	3	The ship-to number specifying the shipping address on the order, if any, on which the single-use promotion code was redeemed.

CWSingleUsePromoCodeCheckResponse Sample XML Messages

Valid and unredeemed: The following is a sample response message when the single-use code specified in the request is valid and unredeemed.

<Message source="CWDirect" target="WEB" type="CWSingleUsePromoCodeCheckResponse" date_created="2013-06-25" time_created="09:43:11">

<CWSingleUsePromoCodeCheckResponse company_code="27" single_use_promo_code="2361638063" reason="Unredeemed" promo_code="SUPORD1" promo_start_date="2013-06-11" promo_end_date="2013-07-31" source_code="BEACH01"/>

</Message>

Valid and redeemed: The following is a sample response message when the single-use code specified in the request has been redeemed on an order.

<Message source="CWDirect" target="WEB" type="CWSingleUsePromoCodeCheckResponse" date_created="2013-06-25" time_created="09:43:11">

<CWSingleUsePromoCodeCheckResponse company_code="27" single_use_promo_code="1558087792" reason="Redeemed" promo_code="SUPORD1" promo_start_date="2013-06-11" promo_end_date="2013-07-31" source_code="SOURCE" date_redeemed="2013-06-13" redeeming_order_id="200419" redeeming_ship_to_number="1" />

</Message>

Invalid: The following is a sample response message when the single-use code specified in the request is invalid.

<Message source="CWDirect" target="WEB" type="CWSingleUsePromoCodeCheckResponse" date_created="2013-06-25" time_created="09:43:11">

<CWSingleUsePromoCodeCheckResponse company_code="27" single_use_promo_code="1111111111" reason="Invalid" promo_start_date="2013-06-11" promo_end_date="2013-07-31"/>

</Message>