ClaimRowValue

Runtime verified Test scripts included

Syntax

ClaimRowValue(dataExt, returnColumn, claimColumn, fallbackValue, claimantColumn, claimantValue)  →  string

Parameters

Name	Type	Required	Description
`dataExt`	string	Yes	Name or external key of the claimable data extension
`returnColumn`	string	Yes	Column whose value is returned from the claimed row
`claimColumn`	string	Yes	Boolean column that marks a row as claimed; must be required and default to `False`
`fallbackValue`	string	Yes	Value returned when no unclaimed rows remain
`claimantColumn`	string	Yes	Column written with the claimant value when a row is claimed
`claimantValue`	string	Yes	The value identifying who is claiming — a distinct value claims the next row; a repeated value returns that claimant’s existing value

Example

%%[
  VAR @code
  SET @code = ClaimRowValue("Coupons", "CouponCode", "IsClaimed", "SOLD OUT", "EmailAddress", emailaddr)
]%%
Your code: %%=v(@code)=%%

Each distinct claimantValue claims the next unclaimed row and returns that row’s returnColumn value. When every row is already claimed, the call returns fallbackValue (SOLD OUT above) instead.

Return value

string — the returnColumn value from the claimed row, or fallbackValue when the data extension has no unclaimed rows left. Unlike ClaimRow, which returns the whole row (and an empty row on exhaustion), ClaimRowValue returns a single scalar and the caller-supplied fallback.

Behaviour

Distinct claimants advance; a repeated claimant does not. Claiming is keyed on claimantValue. A new value claims the next unclaimed row and advances; a value that already holds a row returns that same row’s value without advancing — per-subscriber idempotency.

A claimable data extension needs the documented schema. A text primary key, a claimant text column, a required non-nullable Boolean claim column defaulting to False, and (optionally) a nullable claimant date column. This schema was created via the API and advanced correctly.

Exhaustion returns the fallback, matching the docs. When no unclaimed rows remain, the fourth argument (fallbackValue) is returned. Proven on a CloudPage: four distinct claimants advanced through C1..C4, then a fifth distinct claimant received the fallback. This is the exact behaviour the official reference describes.

Drive advancement across separate renders

AMPscript caches data-extension reads within a single render. Prove advancement across separate HTTP requests, each passing a distinct claimant — a single render that claims repeatedly reads the cached state and appears not to advance.

Show test script

%%[
  VAR @b, @em, @i, @code, @rs, @row, @v

  SET @b = RequestParameter("b")
  SET @em = RequestParameter("em")

  /* reset: reseed C1..C4 all unclaimed (delete then insert - never pass an
     empty string to the Date column, that aborts the page) */
  IF @b == "reset" THEN
    SET @rs = DeleteData("AMP_VERIFY_CLAIM", "CouponCode", "C1")
    SET @rs = DeleteData("AMP_VERIFY_CLAIM", "CouponCode", "C2")
    SET @rs = DeleteData("AMP_VERIFY_CLAIM", "CouponCode", "C3")
    SET @rs = DeleteData("AMP_VERIFY_CLAIM", "CouponCode", "C4")
    SET @rs = InsertData("AMP_VERIFY_CLAIM", "CouponCode", "C1", "IsClaimed", "False")
    SET @rs = InsertData("AMP_VERIFY_CLAIM", "CouponCode", "C2", "IsClaimed", "False")
    SET @rs = InsertData("AMP_VERIFY_CLAIM", "CouponCode", "C3", "IsClaimed", "False")
    SET @rs = InsertData("AMP_VERIFY_CLAIM", "CouponCode", "C4", "IsClaimed", "False")
    OutputLine(Concat("reset done"))
  ENDIF

  /* dump: read each known coupon row by its PK and print its claim state */
  IF @b == "dump" THEN
    FOR @i = 1 TO 4 DO
      SET @code = Concat("C", @i)
      SET @rs = LookupRows("AMP_VERIFY_CLAIM", "CouponCode", @code)
      IF RowCount(@rs) > 0 THEN
        SET @row = Row(@rs, 1)
        OutputLine(Concat(@code, ": IsClaimed=[", Field(@row, "IsClaimed"), "] EmailAddress=[", Field(@row, "EmailAddress"), "] ClaimedDate=[", Field(@row, "ClaimedDate"), "]"))
      ELSE
        OutputLine(Concat(@code, ": MISSING"))
      ENDIF
    NEXT @i
  ENDIF

  /* claim: claim the next unclaimed row for the given distinct claimant and
     return its CouponCode scalar. When exhausted, the 4th arg (FALLBACK) is
     returned instead. */
  IF @b == "claim" THEN
    SET @v = ClaimRowValue("AMP_VERIFY_CLAIM", "CouponCode", "IsClaimed", "FALLBACK", "EmailAddress", @em)
    OutputLine(Concat("claim em=[", @em, "] -> value=[", @v, "]"))
  ENDIF
]%%

Availability

Platform	Available
Marketing Cloud Engagement	Yes
Marketing Cloud Next	No