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

# Vouchers

> Create shareable Bitcoin gifts and promotional codes that drive engagement

Turn Bitcoin into shareable gift codes. Vouchers are redeemable payment links that let you distribute value without knowing recipients' payment details – perfect for promotions, rewards, and re-engagement campaigns.

<CardGroup cols={3}>
  <Card title="No User Details Needed" icon="user">
    Send Bitcoin without knowing Lightning addresses or gamertags
  </Card>

  <Card title="Perfect for Marketing" icon="megaphone">
    Create bulk codes for promotions, giveaways, and campaigns
  </Card>

  <Card title="Track Everything" icon="chart-line">
    Monitor redemption rates and campaign performance
  </Card>
</CardGroup>

## Why Use Vouchers?

### 🎁 User Acquisition & Retention

<Tabs>
  <Tab title="New User Onboarding">
    **The Problem**: Getting users to try your app is hard

    **The Solution**: Give them immediate value

    ```javascript theme={null}
    // Create welcome bonus vouchers
    const voucher = await zbd.createVoucher({
      amount: 1000, // sats (~$0.50)
      description: "Welcome to GameApp! 🎮"
    });

    // Send via email/SMS
    sendWelcomeEmail(user.email, voucher.code);
    ```

    **Result**: 3x higher activation rates
  </Tab>

  <Tab title="Win-Back Campaigns">
    **Re-engage Dormant Users**

    Send personalized vouchers to users who haven't been active:

    * "We miss you! Here's 2000 sats"
    * "Complete your profile for 5000 sats"
    * "Return bonus: 10,000 sats"

    **Case Study**: Game studio saw 40% of churned users return
  </Tab>

  <Tab title="Referral Programs">
    **Viral Growth Mechanics**

    ```javascript theme={null}
    // Both referrer and referee get rewards
    const referralVoucher = await createVoucher({
      amount: 5000,
      description: "Thanks for sharing!"
    });
    ```

    Users share more when they can give real value
  </Tab>
</Tabs>

### 🎯 Marketing & Promotions

<CardGroup cols={2}>
  <Card title="Social Media Giveaways">
    * Twitter/X campaigns: "RT to win!"
    * Discord events and contests
    * Twitch stream rewards
    * Community milestones
  </Card>

  <Card title="Event Marketing">
    * Conference booth traffic
    * QR code scavenger hunts
    * Workshop attendance rewards
    * Beta testing incentives
  </Card>

  <Card title="Content Marketing">
    * Survey completion rewards
    * Newsletter signup bonuses
    * Tutorial completion gifts
    * Review incentives
  </Card>

  <Card title="Partnership Campaigns">
    * Co-marketing vouchers
    * Influencer distribution
    * Cross-promotion codes
    * Sponsor activations
  </Card>
</CardGroup>

## Creating Vouchers

### Dashboard Method

Navigate to **Vouchers** in your dashboard and click **Create Voucher**:

<Frame caption="Create vouchers directly from the dashboard">
  <img src="https://mintcdn.com/zbd/NzvYJh9FFidtNwO3/img/v3/create-voucher.png?fit=max&auto=format&n=NzvYJh9FFidtNwO3&q=85&s=b384b509c4bfc6e558be315360780b07" alt="Create Voucher Interface" width="1414" height="984" data-path="img/v3/create-voucher.png" />
</Frame>

### API Method

<CodeGroup>
  ```javascript Node.js theme={null}
  // Single voucher
  const voucher = await zbd.createVoucher({
    amount: 1000, // satoshis
    description: "Thanks for playing!"
  });

  console.log(`Share this code: ${voucher.code}`);
  // Output: Share this code: ABC12345

  // Bulk creation for campaigns
  const campaign = await Promise.all(
    Array(100).fill(null).map(() => 
      zbd.createVoucher({
        amount: 500,
        description: "Launch week special"
      })
    )
  );
  ```

  ```python Python theme={null}
  # Create marketing voucher
  voucher = zbd.create_voucher(
      amount=1000,
      description="Welcome bonus"
  )

  # Generate QR code for easy sharing
  qr_url = f"https://zbd.gg/v/{voucher['code']}"
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.zbdpay.com/v0/vouchers \
    -H "apikey: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": "1000",
      "description": "Conference giveaway"
    }'
  ```
</CodeGroup>

## Distribution Strategies

### 📧 Email Campaigns

```html theme={null}
<!-- Beautiful email template -->
<div style="text-align: center; padding: 20px;">
  <h2>You've received Bitcoin! 🎉</h2>
  <p>Redeem your gift with this code:</p>
  <div style="font-size: 32px; font-weight: bold; 
              background: #f0f0f0; padding: 20px; 
              border-radius: 8px; margin: 20px;">
    ABC12345
  </div>
  <p>Redeem now!</p>
</div>
```

### 🎮 In-App Distribution

```javascript theme={null}
// Trigger voucher creation on achievement
async function rewardAchievement(userId, achievement) {
  const voucher = await zbd.createVoucher({
    amount: achievement.rewardAmount,
    description: `Achievement unlocked: ${achievement.name}`
  });
  
  // Show in-game notification
  showNotification({
    title: "Achievement Unlocked! 🏆",
    message: `You earned ${achievement.rewardAmount} sats!`,
    code: voucher.code,
    action: "Tap to redeem"
  });
}
```

## Redemption Process

### For End Users

<Tabs>
  <Tab title="Developer Dashboard">
    **Quick Redemption** (anywhere in dashboard):

    1. Open redemption modal inside Vouchers page
    2. Enter 8-character code
    3. Click "Redeem Voucher"
    4. Funds instantly added to wallet
  </Tab>

  <Tab title="ZBD App">
    **Mobile Redemption**:

    1. Tap wallet balance in navbar
    2. Select "Redeem Voucher"
    3. Enter voucher code
    4. Confirm redemption
  </Tab>
</Tabs>

### API Redemption

```javascript theme={null}
// Programmatic redemption
const result = await zbd.redeemVoucher({
  code: 'ABC12345',
});

if (result.success) {
  console.log(`Redeemed ${result.amount} sats!`);
}
```

## Managing Vouchers

### Voucher Statuses

| Status         | Description           | Action Available |
| -------------- | --------------------- | ---------------- |
| 🟢 **Valid**   | Active and redeemable | Share, Revoke    |
| ✅ **Redeemed** | Successfully claimed  | View details     |
| ❌ **Revoked**  | Cancelled by creator  | None             |

### Revoke Unused Vouchers

Cancel vouchers and reclaim funds:

<CodeGroup>
  ```javascript Node.js theme={null}
  // Revoke single voucher
  await zbd.revokeVoucher(voucherId);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.zbdpay.com/v0/vouchers/voucher_id/revoke \
    -H "apikey: YOUR_API_KEY"
  ```
</CodeGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Set Expiration Dates" icon="clock">
    Create urgency and prevent long-term liabilities
  </Card>

  <Card title="Use Descriptive Names" icon="tag">
    Track campaign performance with clear descriptions
  </Card>
</CardGroup>

## Advanced Use Cases

### 🎰 Gamified Redemption

```javascript theme={null}
// Mystery box vouchers with random amounts
function createMysteryVoucher() {
  const amounts = [100, 500, 1000, 5000, 10000];
  const random = amounts[Math.floor(Math.random() * amounts.length)];
  
  return zbd.createVoucher({
    amount: random,
    description: "Mystery Box 📦"
  });
}
```

## Common Questions

<AccordionGroup>
  <Accordion title="Do vouchers expire?">
    Yes, vouchers expire and are automatically revoked if not redeemed within 30 days. Unused funds are returned to your wallet.
  </Accordion>

  <Accordion title="Can vouchers be redeemed multiple times?">
    No, each voucher is single-use only. For recurring rewards, create multiple vouchers.
  </Accordion>
</AccordionGroup>

## Start Your First Campaign

<Steps>
  <Step title="Plan Your Campaign">
    Define goals, audience, and budget
  </Step>

  <Step title="Create Vouchers">
    Use dashboard or API for bulk creation
  </Step>

  <Step title="Distribute Codes">
    Email, social media, or in-app
  </Step>

  <Step title="Track Performance">
    Monitor redemption rates and adjust
  </Step>
</Steps>

<Card title="Ready to Drive Engagement?" icon="rocket" href="/payments/api/vouchers/create">
  **Start Creating Vouchers** - Check out our API reference for programmatic voucher creation at scale.
</Card>