> For the complete documentation index, see [llms.txt](https://docs.mdintegrations.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mdintegrations.com/partner/exploring-features/voucher-recipes.md).

# Voucher Recipes

This page is a set of practical recipes for generating Vouchers. For the core definition of what a Voucher is and how it relates to Questionnaires and Offerings, see Vouchers & Questionnaires.

{% tabs %}
{% tab title="New patient" %}

## Generate a Voucher for a new patient

Use this when you don't yet have a `patient_id` on file — in other words, a brand-new customer starting their first intake.

{% code title="Create Voucher request" %}

```
POST https://api.mdintegrations.com/v1/partner/vouchers
{
  "hold_status": false,
  "patient_id": null,
  "questionnaire_id": "{{ questionnaireId }}",
  "case_offerings": [],
  "disease": []
}
```

{% endcode %}

Passing `patient_id: null` tells MDI to create a new Patient record as part of the intake flow. The response includes an `onboarding_url` — redirect the patient to it, or embed it, to start the flow.

{% hint style="warning" %}
`hold_status: false` here means the Encounter created from this Voucher's intake is immediately eligible for physician assignment. Set it to `true` instead if you need the Encounter held until a later step — such as checkout — completes. See Patients & Encounters for the full explanation of `hold_status`.
{% endhint %}
{% endtab %}

{% tab title="Existing patient" %}

## Generate a Voucher for an existing patient

If you already know who the patient is — a returning customer, or someone already in your system — pass their existing `patient_id` instead of `null`:

{% code title="Create Voucher request" %}

```
POST https://api.mdintegrations.com/v1/partner/vouchers
{
  "hold_status": false,
  "patient_id": "{{ existingPatientId }}",
  "questionnaire_id": "{{ questionnaireId }}",
  "case_offerings": [],
  "disease": []
}
```

{% endcode %}

Because MDI already has the patient's identity and contact details on file, this skips the demographic questions in the Questionnaire and takes them straight into the clinical intake.
{% endtab %}

{% tab title="Automation" %}

## Generate a Voucher from an Automation

Rather than calling the Voucher endpoint manually, you can trigger Voucher generation automatically from an Automation — for example, a refill-reminder workflow that, once triggered, generates a new Voucher and messages the patient with their `onboarding_url` in the same flow. This removes the manual API call entirely for recurring or predictable Voucher needs. See the refill-reminder recipe in Automations for the full workflow.

{% hint style="info" %}
However a Voucher is generated — API, Portal UI, or Automation — always redirect or embed the patient using the `onboarding_url` returned in the response. That URL is what actually links the Voucher to the patient's intake session.
{% endhint %}
{% endtab %}

{% tab title="Pharmacy override" %}

## Override the pharmacy for a Voucher

Pharmacy selection is normally tied to the Offering — each Offering has a pharmacy configured to fill the prescriptions it generates. If a specific Voucher needs to route through a different pharmacy than the one tied to its Offering, you can override it directly in the voucher-creation payload instead:

{% code title="Create Voucher request" %}

```
POST https://api.mdintegrations.com/v1/partner/vouchers
{
  "hold_status": false,
  "patient_id": null,
  "questionnaire_id": "{{ questionnaireId }}",
  "case_offerings": [],
  "disease": [],
  "pharmacy_id": "{{ overridePharmacyId }}"
}
```

{% endcode %}

Use this when a particular patient, region, or promotion needs to be filled by a pharmacy other than the Offering's default. Omit `pharmacy_id` and the Voucher falls back to the Offering's configured pharmacy, as usual.
{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mdintegrations.com/partner/exploring-features/voucher-recipes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.