ViralPayouts API

Quickstart

Create a key, then call the API with it as a bearer token. Every answer is JSON. Money is in minor units (cents) with a currency.

curl https://viralpayouts.com/api/v1/programs \
  -H "Authorization: Bearer vpk_..."

{
  "data": [ { "id": "prg_9f2c1a", "name": "Acme Pro", "status": "live", "commission": "25% of each sale", ... } ],
  "has_more": false,
  "next_cursor": null
}

Every endpoint, with its fields and an example answer, is in the API reference. The machine-readable contract is the OpenAPI 3.1 document at /api/v1/openapi.json: import it into Postman, an SDK generator or an agent.

Authentication and keys

Send a key in the Authorization header: Authorization: Bearer <key>. A key is shown once, when it is created. ViralPayouts keeps only a SHA-256 of it and its last four characters. A revoked key stops working on the next request.

A brand key on a partner endpoint answers 403 partner_key_required, and a partner key on a brand endpoint 403 brand_key_required. A record of another brand answers 404, exactly like one that does not exist.

Errors

Every error has the same shape: the HTTP status, a stable code, a message saying what happened, and next, the next step (which field to fix, which endpoint to call, which key to use). A server error also carries a requestId to quote to us.

HTTP/1.1 403 Forbidden
{
  "error": {
    "status": 403,
    "code": "role_too_low",
    "message": "This key has the viewer role, and POST /api/v1/programs needs an owner key.",
    "next": "Ask a brand owner to create a key with the owner role in the console (Integration tab, API keys), then call again with it."
  }
}

Pagination

Lists are newest first and use cursors. Send limit (1 to 100, default 25). The answer has data, has_more and next_cursor. To get the next page, send cursor=<next_cursor> with the same filters. A cursor marks the last row you saw, so new rows arriving between pages never make you see a row twice or miss one.

curl "https://viralpayouts.com/api/v1/programs/prg_9f2c1a/conversions?status=pending&limit=50&cursor=MjAyNi0xMC..." \
  -H "Authorization: Bearer vpk_..."

Rate limits

Each key may make 120 requests a minute. Every answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window ends). Past the limit the answer is 429 with Retry-After. Requests with keys that are not valid are limited too: 30 a minute from one address. The MCP endpoint has its own limit of 120 requests a minute per key.

Idempotency

Send an Idempotency-Key header (1 to 255 visible characters, a UUID is ideal) on a POST, PUT or PATCH to make a retry safe. The first answer is kept for 24 hours. The same key with the same request gets that answer again, with Idempotent-Replayed: true, and nothing runs twice. The same key with a different request gets 422 idempotency_key_reused. A retry while the first request is still running gets 409 idempotency_in_progress. A server error (5xx) is not kept, so you can retry it with the same key.

Recording a refund moves money, so POST /conversions/{conversionId}/refund requires the header. Over MCP the same value is the idempotencyKey argument.

curl -X POST https://viralpayouts.com/api/v1/conversions/cnv_0c88aa/refund \
  -H "Authorization: Bearer vpk_..." \
  -H "Idempotency-Key: 6f1c2f0e-3b7a-4c1e-9a55-2d0f7f1b8e21" \
  -H "Content-Type: application/json" \
  -d '{"amountCents": 2500}'

Event API: send sales from your server

Your backend reports each sale, refund and app event to POST https://viralpayouts.com/api/v1/events, signed with the program's signing secret (an owner key reads it from GET /programs/{programId}/integration, or copy it from the console's Integration tab). This endpoint uses the signature, not an API key.

import crypto from 'node:crypto';

const raw = JSON.stringify({ id: 'evt_1', type: 'sale', order_id: 'ord_1', amount_cents: 10000, currency: 'USD', click_id: clickId });
const ts = String(Math.floor(Date.now() / 1000));
const sig = crypto.createHmac('sha256', process.env.VP_SIGNING_SECRET).update(`${ts}.${raw}`).digest('hex');
await fetch('https://viralpayouts.com/api/v1/events', {
  method: 'POST',
  headers: { 'content-type': 'application/json', 'x-vp-program': 'prg_9f2c1a', 'x-vp-timestamp': ts, 'x-vp-signature': sig },
  body: raw,
});

The answer is { "status": "processed" | "duplicate" | "unmatched" | "error", "note", "conversionId", "signedWith" }: 200, or 422 when the status is error. unmatched means no partner could be credited (the note says why); a refund for an order not seen yet is kept and applied if the sale arrives. A body may be up to 64 KB. Each program may send 600 valid events a minute and each address may fail 20 times a minute by default; past either the answer is 429 with Retry-After.

Webhooks and postbacks

Sales coming in. Your checkout reports sales and refunds to ViralPayouts in one of three ways. GET /programs/{programId}/webhooks shows the URLs for a program and whether each secret is set; GET /programs/{programId}/events shows every event received and what happened to it.

Postbacks going out. A partner can give each program a postback URL (PUT /partner/programs/{program}/postback). When one of their sales is recorded, approved or reversed, ViralPayouts calls it once with a GET (5-second timeout, redirects not followed). A timeout, a 5xx, 408 or 429 is retried up to 6 times; another 4xx is not retried. Test sales never send one. Macros: {sub_id} {sub2} {sub3} {sub4} {sub5} {click_id} {conversion_id} {payout} {currency} {status} {event} {program}.

What the API covers

Starting payout batches, connecting payout accounts and tax forms stay in the console and the portal. The full list is in the reference.