> ## Documentation Index
> Fetch the complete documentation index at: https://docs-provider.voucher.allride.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Dynamic links

> Render links from Link Templates at redemption.

## Dynamic links

A **Link Template** is a URL with `{{placeholders}}` that is rendered when a voucher is redeemed. Use it in two ways:

* **Code sets with a link**: `linkTemplate` in the set's content renders a link next to each code, for example `https://acme-scooters.example.com/r?c={{code}}`. The consumer gets both the code and the link.
* **Link sets with personal links**: the `value` of each link voucher may itself contain placeholders, for example `https://acme-scooters.example.com/unlock/{{voucherId}}`. `{{code}}` is not allowed there.

Templates are checked when you submit content and when you add vouchers. Test one at any time with the preview operation:

```bash theme={null}
curl -sS -X POST "$VOUCHER_API_BASE_URL/provider/v1/link-templates:preview" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "acmescooters://promo?code={{code}}&v={{voucherId}}",
    "voucherKind": "code",
    "allowedLinkSchemes": ["acmescooters"],
    "sample": {"code": "A B&C"}
  }'
```

The answer is always 200: `valid`, `renderedUrl`, `scheme`, `linkStyle` (`web` for https, `app` for a custom scheme), the `placeholders` used, and `issues` when the template is invalid (`invalid-link-template`, `link-host-not-allowed`, `scheme-not-allowed`, `unknown-placeholder`, `placeholder-in-host`).

## Placeholders

| Placeholder | Value |
| - | - |
| `{{code}}` | The voucher value (code sets only) |
| `{{voucherId}}` | Voucher id |
| `{{redemptionId}}` | Redemption id |
| `{{voucherSetId}}` | Voucher set id |
| `{{providerSlug}}` | Your partner slug |
| `{{voucher.metadata.<key>}}` | A top-level string or number from the voucher's `metadata`; a missing key renders as an empty string |

Data about consumers or their customers (redemption entity, link metadata, consumer identity) is **never** available to templates. Any other placeholder → `unknown-placeholder`.

## Encoding

* Placeholders may appear **only in the path, query or fragment**. Scheme, host and port are literal, so they can always be checked (`placeholder-in-host` otherwise).
* Every substituted value is percent-encoded as an RFC 3986 component: the code `A B&C` renders as `A%20B%26C`.
* The rendered link must parse again with an allowed host or scheme. If it does not, the redemption fails without using up a voucher, and AllRide is alerted.

Example: `https://acme-scooters.example.com/r?c={{code}}&v={{voucherId}}` with code `A B&C` and voucher 5030 renders `https://acme-scooters.example.com/r?c=A%20B%26C&v=5030`.

## Allowed hosts

* **https links**: the host must be listed in the set's `allowedLinkHosts` (up to 10 hosts, not under AllRide's own domain). It is required as soon as an https link can occur: on `link` sets and on code sets with an https `linkTemplate`.
* **App deep links**: a custom scheme such as `acmescooters://` must be listed in `allowedLinkSchemes` (up to 3, lower-case, pattern `^[a-z][a-z0-9+.-]{1,31}$`). Dashboards show app links only as an "Open in app" button.
* `javascript`, `data`, `vbscript`, `file`, `blob`, `about`, `http` and `intent` are always refused, and `https` belongs in `allowedLinkHosts`, not in `allowedLinkSchemes`.
* Both lists are content and change through change requests. A change request that removes a host or scheme still used by available link vouchers or by the template → 422 `link-host-in-use`; revoke those vouchers first.

## Related

* [Voucher sets](https://docs-provider.voucher.allride.io/provider/voucher-sets.md#content-fields)
* [Vouchers and uploads](https://docs-provider.voucher.allride.io/provider/vouchers-and-uploads.md)
* [Content rules](https://docs-provider.voucher.allride.io/provider/content-rules.md#links)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.