# Voucher Management

Our Voucher Management APIs allow you to manage clients, orders, and voucher distributions efficiently.

## Requirements

| Vista Product Component | Capability | Minimum Required Version |
|  --- | --- | --- |
| Voucher Third-party Service | VOUCHERMANGEMENT | 5.0.15.19 |


## Managing Third-Party Client Vouchers

These APIs follow our asynchronous [Operation Result Token](/integration-platform/getting-started/operation-result-tokens) pattern. This means operations return a token that must be used in a follow-up call to retrieve the final result.

Below is a high-level overview of the key workflows and data fields. For full details, refer to the [API reference documentation](https://developer.vista.co/openapi/integration-platform/reference/overview/).

### Clients

Clients represent your corporate customers, and all voucher orders are associated with them.

#### Endpoint

```http
POST /api/v1/voucher-management/client
```

#### Sample Request Body (abbreviated)

```json
{
  "code": "ABC123",
  "name": "Vista",
  "contact": {
    "name": "John Smith",
    "email": "johnsmith@vista.co",
    "phone": "0211231234",
    "fax": ""
  },
  "externalClientId": "xyz123",
  "externalData": "my additional free-text reference data",
  "voucherTypeCodes": ["VOUCHERTYPE1", "VOUCHERTYPE2"]
}
```

#### Key Fields

- `externalClientId`: A searchable identifier for cross-referencing this client in your system.
- `externalData`: A free-text field for storing additional metadata about the client.


#### Response

Returns an [Operation Result Token](/integration-platform/getting-started/operation-result-tokens) that resolves to the client ID:

```json
{
  "responses": [
    {
      "operationResultToken": "aGVsbG8gd..."
    }
  ]
}
```

### Client Orders

Creates a client order and issues vouchers.

#### Endpoint

```http
POST /api/v1/voucher-management/client-order
```

#### Sample Request Body (abbreviated)

```json
{
  "clientCode": "ABC123",
  "reference": "My internal ref #1234",
  "electronicDistribution": true,
  "externalUserId": "User-123",
  "deliveryAddress": {
    ...
  },
  "externalData": "my additional free-text reference data",
  "vouchers": [
    {
      "productCode": "ABC12",
      "quantity": 5,
      "salePrice": 12.34,
      "redeemPrice": 12.34,
      "expiryDate": "2024-02-01T00:00:00Z"
    }
  ]
}
```

#### Key Fields

- `externalUserId`: A searchable identifier for the user who created the order.
- `externalData`: A customizable field for attaching additional metadata to the order.


#### Response

Returns an operation token to be resolved for final order status:

```json
{
  "responses": [
    {
      "operationResultToken": "Vm91Y2hlckNsaWVudE..."
    }
  ]
}
```

Large orders may take a long time to process, the resolve [Operation Result Token](/integration-platform/getting-started/operation-result-tokens) API endpoint returns a status field indicating the processing status.

```json
[
  {
    "operationResultToken": "Vm91Y2hlckNsaWVudE...",
    "entityId": "6052",
    "status": "Processing",
    "entityType": "VoucherClientOrder"
  }
]
```

### Distributions

Distributions send vouchers to recipients via email or mobile.

Currently, **only external distribution** is supported. Vista-managed internal distribution is not yet available.

#### Email Distribution

```http
POST /api/v1/voucher-management/email-distribution
```

#### Mobile Distribution

```http
POST /api/v1/voucher-management/mobile-distribution
```

#### Common Key Fields

- `distributionData`: Free-text metadata, such as image links or personalized messages.
- `externallyDistributed`: Must be `true`.


```json
{
  "reference": "abc",
  "distributionData": "string",
  "distributionItems": [
    {
      "clientOrderItemId": 1234,
      "quantityPerRecipient": 123
    }
  ],
  "externallyDistributed": true,
  ...
}
```

#### Response Handling

The distribution creation endpoints return a separate Operation Result Token for each distribution item requested.

You can resolve all tokens in a single request using the [Resolve Operation Result Tokens](/integration-platform/getting-started/operation-result-tokens) API endpoint.