ClaimRow()

Returns the first unclaimed row from a data extension. The row that was returned is updated in the data extension to indicate that it 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 ClaimRowValue() function. However, the ClaimRowValue() function can return a fallback value if the data extension doesn’t contain any unclaimed rows, while this function returns an exception if there aren’t any unclaimed rows. Additionally, this function returns an entire row, while the ClaimRowValue() function returns a value from the unclaimed row.

Availability

Syntax

ClaimRow(dataExt,
         claimColumn,
         claimantColumn1, claimantValue1,
         [claimantColumn2, claimantValue2 ...])

The ClaimRow() function has four 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.
• 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.
• 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 the claimantColumn column 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.

Data Extension Configuration

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.

note: 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".

Usage

This example uses a data extension called "CouponCodes," which contains the data in this table.

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 ClaimRow() function.

%%[
  Var @emailAddress, @couponCodeRow, @couponCode
  Set @emailAddress = AttributeValue("emailAddr")
  Set @couponCodeRow = ClaimRow("CouponCode",
                                /* Column that denotes claim status */
                                "IsClaimed",
                                /* Column to populate when claiming the row */
                                "EmailAddress",
                                /* Value to populate column with when claiming the row */
                                @emailAddress
                                )
  Set @couponCode = Field(@couponCodeRow,"CouponCode")
]%%
<p>Your coupon code is %%=v(@couponCode)=%%</p>

The code example outputs the first unclaimed coupon code in the data extension:

Your coupon code is 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.

See Also

• ClaimRowValue()