Overview

The "reserveOne" method ensures that a single unique supplement record is used only once in the personalization of a message for an individual contact.

Once the record is used for that contact, the record is flagged with:

• Timestamp: to represent when it was printed in a message.
• mcID: to represent the unique contact and the exact message in which the record was printed.
• cID: contact ID representing the unique contact who received the coupon.

In addition to live message sends, test message sends will also flag a record as "reserved".

Data automations currently do not support the use of reserveOne method.

Our example

• Used in: Message automations
• Syntax: {$supplements->reserveOne($key, $filterOptions)}

• {$coupon.key = 'couponBank1'}
  {$coupon.filter = ['filterOptions' => ['expdate' => ['gt' => {$smarty.now|date_format:'%Y-%m-%d'}]]]}
  
  {$coupon = $supplements->reserveOne($coupon.key, $coupon.filter)}
  
  Here is your coupon code: <strong>{$coupon.code}</strong>

• In our example, these coupon codes are stored as supplement records in the couponBank1 supplement collection. We are using the expdate supplement field to filter for coupons that have not expired using the filterOptions parameter.

  {
    "code": "1234015",
    "id": "1",
    "expdate": "2023-03-23T17:45:18+0000"
  },
  {
    "code": "1234016",
    "id": "2",
    "expdate": "2023-03-23T17:45:18+0000"
  },
  {
    "code": "1234017",
    "id": "3",
    "expdate": "2023-03-23T17:45:18+0000"
  }

• Here is your coupon code: 1234015

• Parameter	Description	Required	Expected	Default
  key	A unique key created by the user for a stored supplement.	required	String	NA
  filterOptions	A filter used to query supplement records by date. Only indexed fields can be queried.	optional	Array	[]

Use case: coupon codes distributed as unique values

1. Create a new supplement. Using the coupon example, the supplement could be called "couponBank1" with an index on the code and expdate fields. The expdate field will store coupon expiration dates for filtering unexpired codes. It should be of Date data type.

This supplement should not be marked for use as a contact attribute.

2. Create a CSV file with an id, code, and expdate columns ("id" and "code" could be the same value in this case, since the codes are all unique). 

3. Import that CSV file using the supplements POST API.

4. In the Smarty template, use the Smarty syntax below to print the variable.

Example records for the "couponBank1" supplement as a .csv:

id,code,expdate
1,1234015,2023-03-23T17:45:18+0000
2,1234016,2023-03-23T17:45:18+0000
3,1234017,2023-03-23T17:45:18+0000

Example records for the "couponBank1" supplement after the import:

{
  "code": "1234015",
  "id": "1",
  "expdate": "2023-03-23T17:45:18+0000"
},
{
  "code": "1234016",
  "id": "2",
  "expdate": "2023-03-23T17:45:18+0000"
},
{
  "code": "1234017",
  "id": "3",
  "expdate": "2023-03-23T17:45:18+0000"
}

Smarty Syntax:

{$coupon=$supplements->reserveOne($key, $filterOptions)}

Using the "couponBank1" example:

{$coupon.key = 'couponBank1'}
{$coupon.filter = ['filterOptions' => ['expdate' => ['gt' => {$smarty.now|date_format:'%Y-%m-%d'}]]]}

{$coupon = $supplements->reserveOne($coupon.key, $coupon.filter)}

The above code will set the variable value for the contact. The optional filterOptions parameter can be used to filter coupons by the expdate field, ensuring only unexpired records are reserved. In this example, only coupons with an expiration date greater than the current date will be reserved. Place the variable where the value should print in the message:

Here is your coupon code: {$coupon.code}

How the supplement looks after the records are used or "reserved":

{
  "code": "1234015",
  "ct": "2016-11-15T07:08:37+0000",
  "lm": "2016-11-16T07:09:22+0000",
  "id": "1",
  "expdate": "2023-03-23T17:45:18+0000",
  "cID":"5877e79b84d1ec54b231d32b",
  "mcID":"45:3434e79b84d1ec54b231d32b:ot:5877e79b84d1ec54b231d32b",
  "reserveTS": "2016-11-16T07:09:22+0000",
},
{
  "code": "1234016",
  "ct": "2016-11-15T07:08:37+0000",
  "lm": "2016-11-16T07:09:22+0000",
  "id": "2",
  "expdate": "2023-03-23T17:45:18+0000",
  "cID":"2344e79b84d1ec54b231d32b",
  "mcID":"45:3434e79b84d1ec54b231d32b:ot:2344e79b84d1ec54b231d32b"
  "reserveTS": "2016-11-16T07:09:22+0000",
},
{
  "code": "1234017",
  "ct": "2016-11-15T07:08:37+0000",
  "lm": "2016-11-16T07:09:22+0000",
  "id": "3",
  "expdate": "2023-03-23T17:45:18+0000",
  "cID":"4444e79b84d1ec54b231d32b",
  "mcID":"45:3434e79b84d1ec54b231d32b:ot:4444e79b84d1ec54b231d32b"
  "reserveTS": "2016-11-16T07:09:22+0000",
}

Notice how cID, mcID and reserveTS are added to indicate that the supplement record has already been accessed as content in a message for a unique contact. These flags will preclude the "reserveOne" method from accessing those supplement records a second time.