ClaimRowValue()
Searches a data extension for an unclaimed row and returns a value from that row. The row that contains the value that was returned is updated in the data extension to indicate that the row has been claimed. Subsequent operations return the next unclaimed row in the data extension. This function is commonly used for managing coupon codes and redemption.
This function is similar to the ClaimRow() function. However, this function can return a fallback value if the data extension doesn’t contain any unclaimed rows. Additionally, this function returns a value from the unclaimed row, while the ClaimRow() function returns an entire row.
The ClaimRowValue() function has six parameters:
dataExt(string): Required. The data extension that contains the value to return. You must hard-code this value. If you specify an AMPscript variable for this parameter, the function returns an exception.returnValueColumn(string): Required. The name of the column that contains the data that you want the function to return.claimColumn(string): Required. The column that the function uses to track whether a row is claimed. This column must be configured in a specific way in the data extension; see Data Extension Configuration for more information.valueIfClaimed(string): Required. A fallback value that the function returns if there aren’t any unclaimed rows in the data extension.claimantColumn(string): Required. The column that the function uses to track the subscriber who claimed the row.claimantValue(string): Required. The value to enter in theclaimantColumncolumn when the function claims a row.
You can populate more than one column in the claimed row by appending additional column names and values to the end of the function.
To use this function, your data extension must contain a required (non-nullable) boolean attribute with a default value of False. The data extension must also have a column for tracking the entity that claimed a row.
This table shows the fields in a minimal data extension that you can use with this function.
| Attribute Name | Data Type | Required? | Default Value |
|---|---|---|---|
| CouponCode | Text | Yes | |
| EmailAddress | Text | No | |
| IsClaimed | Boolean | Yes | False |
| ClaimedDate | Date | No |
The ClaimedDate column isn’t strictly required to use this function. If your data extension includes this column, the function automatically inserts a timestamp in the ClaimedDate column when it claims a row. The column must be nullable, have a data type of Date, and have the name "ClaimedDate".
This example uses a data extension called "CouponCodes," which contains the data in this table.
| CouponCode | EmailAddress | IsClaimed | ClaimedDate |
|---|---|---|---|
| S5MY7BVU | False | ||
| 40PNCHO2 | False | ||
| 718BZOY0 | False | ||
| 08713TEH | False | ||
| AM0R1397 | False | ||
| ZFUX4591 | False |
To claim a coupon code from this data extension for a subscriber and make that code unavailable to other subscribers, pass the required parameters to the ClaimRowValue() function.
The code example outputs the first unclaimed coupon code in the data extension: S5MY7BVU.
The function also updates the corresponding row in the data extension to indicate that the coupon has been claimed. The data extension now resembles this example.
| CouponCode | EmailAddress | IsClaimed | ClaimedDate |
|---|---|---|---|
| S5MY7BVU | sunhi.kim@example.com | True | 8/5/2023 1:41:32 PM |
| 40PNCHO2 | False | ||
| 718BZOY0 | False | ||
| 08713TEH | False | ||
| AM0R1397 | False | ||
| ZFUX4591 | False |