# Set voucher as consumed

### Description

This service allows an operator to manually mark a specific voucher from a mileage catalog as "Consumed."

> ⚠️ Usage Note: This endpoint is strictly for administrative use. It is not intended for consumer-facing applications. It allows operators to update voucher states directly without going through the standard consumer checkout or redemption flow.

***

### Request

#### Restrictions

* Authentication: Requires a successful operator login.
* Access: The operator must have permissions for the specific activity and item codes provided.

#### Endpoint

```
PUT https://<server-url>/api/v4/operator/activity/{activity_code}/item/{voucher_item_code}/voucher/{voucher_code}
```

#### Path Parameters

| **Parameter**       | **Type** | **Description**                                                      |
| ------------------- | -------- | -------------------------------------------------------------------- |
| `activity_code`     | String   | The unique code of the activity associated with the voucher.         |
| `voucher_item_code` | String   | The unique code of the specific item/product the voucher represents. |
| `voucher_code`      | String   | The unique identifier/serial of the voucher to be consumed.          |

#### Parameters

| **Parameter**  | **Location**   | **Description**                                                                         |
| -------------- | -------------- | --------------------------------------------------------------------------------------- |
| `touchpoint`   | Query / Header | The identifier for the touchpoint. Use `Thalamus-Touchpoint` for the header.            |
| `token`        | Query / Header | The authentication token for the operator session. Use `Thalamus-Token` for the header. |
| `Content-Type` | Header         | Must be `application/json`.                                                             |

#### Request Body (Optional)

You may send custom metadata parameters to be stored or processed alongside the consumption event.

| **Field**      | **Type** | **Description**                                                                 |
| -------------- | -------- | ------------------------------------------------------------------------------- |
| `parameter1-3` | String   | Optional. Custom values or identifiers relevant to the consumption transaction. |

Example Body:

```
{
  "parameter1": "Valor A",
  "parameter2": "Valor B"
}
```

***

### Response

#### ✅ Successful Response: `200 OK`

Returns the updated status of the voucher and any parameters associated with the transaction.

JSON

```
{
  "code": "XWT201711230000000000",  
  "state": "CONSUMED",  
  "parameter1": "3456",  
  "parameter2": "2366",  
  "parameter3": null
}
```

***

### ❌ Unsuccessful Response

#### `400 Bad Request` or `404 Not Found`

The `errors` object will specify which part of the request or state was invalid.

| **Error Code**  | **Description**                                                                                  |
| --------------- | ------------------------------------------------------------------------------------------------ |
| `NotAnOperator` | The authenticated user does not have operator privileges.                                        |
| `NotFound`      | One of the path parameters (`activityCode`, `voucherItemCode`, or `voucherCode`) does not exist. |
| `InvalidStatus` | The voucher is in a status that does not allow consumption (e.g., already voided).               |
| `InvalidState`  | The transition to "CONSUMED" is not allowed from the current state.                              |