ClaimRowValue

Runtime verified Test scripts included

Syntax

ClaimRowValue(dataExt, returnColumn, claimColumn, fallbackValue, claimantColumn, claimantValue[, additionalColumnNameN, additionalColumnValueN, ...])  →  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
`additionalColumnNameN`	string	No	Name of a further column to write on the claimed row (record extra context at claim time). Repeatable as name/value pairs.
`additionalColumnValueN`	string	No	Value written to the paired `additionalColumnNameN` column on the claimed row

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.

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

The first six arguments are all required — the claimant pair and fallback are not optional. Some community references mark arguments 4–6 (fallbackValue, claimantColumn, claimantValue) as optional, but at runtime a three- or four-argument call aborts the page. Only the trailing additionalColumnNameN, additionalColumnValueN pairs (argument 7 onward) are optional; each pair records a further column on the claimed row, and an 8-argument call (six required plus one extra pair) rendered correctly.

Drive advancement across separate renders

AMPscript caches data-extension reads within a single render. Drive 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, @rg, @i, @code, @rs, @row, @v

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

  /* 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

  /* claimpair: 8-arg form - six required args plus one optional trailing
     name/value pair (Region). Records the extra column on the claimed row
     and still returns the scalar CouponCode. */
  IF @b == "claimpair" THEN
    SET @v = ClaimRowValue("AMP_VERIFY_CLAIM", "CouponCode", "IsClaimed", "FALLBACK", "EmailAddress", @em, "Region", @rg)
    OutputLine(Concat("claimpair em=[", @em, "] rg=[", @rg, "] -> value=[", @v, "]"))
  ENDIF
]%%

Availability

Platform	Available
Marketing Cloud Engagement	Yes
Marketing Cloud Next	Yes, from API 68.0