> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.komo.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Vii Gift Cards

> Issue Vii digital gift cards to contacts automatically with workflows.

## What is it?

The Vii connected app lets your workflows create and load [Vii](https://www.vii.com.au) digital gift cards, for example for prize winners. It adds an **Issue Vii card** workflow step. The step saves a link to each new card in a workflow variable, so you can send it to the contact in an email or SMS.

> [!NOTE]
>
> Vii is only available on certain Komo plans. You also need a Vii gift card program. Vii gives you the API username, password and endpoint URL, plus the Store ID, BIN and card design code used in the workflow step. Ask Vii for a digital card design, which returns a link to the card.

## How do I set it up?

### Step 1: Connect Vii

* Click the **Workspace initials** in the top right corner, then click **Company Settings**.
* Click **Connected Apps** in the left-hand menu.
* Click **Connect** on Vii.
* Enter the **Username**, **Endpoint** (your Vii endpoint URL) and **Password** from Vii.
* Click **Connect**.

![Update Vii connection window with Username, Endpoint and a masked Password](https://mintcdn.com/komotechnologies/DYCe8G0maYmRrTPd/images/vii-connection-modal.webp?fit=max\&auto=format\&n=DYCe8G0maYmRrTPd\&q=85\&s=3edd1425de577b164f3b0e99626c25f5)

The connection applies to every workspace in your company. To change the credentials, click **Update** on the Vii tile. To remove the connection, click **Disconnect**.

### Step 2: Build your workflow

* Create a workflow at the card, hub or workspace level. See [Workflows](https://knowledge.komo.tech/integrations-automation/workflows.md).
* Set the trigger. For prize winners, use **Prize Awarded** and filter to your gift card prize.
* Search the Steps panel for **Vii**, drag in **Issue Vii card** and connect it to the trigger. It's in the **Cards and Coupons** group.
* Click the **pencil icon** on the step and fill in the fields below.

![The Issue Vii Card step with Amount, Card Design Type, Store ID, BIN, Created Card URL set to a vii\_link String variable, Limit per contact, Card Expiry Date and Grace Period Days](https://mintcdn.com/komotechnologies/DYCe8G0maYmRrTPd/images/vii-issue-card-step.webp?fit=max\&auto=format\&n=DYCe8G0maYmRrTPd\&q=85\&s=b015aa574955c77335070e3a33969b93)

| Field | What to enter |
| - | - |
| **Amount** (required) | The card value in dollars, from `5.00` to `1,000.00`. |
| **Card Design Type** (required) | The Vii code for the gift card design. Use a digital design hosted by Vii, or no card link is returned. |
| **Store ID** (required) | The store ID Vii gave you. |
| **BIN** (required) | Your gift card program's BIN number, from Vii. |
| **Created Card URL** (required) | A String workflow variable that stores the link to the new card, for example `vii_link`. Click **Manage variables** to create one. |
| **Limit per contact** | The most cards this step can issue to one contact. Leave empty for no limit. |
| **Card Expiry Date** | Overrides your Vii program's default expiry date. Leave empty to use the default. Vii must allow variable expiry on your program. |
| **Grace Period Days** | Overrides your Vii program's default grace period, in days. Leave empty to use the default. |

* Add a **Send email** or **Send SMS** step after **Issue Vii card** on the **Success** path, and include the card link, for example `{{variables.vii_link}}`.
* Click **Save**, then **Save** in the top right-hand corner.
* To start the workflow, click the **3 dots** next to it, select **Run**, then **Yes, start it**.

> [!TIP]
>
> Test with a manually awarded test prize and a low **Amount** before you go live. See [Prizes and Comms](https://knowledge.komo.tech/competitions-promotions/setup-management/prizes-and-comms.md).

### Step 3: Check your workflow runs

The step has two paths:

* **Success**: Vii created and loaded the card. The link is saved to your **Created Card URL** variable.
* **LimitExceeded**: the contact has already reached **Limit per contact**, so no card is issued. Connect a step here if you want to tell them, or leave it empty.

Open **Workflow Runs**, or **Usage** under the Workflows dropdown in **Card settings**, then open a run. A successful step shows the card number, linked to the card.

If Vii rejects the request, the step and the run show as **Errored** with Vii's response code and message. Komo automatically retries temporary errors, such as timeouts or Vii being briefly out of card stock, for a few minutes before it gives up. Fix the cause, then retry the run from [Workflow Runs](https://knowledge.komo.tech/integrations-automation/workflows/workflow-runs.md).

## FAQ

**Why does Connect say "Vii is not available on your current plan"?**

Vii isn't included in your Komo plan. Contact your Komo account manager to enable it.

**Why can't I see the Issue Vii card step in my workflow?**

Vii isn't connected for your company yet. Connect it in **Company Settings** > **Connected Apps** first.

**How does Limit per contact count cards?**

It counts the cards this step has issued to the contact across all runs of this workflow. Runs that errored or went down **LimitExceeded** don't count. The workflow needs a trigger with a contact, such as **Prize Awarded**, for the limit to work.

**Will retrying a run issue a second card?**

No. Komo sends Vii the same transaction ID every time it retries a run, including automatic retries, and Vii creates only one card per transaction ID. If the first attempt already created a card, the retry gets that same card back.

**Why is my Created Card URL variable empty?**

Your **Card Design Type** isn't a digital design hosted by Vii, so Vii returned a card without a link. Ask Vii to set up a digital design.

**Why did the step fail with "Invalid step data"?**

A required field is missing, or **Amount** is outside $5 to $1,000. Open the step, fix the field, then retry the run.

**Why did the step fail with a Vii error?**

If the error shows a Vii response code, Vii rejected the card, for example because of a wrong Store ID, BIN or card design code. If it has no response code, Vii didn't accept the request at all, so check the connection's username, password and endpoint. Fix the values with Vii, then retry the run.


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