← Back to Dashboard

Partner Integration API

Generate unique promo codes and receive webhooks when codes are redeemed.

Authentication

All API requests require your partner API key in the X-Partner-Key header.

X-Partner-Key: your-api-key-here

Find your API key in the Integration panel of your dashboard. Keep it secret.

Generate a Promo Code

POST /api/partners/codes/generate

Mint a unique, single-use promo code for a customer. Each code gives 100% off one CinematicCard (Signature tier). Codes expire 48 hours after generation.

Request

curl -X POST https://cinematiccard.com/api/partners/codes/generate \
  -H "X-Partner-Key: your-api-key"

No request body needed. One code is generated per call.

Response

{
  "ok": true,
  "code": "PREFIX-1A0A48C0",
  "url": "https://cinematiccard.com/?promo=PREFIX-1A0A48C0",
  "expires_at": "2026-03-18T23:29:28.917Z"
}

Field	Description
code	The unique promo code (your prefix + random hex)
url	Direct link that auto-applies the code at checkout — send this to your customer
expires_at	ISO 8601 expiry (48 hours from generation)

Error Responses

Status	Error	Meaning
401	Invalid API key	Check your X-Partner-Key header
403	Partner account is not active	Account suspended or pending approval
403	No codes remaining	Purchase more codes in your dashboard

Integration Flow

Here's how to integrate CinematicCard into your customer experience:

1. Customer clicks "Send a free CinematicCard" on your site
2. Your server calls POST /api/partners/codes/generate to mint a unique code
3. Redirect the customer to the url from the response
4. Customer lands on CinematicCard with $0.00 price — no code typing needed
5. Customer builds and sends their card
6. You receive a code.redeemed webhook (if configured)

Example (Node.js)

app.get('/free-card', async (req, res) => {
  const resp = await fetch('https://cinematiccard.com/api/partners/codes/generate', {
    method: 'POST',
    headers: { 'X-Partner-Key': process.env.CINEMATICCARD_API_KEY },
  });
  const { url } = await resp.json();
  res.redirect(url);
});

Webhooks

Configure a webhook URL in your dashboard to receive real-time notifications when a code is redeemed.

Event: code.redeemed

Sent as a POST request to your webhook URL when a customer uses one of your codes.

{
  "event": "code.redeemed",
  "partner_id": "your-partner-id",
  "code": "PREFIX-1A0A48C0",
  "card_id": "a1b2c3d4",
  "recipient_name": "Sarah",
  "occasion": "mother",
  "timestamp": "2026-03-16T20:15:00.000Z",
  "codes_remaining": 49823
}

Field	Description
code	The promo code that was redeemed
card_id	The generated card's ID
recipient_name	Who the card was made for
occasion	Card theme/occasion (e.g., "mother", "birthday-her-luxury")
codes_remaining	How many codes you have left

Event: test

Sent when you click "Test Webhook" in the dashboard. Use this to verify your endpoint is working.

{
  "event": "test",
  "partner_id": "your-partner-id",
  "timestamp": "2026-03-16T20:15:00.000Z",
  "message": "Test webhook from CinematicCard"
}

Rate Limits

Code generation: 100 requests per minute per API key. If you need higher throughput, contact us.

Code Lifecycle

• Generated — Code is active, 48-hour countdown starts
• Redeemed — Customer used the code. It's now deactivated (single-use).
• Expired — 48 hours passed without redemption. Code is no longer valid. Your balance is not affected — only redeemed codes count against your inventory.

Support

Questions? Email your dedicated VIP address shown in your dashboard.