Skip to content
Vauchflow Docs

Getting started

Welcome to Vauchflow — the Voucher & Promotions API built for developers.

Prerequisites

Section titled “Prerequisites”
  • A Vauchflow account (sign up free)
  • curl or any HTTP client

Quickstart

Section titled “Quickstart”

  1. Get your API key

    From your dashboard, navigate to Settings → API Keys and create a secret key (vf_sk_...).

  2. Create a campaign

    Terminal window
    curl -X POST https://api.vauchflow.com/v1/campaigns \
      -H "Authorization: Bearer vf_sk_YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Summer Sale",
        "type": "DISCOUNT",
        "rules": {
          "discount_type": "PERCENT",
          "discount_value": 20,
          "max_redemptions": 500,
          "expires_at": "2026-08-31T23:59:59Z"
        }
      }'

  3. Issue a voucher

    Terminal window
    curl -X POST https://api.vauchflow.com/v1/vouchers \
      -H "Authorization: Bearer vf_sk_YOUR_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: create-save20-001" \
      -d '{
        "code": "SAVE20",
        "campaign_id": "cmp_01HX..."
      }'

  4. Redeem atomically

    Terminal window
    curl -X POST https://api.vauchflow.com/v1/vouchers/SAVE20/redeem \
      -H "Authorization: Bearer vf_sk_YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "customer_id": "cust_external_123",
        "order_value": 89.99
      }'
    

    # Response
    # { "discount_applied": 17.998, "status": "redeemed", "remaining": 499 }

API key types

Section titled “API key types”
TypePrefixTTLScopesUse case
Secretvf_sk_IndefiniteFullServer-side only
Publishablevf_pk_IndefiniteValidate-onlyClient-side
Agentvf_ak_1–90 days (configurable)Per-tool grantsAI agents (MCP, Custom GPT)

Agent keys are available on Starter plans and above.

Free plan limits

Section titled “Free plan limits”

The Free plan is great for prototyping and integration testing, with the following limits:

LimitValue
Active campaigns1
API requests10/min for general endpoints
Voucher redemptions3/min
Webhook deliveryDisabled (paid plans only)
Analytics endpointsDisabled (returns 402 analytics_not_available with an upgrade_url)

When a Free-plan tenant hits a limit, the API returns a structured envelope:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded for Free plan",
    "meta": { "upgrade_url": "https://app.vauchflow.com/billing/upgrade" }
  }
}

Upgrade to Starter or higher for production-scale campaigns, webhooks, analytics, agent keys, and MCP integration. See pricing.

Idempotency

Section titled “Idempotency”

All write endpoints accept an Idempotency-Key header. Use a unique key per request to safely retry on network failures — you’ll get the same response without double-creating resources.

Next steps

Section titled “Next steps”