# How can we help?

## 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:

### 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.