{ "openapi": "3.1.0", "info": { "title": "AffiliateRail API", "version": "2026-08-21", "description": "The REST API for AffiliateRail: every object in the product, addressable, on one consistent contract.\n\n- **Auth**: `Authorization: Bearer rail_live_…`. Test-mode keys (`rail_test_…`) work against the same organization and stamp `X-Rail-Livemode: false` on every response.\n- **Lists**: one flat envelope `{ data, has_more, total_count }`; `limit` (default 25, max 100), `starting_after` / `ending_before` cursors; `program_id` required.\n- **Expand**: `expand[]=partner` embeds the related object under the same name on every endpoint that has it. `include[]=stats` adds computed counters.\n- **Money**: integer minor units (`amount_minor`) with an explicit `currency`. Rates are basis points. Never floats, never strings.\n- **Idempotency**: send `Idempotency-Key` on any POST; the same key replays the first response for 24 hours.\n- **Rate limit**: 25 requests per second per key. `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, and `Retry-After` on 429.\n- **Errors**: `{ error: { type, code, message, param? } }`, every time.\n- **Webhooks**: the event catalogue and signing scheme are at https://app.affiliaterail.com/webhooks/llms.txt." }, "servers": [ { "url": "https://api.affiliaterail.com", "description": "Production" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "rail_live_… or rail_test_…", "description": "Create keys in Settings → API keys. Each key carries scopes; the docs name the scope every route needs." } }, "schemas": { "ProgramList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Program" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "Program": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "object": { "type": "string", "enum": [ "program" ] }, "name": { "type": "string" }, "product_name": { "type": "string" }, "website_url": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "USD", "description": "ISO-4217" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "subdomain": { "type": "string" }, "custom_domain": { "type": [ "string", "null" ] }, "terms_url": { "type": [ "string", "null" ] }, "terms_version": { "type": [ "string", "null" ] }, "cookie_days": { "type": "integer" }, "url_params": { "type": "array", "items": { "type": "string" } }, "commission_on_net_revenue": { "type": "boolean" }, "holding_period_days": { "type": "integer" }, "min_payout_minor": { "type": "integer", "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "payout_term": { "type": "string", "enum": [ "net_15", "net_30", "net_60" ] }, "payout_methods": { "type": "array", "items": { "type": "string", "enum": [ "paypal", "wise", "bank_transfer", "wire", "crypto" ] } }, "block_self_referrals": { "type": "boolean" }, "blocked_countries": { "type": "array", "items": { "type": "string" } }, "require_tax_forms": { "type": "boolean" }, "auto_payouts_enabled": { "type": "boolean" }, "processor": { "type": [ "string", "null" ], "enum": [ "stripe", "paddle", "chargebee", "manual", "api", null ] }, "stats": { "$ref": "#/components/schemas/ProgramStats" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "name", "product_name", "website_url", "currency", "status", "subdomain", "custom_domain", "terms_url", "terms_version", "cookie_days", "url_params", "commission_on_net_revenue", "holding_period_days", "min_payout_minor", "payout_term", "payout_methods", "block_self_referrals", "blocked_countries", "require_tax_forms", "auto_payouts_enabled", "processor", "created_at", "updated_at" ] }, "ProgramStats": { "type": "object", "properties": { "partners": { "type": "integer" }, "active_partners": { "type": "integer" }, "clicks": { "type": "integer" }, "referrals": { "type": "integer" }, "customers": { "type": "integer" }, "sales_minor": { "type": "integer", "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "commissions_minor": { "type": "integer", "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." } }, "required": [ "partners", "active_partners", "clicks", "referrals", "customers", "sales_minor", "commissions_minor" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "invalid_request_error", "not_found_error", "conflict_error", "rate_limit_error", "plan_error", "not_implemented_error", "api_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" } }, "required": [ "type", "code", "message" ] } }, "required": [ "error" ] }, "ProgramUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "product_name": { "type": "string", "minLength": 1 }, "website_url": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "terms_url": { "type": [ "string", "null" ], "format": "uri" }, "cookie_days": { "type": "integer", "minimum": 1, "maximum": 365 }, "commission_on_net_revenue": { "type": "boolean" }, "holding_period_days": { "type": "integer", "minimum": 0, "maximum": 180 }, "min_payout_minor": { "type": "integer", "minimum": 0, "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "payout_term": { "type": "string", "enum": [ "net_15", "net_30", "net_60" ] }, "block_self_referrals": { "type": "boolean" }, "blocked_countries": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 } }, "require_tax_forms": { "type": "boolean" } } }, "PartnerList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Partner" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "Partner": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "object": { "type": "string", "enum": [ "partner" ] }, "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "group_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?grp_", "example": "grp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`grp_…`)" }, "email": { "type": "string", "format": "email" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "language_code": { "type": [ "string", "null" ] }, "handle": { "type": "string", "description": "The `?ref=` value" }, "status": { "type": "string", "enum": [ "pending", "active", "declined", "suspended" ] }, "decline_reason": { "type": [ "string", "null" ] }, "suspension_reason": { "type": [ "string", "null" ] }, "min_payout_minor": { "type": [ "integer", "null" ], "example": 2500, "description": "Per-partner threshold override; null means the program's" }, "terms_accepted_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "terms_version": { "type": [ "string", "null" ] }, "completed_onboarding": { "type": "boolean" }, "email_first_referral": { "type": "boolean" }, "email_new_referral": { "type": "boolean" }, "email_payout_paid": { "type": "boolean" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Your own key/value data, stored as given" }, "stats": { "$ref": "#/components/schemas/PartnerStats" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "program_id", "group_id", "email", "first_name", "last_name", "display_name", "company_name", "website_url", "country_code", "language_code", "handle", "status", "decline_reason", "suspension_reason", "min_payout_minor", "terms_accepted_at", "terms_version", "completed_onboarding", "email_first_referral", "email_new_referral", "email_payout_paid", "metadata", "created_at", "updated_at" ] }, "PartnerStats": { "type": "object", "properties": { "clicks": { "type": "integer" }, "referrals": { "type": "integer" }, "customers": { "type": "integer" }, "commissions_minor": { "type": "integer", "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "paid_minor": { "type": "integer", "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." } }, "required": [ "clicks", "referrals", "customers", "commissions_minor", "paid_minor" ] }, "PartnerCreate": { "type": "object", "properties": { "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "email": { "type": "string", "format": "email" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "company_name": { "type": "string" }, "website_url": { "type": "string", "format": "uri" }, "country_code": { "type": "string", "minLength": 2, "maxLength": 2 }, "handle": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,30}[a-z0-9]$", "description": "2 to 32 chars, letters, digits, hyphens. Derived from the email when omitted." }, "group_id": { "type": "string", "pattern": "^(sample_)?grp_", "example": "grp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`grp_…`)" }, "status": { "type": "string", "enum": [ "active", "pending" ], "default": "active", "description": "`pending` puts the partner in the review queue instead of activating them" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Your own key/value data, stored as given" } }, "required": [ "program_id", "email" ] }, "PartnerUpdate": { "type": "object", "properties": { "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "website_url": { "type": [ "string", "null" ], "format": "uri" }, "country_code": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2 }, "handle": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,30}[a-z0-9]$" }, "group_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?grp_", "example": "grp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`grp_…`)" }, "min_payout_minor": { "type": [ "integer", "null" ], "minimum": 0, "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "status": { "type": "string", "enum": [ "active", "suspended" ], "description": "Suspend or reinstate. Approval of a pending partner goes through applications." }, "suspension_reason": { "type": [ "string", "null" ] }, "tag_ids": { "type": "array", "items": { "type": "string", "pattern": "^(sample_)?tag_", "example": "tag_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`tag_…`)" }, "description": "Replaces the partner's tags" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Your own key/value data, stored as given" } } }, "Deleted": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "object": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "object", "deleted" ] }, "MagicLink": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "magic_link" ] }, "partner_id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "object", "partner_id", "url", "expires_at" ] }, "GroupList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "Group": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?grp_", "example": "grp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`grp_…`)" }, "object": { "type": "string", "enum": [ "group" ] }, "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "landing_url": { "type": [ "string", "null" ] }, "is_private": { "type": "boolean" }, "is_default": { "type": "boolean" }, "stats": { "type": "object", "properties": { "partners": { "type": "integer" } }, "required": [ "partners" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "program_id", "name", "slug", "description", "landing_url", "is_private", "is_default", "created_at", "updated_at" ] }, "GroupCreate": { "type": "object", "properties": { "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "landing_url": { "type": "string", "format": "uri" }, "is_private": { "type": "boolean" } }, "required": [ "program_id", "name" ] }, "GroupUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "landing_url": { "type": [ "string", "null" ], "format": "uri" }, "is_private": { "type": "boolean" }, "is_default": { "type": "boolean", "enum": [ true ] } } }, "TagList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "Tag": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?tag_", "example": "tag_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`tag_…`)" }, "object": { "type": "string", "enum": [ "tag" ] }, "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "name": { "type": "string" }, "color": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "program_id", "name", "color", "created_at", "updated_at" ] }, "TagCreate": { "type": "object", "properties": { "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "name": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } }, "required": [ "program_id", "name" ] }, "TagUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } } }, "ApplicationList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "Application": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?app_", "example": "app_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`app_…`)" }, "object": { "type": "string", "enum": [ "application" ] }, "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "group_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?grp_", "example": "grp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`grp_…`)" }, "partner_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "email": { "type": "string" }, "answers": {}, "source": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "withdrawn" ] }, "reviewed_by_user_id": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "rejection_reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "program_id", "group_id", "partner_id", "email", "source", "status", "reviewed_by_user_id", "reviewed_at", "rejection_reason", "created_at", "updated_at" ] }, "ApplicationReject": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 1000, "description": "Shown to the applicant word for word. Blank falls back to the program's default sentence." } } }, "LinkList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "Link": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?lnk_", "example": "lnk_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`lnk_…`)" }, "object": { "type": "string", "enum": [ "link" ] }, "partner_id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "param": { "type": "string" }, "value": { "type": "string" }, "destination_url": { "type": "string" }, "url": { "type": "string", "description": "The destination with the tracking parameter applied" }, "short_url": { "type": [ "string", "null" ] }, "short_slug": { "type": [ "string", "null" ] }, "short_domain": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "rate_override": {}, "stats": { "type": "object", "properties": { "clicks": { "type": "integer" }, "referrals": { "type": "integer" }, "customers": { "type": "integer" } }, "required": [ "clicks", "referrals", "customers" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "partner_id", "param", "value", "destination_url", "url", "short_url", "short_slug", "short_domain", "label", "created_at", "updated_at" ] }, "LinkCreate": { "type": "object", "properties": { "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "partner_id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "destination_url": { "type": "string", "format": "uri" }, "value": { "type": "string", "minLength": 2, "maxLength": 64, "description": "The tracking value; defaults to the partner's handle" }, "param": { "type": "string", "minLength": 1, "maxLength": 32 }, "label": { "type": "string" } }, "required": [ "program_id", "partner_id", "destination_url" ] }, "LinkUpdate": { "type": "object", "properties": { "destination_url": { "type": "string", "format": "uri" }, "label": { "type": [ "string", "null" ] } } }, "CouponList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Coupon" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "Coupon": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?cpn_", "example": "cpn_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`cpn_…`)" }, "object": { "type": "string", "enum": [ "coupon" ] }, "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "partner_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "group_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?grp_", "example": "grp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`grp_…`)" }, "code": { "type": "string" }, "external_id": { "type": [ "string", "null" ], "description": "The processor's own promotion id, and the only thing a sale is matched on" }, "stats": { "type": "object", "properties": { "customers": { "type": "integer" } }, "required": [ "customers" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "program_id", "partner_id", "group_id", "code", "external_id", "created_at", "updated_at" ] }, "CouponCreate": { "type": "object", "properties": { "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "code": { "type": "string", "minLength": 1, "maxLength": 64 }, "partner_id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "group_id": { "type": "string", "pattern": "^(sample_)?grp_", "example": "grp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`grp_…`)" }, "external_id": { "type": "string" } }, "required": [ "program_id", "code" ] }, "CouponUpdate": { "type": "object", "properties": { "external_id": { "type": [ "string", "null" ] }, "partner_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" } } }, "ClickList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Click" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "Click": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?clk_", "example": "clk_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`clk_…`)" }, "object": { "type": "string", "enum": [ "click" ] }, "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "partner_id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "link_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?lnk_", "example": "lnk_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`lnk_…`)" }, "referral_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?ref_", "example": "ref_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`ref_…`)" }, "user_agent": { "type": [ "string", "null" ] }, "referer": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "device": { "type": [ "string", "null" ] }, "landing_url": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "program_id", "partner_id", "link_id", "referral_id", "user_agent", "referer", "country", "device", "landing_url", "created_at" ] }, "ClickCreate": { "type": "object", "properties": { "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "value": { "type": "string", "minLength": 1, "description": "The partner handle or link value the visitor arrived with" }, "param": { "type": "string", "default": "ref" }, "landing_url": { "type": "string", "format": "uri" }, "visitor_token": { "type": "string", "minLength": 8, "maxLength": 128, "description": "Your stable identifier for this visitor; the same token across clicks makes one referral" }, "referrer": { "type": "string" }, "ip": { "type": "string", "description": "Hashed on write, never stored" }, "user_agent": { "type": "string" }, "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "device": { "type": "string" } }, "required": [ "program_id", "value", "landing_url", "visitor_token" ] }, "ReferralList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Referral" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "Referral": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?ref_", "example": "ref_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`ref_…`)" }, "object": { "type": "string", "enum": [ "referral" ] }, "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "partner_id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "link_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?lnk_", "example": "lnk_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`lnk_…`)" }, "landing_url": { "type": [ "string", "null" ] }, "utm": {}, "tracked_by": { "type": "string", "enum": [ "link", "coupon", "manual", "api" ] }, "status": { "type": "string", "enum": [ "visit", "lead", "converted" ] }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "program_id", "partner_id", "link_id", "landing_url", "tracked_by", "status", "expires_at", "created_at", "updated_at" ] }, "CustomerList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "Customer": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?cus_", "example": "cus_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`cus_…`)" }, "object": { "type": "string", "enum": [ "customer" ] }, "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "partner_id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "referral_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?ref_", "example": "ref_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`ref_…`)" }, "link_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?lnk_", "example": "lnk_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`lnk_…`)" }, "coupon_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?cpn_", "example": "cpn_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`cpn_…`)" }, "processor": { "type": [ "string", "null" ], "enum": [ "stripe", "paddle", "chargebee", "manual", "api", null ] }, "external_customer_id": { "type": [ "string", "null" ] }, "external_subscription_id": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "identifier": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "lead", "trial", "active", "cancelled", "refunded", "suspended" ] }, "tracked_by": { "type": "string", "enum": [ "link", "coupon", "manual", "api" ] }, "lead_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "converted_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Your own key/value data, stored as given" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "program_id", "partner_id", "referral_id", "link_id", "coupon_id", "processor", "external_customer_id", "external_subscription_id", "email", "name", "identifier", "status", "tracked_by", "lead_at", "converted_at", "metadata", "created_at", "updated_at" ] }, "CustomerCreate": { "type": "object", "properties": { "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "partner_id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Attribute directly to a partner" }, "click_id": { "type": "string", "pattern": "^(sample_)?clk_", "example": "clk_7uSyy9FqVLCFWrdPeZaK", "description": "Or attribute through the click the visitor arrived on (one of partner_id or click_id is required)" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "identifier": { "type": "string", "description": "Your own id for this customer" }, "external_customer_id": { "type": "string", "description": "The processor's customer id, used to match incoming charges" }, "status": { "type": "string", "enum": [ "lead", "trial", "active", "cancelled", "suspended" ], "default": "lead" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Your own key/value data, stored as given" } }, "required": [ "program_id" ] }, "CustomerUpdate": { "type": "object", "properties": { "email": { "type": [ "string", "null" ], "format": "email" }, "name": { "type": [ "string", "null" ] }, "identifier": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "lead", "trial", "active", "cancelled", "suspended" ], "description": "`refunded` is written by the refund itself" }, "partner_id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Reassign; recorded as manual attribution" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Your own key/value data, stored as given" } } }, "SaleList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Sale" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "Sale": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?sale_", "example": "sale_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`sale_…`)" }, "object": { "type": "string", "enum": [ "sale" ] }, "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "customer_id": { "type": "string", "pattern": "^(sample_)?cus_", "example": "cus_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`cus_…`)" }, "partner_id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "external_charge_id": { "type": "string" }, "external_payment_intent_id": { "type": [ "string", "null" ] }, "processor": { "type": "string", "enum": [ "stripe", "paddle", "chargebee", "manual", "api" ] }, "amount_minor": { "type": "integer", "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "tax_minor": { "type": [ "integer", "null" ], "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "USD", "description": "ISO-4217" }, "billing_type": { "type": "string", "enum": [ "one_time", "subscription" ] }, "interval": { "type": [ "string", "null" ], "enum": [ "day", "week", "month", "year", null ] }, "product_id": { "type": [ "string", "null" ] }, "product_name": { "type": [ "string", "null" ] }, "is_first_sale": { "type": "boolean" }, "occurred_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "refunded_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Your own key/value data, stored as given" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "program_id", "customer_id", "partner_id", "external_charge_id", "external_payment_intent_id", "processor", "amount_minor", "tax_minor", "currency", "billing_type", "interval", "product_id", "product_name", "is_first_sale", "occurred_at", "refunded_at", "metadata", "created_at", "updated_at" ] }, "SaleCreate": { "type": "object", "properties": { "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "customer_id": { "type": "string", "pattern": "^(sample_)?cus_", "example": "cus_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`cus_…`)" }, "external_charge_id": { "type": "string", "minLength": 1, "description": "Your charge id. One charge produces at most one sale, forever." }, "amount_minor": { "type": "integer", "minimum": 0, "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "tax_minor": { "type": [ "integer", "null" ], "minimum": 0, "default": null, "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "USD", "description": "ISO-4217" }, "billing_type": { "type": "string", "enum": [ "one_time", "subscription" ], "default": "subscription" }, "interval": { "type": [ "string", "null" ], "enum": [ "day", "week", "month", "year", null ], "default": null }, "product_id": { "type": [ "string", "null" ], "default": null }, "product_name": { "type": [ "string", "null" ], "default": null }, "occurred_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Your own key/value data, stored as given" } }, "required": [ "program_id", "customer_id", "external_charge_id", "amount_minor", "currency" ] }, "RefundResult": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "refund" ] }, "sale_id": { "type": "string", "pattern": "^(sample_)?sale_", "example": "sale_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`sale_…`)" }, "voided_commissions": { "type": "integer" }, "clawback_minor": { "type": "integer", "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "refunded_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "object", "sale_id", "voided_commissions", "clawback_minor", "refunded_at" ] }, "CommissionList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Commission" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "Commission": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?com_", "example": "com_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`com_…`)" }, "object": { "type": "string", "enum": [ "commission" ] }, "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "partner_id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "sale_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?sale_", "example": "sale_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`sale_…`)" }, "customer_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?cus_", "example": "cus_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`cus_…`)" }, "flow_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?flw_", "example": "flw_7uSyy9FqVLCFWrdPeZaK", "description": "Which flow produced it" }, "flow_branch_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?flb_", "example": "flb_7uSyy9FqVLCFWrdPeZaK", "description": "And which branch" }, "kind": { "type": "string", "enum": [ "referral", "reward", "clawback" ] }, "amount_minor": { "type": "integer", "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "revenue_minor": { "type": [ "integer", "null" ], "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "USD", "description": "ISO-4217" }, "status": { "type": "string", "enum": [ "pending", "approved", "due", "paid", "rejected", "voided" ] }, "mature_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "approved_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "voided_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "void_reason": { "type": [ "string", "null" ] }, "payout_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?pyt_", "example": "pyt_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`pyt_…`)" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Your own key/value data, stored as given" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "program_id", "partner_id", "sale_id", "customer_id", "flow_id", "flow_branch_id", "kind", "amount_minor", "revenue_minor", "currency", "status", "mature_at", "approved_at", "voided_at", "void_reason", "payout_id", "metadata", "created_at", "updated_at" ] }, "CommissionCreate": { "type": "object", "properties": { "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "partner_id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "amount_minor": { "type": "integer", "minimum": 1, "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "USD", "description": "ISO-4217" }, "customer_id": { "type": "string", "pattern": "^(sample_)?cus_", "example": "cus_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`cus_…`)" }, "sale_id": { "type": "string", "pattern": "^(sample_)?sale_", "example": "sale_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`sale_…`)" }, "reason": { "type": "string", "minLength": 1, "description": "Why this commission exists; written to the audit log" } }, "required": [ "program_id", "partner_id", "amount_minor", "reason" ] }, "CommissionDecision": { "type": "object", "properties": { "reason": { "type": "string" } } }, "CommissionReject": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1 } }, "required": [ "reason" ] }, "BalanceList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Balance" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "Balance": { "type": "object", "properties": { "id": { "type": "string", "example": "bal_part_7uSyy9FqVLCFWrdPeZaK_USD", "description": "`bal__`" }, "object": { "type": "string", "enum": [ "balance" ] }, "partner_id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "USD", "description": "ISO-4217" }, "pending_minor": { "type": "integer", "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "due_minor": { "type": "integer", "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "paid_minor": { "type": "integer", "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "partner_id", "currency", "pending_minor", "due_minor", "paid_minor", "updated_at" ] }, "PayoutList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payout" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "Payout": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?pyt_", "example": "pyt_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`pyt_…`)" }, "object": { "type": "string", "enum": [ "payout" ] }, "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "partner_id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "batch_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?batch_", "example": "batch_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`batch_…`)" }, "amount_minor": { "type": "integer", "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "USD", "description": "ISO-4217" }, "method": { "type": [ "string", "null" ], "enum": [ "paypal", "wise", "bank_transfer", "wire", "crypto", null ] }, "status": { "type": "string", "enum": [ "not_eligible", "pending", "processing", "paid", "failed" ] }, "not_eligible_reason": { "type": [ "string", "null" ], "description": "Why this partner was not paid this period, in words" }, "external_id": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "period_start": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "period_end": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Your own key/value data, stored as given" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "program_id", "partner_id", "batch_id", "amount_minor", "currency", "method", "status", "not_eligible_reason", "external_id", "error_code", "error_message", "period_start", "period_end", "paid_at", "metadata", "created_at", "updated_at" ] }, "PayoutMarkPaid": { "type": "object", "properties": { "paid_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "external_id": { "type": "string", "description": "Your reference from the rail you paid through" } } }, "PayoutBatchList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutBatch" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "PayoutBatch": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?batch_", "example": "batch_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`batch_…`)" }, "object": { "type": "string", "enum": [ "payout_batch" ] }, "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "term": { "type": "string", "enum": [ "net_15", "net_30", "net_60" ] }, "period_start": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "period_end": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "USD", "description": "ISO-4217" }, "total_minor": { "type": "integer", "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "payout_count": { "type": "integer" }, "generated_by_user_id": { "type": [ "string", "null" ] }, "executed_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "program_id", "term", "period_start", "period_end", "currency", "total_minor", "payout_count", "generated_by_user_id", "executed_at", "created_at", "updated_at" ] }, "PayoutBatchRun": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "payout_batch_run" ] }, "batches": { "type": "array", "items": { "$ref": "#/components/schemas/PayoutBatch" } }, "created": { "type": "array", "items": { "type": "object", "properties": { "payout_id": { "type": "string", "pattern": "^(sample_)?pyt_", "example": "pyt_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`pyt_…`)" }, "partner_id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "USD", "description": "ISO-4217" }, "amount_minor": { "type": "integer", "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "status": { "type": "string", "enum": [ "pending", "not_eligible" ] }, "reason": { "type": [ "string", "null" ] } }, "required": [ "payout_id", "partner_id", "currency", "amount_minor", "status", "reason" ] } }, "upgraded": { "type": "array", "items": { "type": "string", "pattern": "^(sample_)?pyt_", "example": "pyt_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`pyt_…`)" } }, "refreshed": { "type": "array", "items": { "type": "string", "pattern": "^(sample_)?pyt_", "example": "pyt_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`pyt_…`)" } }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "partner_id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "USD", "description": "ISO-4217" }, "status": { "type": "string" } }, "required": [ "partner_id", "currency", "status" ] } } }, "required": [ "object", "batches", "created", "upgraded", "refreshed", "skipped" ] }, "PayoutBatchCreate": { "type": "object", "properties": { "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "period_end": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "Last instant of the earning period" }, "period_start": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "partner_ids": { "type": "array", "items": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" } }, "group_id": { "type": "string", "pattern": "^(sample_)?grp_", "example": "grp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`grp_…`)" }, "ignore_threshold": { "type": "boolean", "default": false } }, "required": [ "program_id", "period_end" ] }, "FlowList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Flow" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "Flow": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?flw_", "example": "flw_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`flw_…`)" }, "object": { "type": "string", "enum": [ "flow" ] }, "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "group_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?grp_", "example": "grp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`grp_…`)" }, "partner_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "trigger": { "type": "string", "enum": [ "new_payment", "new_signup" ] }, "action": { "type": "string", "enum": [ "generate_commission", "switch_group" ] }, "rate_type": { "type": "string", "enum": [ "percent", "fixed" ] }, "rate_value": { "type": "integer", "description": "Basis points for percent, minor units for fixed. The fallback when no branch matches." }, "approval_mode": { "type": "string", "enum": [ "immediate", "after_days", "manual" ] }, "approval_delay_days": { "type": [ "integer", "null" ] }, "priority": { "type": "integer", "description": "Lower runs first" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "switch_to_group_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?grp_", "example": "grp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`grp_…`)" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Your own key/value data, stored as given" }, "branches": { "type": "array", "items": { "$ref": "#/components/schemas/FlowBranch" } }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "program_id", "group_id", "partner_id", "name", "description", "trigger", "action", "rate_type", "rate_value", "approval_mode", "approval_delay_days", "priority", "status", "switch_to_group_id", "metadata", "branches", "created_at", "updated_at" ] }, "FlowBranch": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?flb_", "example": "flb_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`flb_…`)" }, "object": { "type": "string", "enum": [ "flow_branch" ] }, "flow_id": { "type": "string", "pattern": "^(sample_)?flw_", "example": "flw_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`flw_…`)" }, "position": { "type": "integer" }, "label": { "type": [ "string", "null" ] }, "conditions": { "$ref": "#/components/schemas/Condition" }, "rate_type": { "type": "string", "enum": [ "percent", "fixed" ] }, "rate_value": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "flow_id", "position", "label", "conditions", "rate_type", "rate_value", "created_at", "updated_at" ] }, "Condition": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string" }, "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "between", "in", "not_in", "contains", "starts_with", "is_true", "is_false" ] }, "value": {} }, "required": [ "field", "op" ] }, { "type": "object", "properties": { "all": { "type": "array", "items": { "$ref": "#/components/schemas/Condition" } } }, "required": [ "all" ] }, { "type": "object", "properties": { "any": { "type": "array", "items": { "$ref": "#/components/schemas/Condition" } } }, "required": [ "any" ] }, { "type": "object", "properties": { "not": { "$ref": "#/components/schemas/Condition" } }, "required": [ "not" ] } ], "description": "A comparison `{ field, op, value }` or a group `{ all: [...] }`, `{ any: [...] }`, `{ not: ... }`. Numeric ranges are inclusive." }, "FlowCreate": { "type": "object", "properties": { "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "name": { "type": "string", "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "group_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?grp_", "example": "grp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`grp_…`)" }, "partner_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "trigger": { "type": "string", "enum": [ "new_payment", "new_signup" ], "default": "new_payment" }, "action": { "type": "string", "enum": [ "generate_commission", "switch_group" ], "default": "generate_commission" }, "rate_type": { "type": "string", "enum": [ "percent", "fixed" ], "default": "percent" }, "rate_value": { "type": "integer", "minimum": 0, "default": 2000 }, "approval_mode": { "type": "string", "enum": [ "immediate", "after_days", "manual" ], "default": "immediate" }, "approval_delay_days": { "type": [ "integer", "null" ], "minimum": 1 }, "priority": { "type": "integer", "default": 100 }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active" }, "branches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?flb_", "example": "flb_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`flb_…`)" }, "label": { "type": [ "string", "null" ] }, "conditions": { "$ref": "#/components/schemas/Condition" }, "rate_type": { "type": "string", "enum": [ "percent", "fixed" ] }, "rate_value": { "type": "integer", "minimum": 0 } }, "required": [ "conditions", "rate_type", "rate_value" ] }, "default": [] } }, "required": [ "program_id", "name" ] }, "FlowUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": [ "string", "null" ] }, "group_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?grp_", "example": "grp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`grp_…`)" }, "partner_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "trigger": { "type": "string", "enum": [ "new_payment", "new_signup" ], "default": "new_payment" }, "action": { "type": "string", "enum": [ "generate_commission", "switch_group" ], "default": "generate_commission" }, "rate_type": { "type": "string", "enum": [ "percent", "fixed" ], "default": "percent" }, "rate_value": { "type": "integer", "minimum": 0, "default": 2000 }, "approval_mode": { "type": "string", "enum": [ "immediate", "after_days", "manual" ], "default": "immediate" }, "approval_delay_days": { "type": [ "integer", "null" ], "minimum": 1 }, "priority": { "type": "integer", "default": 100 }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active" }, "branches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?flb_", "example": "flb_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`flb_…`)" }, "label": { "type": [ "string", "null" ] }, "conditions": { "$ref": "#/components/schemas/Condition" }, "rate_type": { "type": "string", "enum": [ "percent", "fixed" ] }, "rate_value": { "type": "integer", "minimum": 0 } }, "required": [ "conditions", "rate_type", "rate_value" ] }, "default": [] } } }, "Report": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "report" ] }, "dimension": { "type": "string", "enum": [ "partner", "link", "product", "group", "tag", "period" ] }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "USD", "description": "ISO-4217" }, "from": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "to": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/ReportRow" } }, "totals": { "allOf": [ { "$ref": "#/components/schemas/ReportRow" }, { "description": "The true totals for the filter, computed without the grouping. Includes direct sales, so revenue matches the dashboard headline." } ] } }, "required": [ "object", "dimension", "currency", "from", "to", "rows", "totals" ] }, "ReportRow": { "type": "object", "properties": { "key": { "type": [ "string", "null" ], "description": "The grouping value: an id, a product name, an ISO day, or `direct`. Null is \"none\"." }, "label": { "type": "string" }, "clicks": { "type": [ "integer", "null" ] }, "leads": { "type": [ "integer", "null" ] }, "customers": { "type": "integer" }, "sales": { "type": "integer" }, "refunded": { "type": "integer" }, "revenue_minor": { "type": "integer", "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "commissions_minor": { "type": "integer", "example": 2500, "description": "Integer minor units (cents, pence). Never a float, never a string." }, "conversion_bps": { "type": [ "integer", "null" ], "description": "customers / clicks in basis points; null with no clicks" }, "refund_bps": { "type": [ "integer", "null" ] } }, "required": [ "key", "label", "clicks", "leads", "customers", "sales", "refunded", "revenue_minor", "commissions_minor", "conversion_bps", "refund_bps" ] }, "RiskFlagList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RiskFlag" } }, "has_more": { "type": "boolean" }, "total_count": { "type": "integer" } }, "required": [ "data", "has_more", "total_count" ] }, "RiskFlag": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?rsk_", "example": "rsk_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`rsk_…`)" }, "object": { "type": "string", "enum": [ "risk_flag" ] }, "kind": { "type": "string" }, "severity": { "type": "string", "enum": [ "high", "medium", "low" ] }, "status": { "type": "string", "enum": [ "open", "reviewing", "resolved", "dismissed" ] }, "evidence": { "type": "object", "additionalProperties": {}, "description": "What the check saw: rates, ids, windows" }, "partner": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "name": { "type": "string" }, "handle": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "name", "handle", "status" ] }, "customer": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "pattern": "^(sample_)?cus_", "example": "cus_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`cus_…`)" }, "label": { "type": "string" } }, "required": [ "id", "label" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "resolved_by": { "type": [ "string", "null" ] }, "resolution_note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "kind", "severity", "status", "evidence", "partner", "customer", "resolved_at", "resolved_by", "resolution_note", "created_at" ] }, "RiskFlagResolve": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "resolved", "dismissed" ], "default": "resolved", "description": "`dismissed` closes it as a false alarm" }, "note": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "What you found; required, and written to the audit log" } }, "required": [ "note" ] }, "ResourceList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Resource" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "Resource": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?res_", "example": "res_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`res_…`)" }, "object": { "type": "string", "enum": [ "resource" ] }, "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "kind": { "type": "string", "enum": [ "file", "link" ] }, "title": { "type": "string" }, "url": { "type": "string" }, "folder": { "type": [ "string", "null" ] }, "mime_type": { "type": [ "string", "null" ] }, "size_bytes": { "type": [ "integer", "null" ] }, "group_ids": { "type": "array", "items": { "type": "string", "pattern": "^(sample_)?grp_", "example": "grp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`grp_…`)" }, "description": "Empty means every group sees it" }, "tag_ids": { "type": "array", "items": { "type": "string", "pattern": "^(sample_)?tag_", "example": "tag_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`tag_…`)" } }, "position": { "type": "integer" }, "published": { "type": "boolean" }, "published_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Your own key/value data, stored as given" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "program_id", "kind", "title", "url", "folder", "mime_type", "size_bytes", "group_ids", "tag_ids", "position", "published", "published_at", "metadata", "created_at", "updated_at" ] }, "ResourceCreate": { "type": "object", "properties": { "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "url": { "type": "string", "format": "uri", "description": "Where the link points. File uploads happen in the dashboard; the API manages links and existing files." }, "folder": { "type": [ "string", "null" ], "maxLength": 60 }, "group_ids": { "type": "array", "items": { "type": "string", "pattern": "^(sample_)?grp_", "example": "grp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`grp_…`)" }, "default": [] }, "tag_ids": { "type": "array", "items": { "type": "string", "pattern": "^(sample_)?tag_", "example": "tag_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`tag_…`)" }, "default": [] }, "published": { "type": "boolean", "default": true } }, "required": [ "program_id", "title", "url" ] }, "ResourceUpdate": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "url": { "type": "string", "format": "uri", "description": "Links only; a file's URL is its blob" }, "folder": { "type": [ "string", "null" ], "maxLength": 60 }, "group_ids": { "type": "array", "items": { "type": "string", "pattern": "^(sample_)?grp_", "example": "grp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`grp_…`)" } }, "tag_ids": { "type": "array", "items": { "type": "string", "pattern": "^(sample_)?tag_", "example": "tag_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`tag_…`)" } }, "published": { "type": "boolean" } } }, "CampaignList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } }, "has_more": { "type": "boolean" }, "total_count": { "type": "integer" } }, "required": [ "data", "has_more", "total_count" ] }, "Campaign": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?camp_", "example": "camp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`camp_…`)" }, "object": { "type": "string", "enum": [ "campaign" ] }, "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "name": { "type": "string" }, "subject": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "sending", "paused", "sent" ] }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "stats": { "type": "object", "properties": { "total": { "type": "integer" }, "queued": { "type": "integer" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "opened": { "type": "integer" }, "skipped": { "type": "integer" } }, "required": [ "total", "queued", "sent", "failed", "opened", "skipped" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "program_id", "name", "subject", "status", "scheduled_at", "sent_at", "stats", "created_at", "updated_at" ] }, "CampaignSend": { "type": "object", "properties": { "program_id": { "type": "string" } }, "required": [ "program_id" ] }, "SequenceList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Sequence" } }, "has_more": { "type": "boolean" }, "total_count": { "type": "integer" } }, "required": [ "data", "has_more", "total_count" ] }, "Sequence": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?seq_", "example": "seq_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`seq_…`)" }, "object": { "type": "string", "enum": [ "sequence" ] }, "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "trigger": { "type": "string", "enum": [ "approved", "idle", "first_commission" ] }, "trigger_days": { "type": [ "integer", "null" ] }, "steps": { "type": "integer" }, "counts": { "type": "object", "properties": { "enrolled": { "type": "integer" }, "active": { "type": "integer" }, "completed": { "type": "integer" } }, "required": [ "enrolled", "active", "completed" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "program_id", "name", "status", "trigger", "trigger_days", "steps", "counts", "created_at", "updated_at" ] }, "SequenceAction": { "type": "object", "properties": { "program_id": { "type": "string" } }, "required": [ "program_id" ] }, "SequenceResume": { "type": "object", "properties": { "program_id": { "type": "string" } }, "required": [ "program_id" ] }, "WebhookEndpointList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?whe_", "example": "whe_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`whe_…`)" }, "object": { "type": "string", "enum": [ "webhook_endpoint" ] }, "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "partner_id": { "type": [ "string", "null" ], "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "url": { "type": "string" }, "event_types": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "secret": { "type": "string", "description": "Shown once, on creation" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "program_id", "partner_id", "url", "event_types", "enabled", "created_at", "updated_at" ] }, "WebhookEndpointCreate": { "type": "object", "properties": { "program_id": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "url": { "type": "string", "format": "uri" }, "event_types": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Empty means every event" } }, "required": [ "program_id", "url" ] }, "WebhookEndpointUpdate": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "event_types": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" } } }, "TaxFormStatusList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaxFormStatus" } }, "has_more": { "type": "boolean", "description": "Pass the last object's id as `starting_after` to fetch the next page" }, "total_count": { "type": "integer", "description": "Count of every object matching the filters, ignoring the cursor" } }, "required": [ "data", "has_more", "total_count" ] }, "TaxFormStatus": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(sample_)?tax_", "example": "tax_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`tax_…`)" }, "object": { "type": "string", "enum": [ "tax_form_status" ] }, "partner_id": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "type": { "type": "string", "enum": [ "w9", "w8ben", "w8bene" ] }, "status": { "type": "string", "enum": [ "not_required", "required", "submitted", "expired", "superseded" ] }, "entity_type": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "signed_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-08-21T10:15:30.000Z", "description": "ISO-8601, UTC" } }, "required": [ "id", "object", "partner_id", "type", "status", "entity_type", "country_code", "signed_at", "expires_at", "created_at", "updated_at" ] } }, "parameters": {} }, "paths": { "/v1/programs": { "get": { "tags": [ "Programs" ], "summary": "List programs", "description": "Every program in your organization. The one list that does not take `program_id`.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "required": false, "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "Programs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/programs/{id}": { "get": { "tags": [ "Programs" ], "summary": "Retrieve a program", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "required": true, "description": "Prefixed id (`prg_…`)", "name": "id", "in": "path" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "No relations on this resource" }, "required": false, "description": "No relations on this resource", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Extras to include: stats" }, "required": false, "description": "Extras to include: stats", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "The program", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Program" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Programs" ], "summary": "Update a program", "description": "Settings a merchant can change from the API. Portal branding and processor connections stay in the app.\n\n**Scope:** `write`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?prg_", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`prg_…`)" }, "required": true, "description": "Prefixed id (`prg_…`)", "name": "id", "in": "path" } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramUpdate" } } } }, "responses": { "200": { "description": "The updated program", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Program" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/partners": { "get": { "tags": [ "Partners" ], "summary": "List partners", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Required on every list" }, "required": true, "description": "Required on every list", "name": "program_id", "in": "query" }, { "schema": { "type": "string", "example": "25", "description": "1 to 100, default 25" }, "required": false, "description": "1 to 100, default 25", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page after it (older)" }, "required": false, "description": "Object id; returns the page after it (older)", "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page before it (newer)" }, "required": false, "description": "Object id; returns the page before it (newer)", "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: group" }, "required": false, "description": "Relations to embed: group", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Extras to include: stats, tags" }, "required": false, "description": "Extras to include: stats, tags", "name": "include[]", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "active", "declined", "suspended" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "group_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "email", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "handle", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "search", "in": "query" } ], "responses": { "200": { "description": "Partners", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Partners" ], "summary": "Create a partner", "description": "Adds a partner directly (`status: active`) or into the review queue (`status: pending`). The handle is derived from the email when omitted.\n\n**Scope:** `partners:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerCreate" } } } }, "responses": { "201": { "description": "The new partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Partner" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Email or handle already in use", "content": { "application/json": { "schema": {} } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/partners/{id}": { "get": { "tags": [ "Partners" ], "summary": "Retrieve a partner", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "required": true, "description": "Prefixed id (`part_…`)", "name": "id", "in": "path" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: group" }, "required": false, "description": "Relations to embed: group", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Extras to include: stats, tags" }, "required": false, "description": "Extras to include: stats, tags", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "The partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Partner" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Partners" ], "summary": "Update a partner", "description": "**Scope:** `partners:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "required": true, "description": "Prefixed id (`part_…`)", "name": "id", "in": "path" } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerUpdate" } } } }, "responses": { "200": { "description": "The updated partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Partner" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Partners" ], "summary": "Delete a partner", "description": "Removes the partner and everything attributed to them: links, referrals, customers, commissions, payouts. Not reversible.\n\n**Scope:** `partners:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "required": true, "description": "Prefixed id (`part_…`)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/partners/{id}/sso": { "post": { "tags": [ "Partners" ], "summary": "Mint a sign-in link", "description": "A single-use magic link that signs the partner straight into their portal. Fifteen-minute life. Drop it into your own emails or app.\n\n**Scope:** `partners:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?part_", "example": "part_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`part_…`)" }, "required": true, "description": "Prefixed id (`part_…`)", "name": "id", "in": "path" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 86400 } } } } } }, "responses": { "201": { "description": "The link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MagicLink" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Magic links are not available yet", "content": { "application/json": { "schema": {} } } } } } }, "/v1/groups": { "get": { "tags": [ "Groups" ], "summary": "List groups", "description": "A group is the commission and approval axis: flows scope to it. Presentation and tags are separate, so one group never has to carry seven concerns.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Required on every list" }, "required": true, "description": "Required on every list", "name": "program_id", "in": "query" }, { "schema": { "type": "string", "example": "25", "description": "1 to 100, default 25" }, "required": false, "description": "1 to 100, default 25", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page after it (older)" }, "required": false, "description": "Object id; returns the page after it (older)", "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page before it (newer)" }, "required": false, "description": "Object id; returns the page before it (newer)", "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "No relations on this resource" }, "required": false, "description": "No relations on this resource", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Extras to include: stats" }, "required": false, "description": "Extras to include: stats", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "Groups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Groups" ], "summary": "Create a group", "description": "**Scope:** `partners:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupCreate" } } } }, "responses": { "201": { "description": "The new group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/groups/{id}": { "get": { "tags": [ "Groups" ], "summary": "Retrieve a group", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?grp_", "example": "grp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`grp_…`)" }, "required": true, "description": "Prefixed id (`grp_…`)", "name": "id", "in": "path" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "No relations on this resource" }, "required": false, "description": "No relations on this resource", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Extras to include: stats" }, "required": false, "description": "Extras to include: stats", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "The group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Groups" ], "summary": "Update a group", "description": "`is_default: true` makes this the group new partners land in and clears the flag on the previous default.\n\n**Scope:** `partners:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?grp_", "example": "grp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`grp_…`)" }, "required": true, "description": "Prefixed id (`grp_…`)", "name": "id", "in": "path" } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupUpdate" } } } }, "responses": { "200": { "description": "The updated group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Groups" ], "summary": "Delete a group", "description": "Partners in it are left without a group; flows scoped to it are deleted with it. The default group cannot be deleted.\n\n**Scope:** `partners:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?grp_", "example": "grp_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`grp_…`)" }, "required": true, "description": "Prefixed id (`grp_…`)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tags": { "get": { "tags": [ "Tags" ], "summary": "List tags", "description": "Tags are the free second axis: flows, campaigns, notifications and resources can all target them.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Required on every list" }, "required": true, "description": "Required on every list", "name": "program_id", "in": "query" }, { "schema": { "type": "string", "example": "25", "description": "1 to 100, default 25" }, "required": false, "description": "1 to 100, default 25", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page after it (older)" }, "required": false, "description": "Object id; returns the page after it (older)", "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page before it (newer)" }, "required": false, "description": "Object id; returns the page before it (newer)", "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "No relations on this resource" }, "required": false, "description": "No relations on this resource", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "Tags", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Tags" ], "summary": "Create a tag", "description": "**Scope:** `partners:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagCreate" } } } }, "responses": { "201": { "description": "The new tag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tags/{id}": { "get": { "tags": [ "Tags" ], "summary": "Retrieve a tag", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?tag_", "example": "tag_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`tag_…`)" }, "required": true, "description": "Prefixed id (`tag_…`)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The tag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Tags" ], "summary": "Update a tag", "description": "**Scope:** `partners:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?tag_", "example": "tag_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`tag_…`)" }, "required": true, "description": "Prefixed id (`tag_…`)", "name": "id", "in": "path" } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagUpdate" } } } }, "responses": { "200": { "description": "The updated tag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Tags" ], "summary": "Delete a tag", "description": "**Scope:** `partners:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?tag_", "example": "tag_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`tag_…`)" }, "required": true, "description": "Prefixed id (`tag_…`)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/applications": { "get": { "tags": [ "Applications" ], "summary": "List applications", "description": "A real object with history: who applied, when, what they answered, who decided and why.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Required on every list" }, "required": true, "description": "Required on every list", "name": "program_id", "in": "query" }, { "schema": { "type": "string", "example": "25", "description": "1 to 100, default 25" }, "required": false, "description": "1 to 100, default 25", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page after it (older)" }, "required": false, "description": "Object id; returns the page after it (older)", "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page before it (newer)" }, "required": false, "description": "Object id; returns the page before it (newer)", "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner, group" }, "required": false, "description": "Relations to embed: partner, group", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "withdrawn" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "partner_id", "in": "query" } ], "responses": { "200": { "description": "Applications", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/applications/{id}": { "get": { "tags": [ "Applications" ], "summary": "Retrieve an application", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?app_", "example": "app_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`app_…`)" }, "required": true, "description": "Prefixed id (`app_…`)", "name": "id", "in": "path" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner, group" }, "required": false, "description": "Relations to embed: partner, group", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "The application", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/applications/{id}/approve": { "post": { "tags": [ "Applications" ], "summary": "Approve an application", "description": "The partner becomes active, the reviewer and time are recorded, `application.approved` and `affiliate.confirmed` fire, and the applicant gets the approval email with your overrides and sending domain. Refused when the application was already decided, or when your plan's revenue meter blocks new approvals.\n\n**Scope:** `partners:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?app_", "example": "app_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`app_…`)" }, "required": true, "description": "Prefixed id (`app_…`)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The approved application", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/applications/{id}/reject": { "post": { "tags": [ "Applications" ], "summary": "Reject an application", "description": "The partner is declined and told why: your `reason` reaches them word for word, and a blank one falls back to the program's default sentence. `application.rejected` fires.\n\n**Scope:** `partners:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?app_", "example": "app_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`app_…`)" }, "required": true, "description": "Prefixed id (`app_…`)", "name": "id", "in": "path" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationReject" } } } }, "responses": { "200": { "description": "The rejected application", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Application" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/links": { "get": { "tags": [ "Links" ], "summary": "List links", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Required on every list" }, "required": true, "description": "Required on every list", "name": "program_id", "in": "query" }, { "schema": { "type": "string", "example": "25", "description": "1 to 100, default 25" }, "required": false, "description": "1 to 100, default 25", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page after it (older)" }, "required": false, "description": "Object id; returns the page after it (older)", "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page before it (newer)" }, "required": false, "description": "Object id; returns the page before it (newer)", "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner" }, "required": false, "description": "Relations to embed: partner", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Extras to include: stats" }, "required": false, "description": "Extras to include: stats", "name": "include[]", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "partner_id", "in": "query" } ], "responses": { "200": { "description": "Links", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Links" ], "summary": "Create a link", "description": "A destination plus a tracking value. The value defaults to the partner's handle; a custom value must be unique in the program.\n\n**Scope:** `partners:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkCreate" } } } }, "responses": { "201": { "description": "The new link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/links/{id}": { "get": { "tags": [ "Links" ], "summary": "Retrieve a link", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?lnk_", "example": "lnk_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`lnk_…`)" }, "required": true, "description": "Prefixed id (`lnk_…`)", "name": "id", "in": "path" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner" }, "required": false, "description": "Relations to embed: partner", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Extras to include: stats" }, "required": false, "description": "Extras to include: stats", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "The link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Links" ], "summary": "Update a link", "description": "Changing the destination never rewrites the tracking value: published links keep working.\n\n**Scope:** `partners:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?lnk_", "example": "lnk_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`lnk_…`)" }, "required": true, "description": "Prefixed id (`lnk_…`)", "name": "id", "in": "path" } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkUpdate" } } } }, "responses": { "200": { "description": "The updated link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Links" ], "summary": "Delete a link", "description": "The link stops being listed and cannot be retrieved again. The URL itself keeps redirecting for anyone still holding it, and its click history stays grouped under it, because deleting a link a partner has already published would break a promise they made to their own audience.\n\n**Scope:** `partners:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?lnk_", "example": "lnk_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`lnk_…`)" }, "required": true, "description": "Prefixed id (`lnk_…`)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/coupons": { "get": { "tags": [ "Coupons" ], "summary": "List coupons", "description": "Coupon codes are created by you in your payment processor and registered here so a checkout that used one is attributed to the partner.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Required on every list" }, "required": true, "description": "Required on every list", "name": "program_id", "in": "query" }, { "schema": { "type": "string", "example": "25", "description": "1 to 100, default 25" }, "required": false, "description": "1 to 100, default 25", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page after it (older)" }, "required": false, "description": "Object id; returns the page after it (older)", "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page before it (newer)" }, "required": false, "description": "Object id; returns the page before it (newer)", "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner, group" }, "required": false, "description": "Relations to embed: partner, group", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Extras to include: stats" }, "required": false, "description": "Extras to include: stats", "name": "include[]", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "partner_id", "in": "query" } ], "responses": { "200": { "description": "Coupons", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Coupons" ], "summary": "Create a coupon", "description": "**Scope:** `partners:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponCreate" } } } }, "responses": { "201": { "description": "The new coupon", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/coupons/{id}": { "get": { "tags": [ "Coupons" ], "summary": "Retrieve a coupon", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?cpn_", "example": "cpn_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`cpn_…`)" }, "required": true, "description": "Prefixed id (`cpn_…`)", "name": "id", "in": "path" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner, group" }, "required": false, "description": "Relations to embed: partner, group", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Extras to include: stats" }, "required": false, "description": "Extras to include: stats", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "The coupon", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Coupons" ], "summary": "Update a coupon", "description": "**Scope:** `partners:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?cpn_", "example": "cpn_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`cpn_…`)" }, "required": true, "description": "Prefixed id (`cpn_…`)", "name": "id", "in": "path" } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponUpdate" } } } }, "responses": { "200": { "description": "The updated coupon", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Coupons" ], "summary": "Delete a coupon", "description": "**Scope:** `partners:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?cpn_", "example": "cpn_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`cpn_…`)" }, "required": true, "description": "Prefixed id (`cpn_…`)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/clicks": { "get": { "tags": [ "Clicks" ], "summary": "List clicks", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Required on every list" }, "required": true, "description": "Required on every list", "name": "program_id", "in": "query" }, { "schema": { "type": "string", "example": "25", "description": "1 to 100, default 25" }, "required": false, "description": "1 to 100, default 25", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page after it (older)" }, "required": false, "description": "Object id; returns the page after it (older)", "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page before it (newer)" }, "required": false, "description": "Object id; returns the page before it (newer)", "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner, link, referral" }, "required": false, "description": "Relations to embed: partner, link, referral", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "partner_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "link_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "referral_id", "in": "query" } ], "responses": { "200": { "description": "Clicks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClickList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Clicks" ], "summary": "Record a click", "description": "Server-side tracking: the same resolution `rail.js` uses (handle first, then custom link values). An unknown value is a 404, not a silent drop. The same `visitor_token` across clicks joins one referral.\n\n**Scope:** `commissions:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClickCreate" } } } }, "responses": { "201": { "description": "The click, attached to its referral", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Click" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/clicks/{id}": { "get": { "tags": [ "Clicks" ], "summary": "Retrieve a click", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?clk_", "example": "clk_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`clk_…`)" }, "required": true, "description": "Prefixed id (`clk_…`)", "name": "id", "in": "path" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner, link, referral" }, "required": false, "description": "Relations to embed: partner, link, referral", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "The click", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Click" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/referrals": { "get": { "tags": [ "Referrals" ], "summary": "List referrals", "description": "A referral is a unique visit, not a person. It moves `visit` -> `lead` -> `converted` and expires at `expires_at`, written from the program's cookie window at creation.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Required on every list" }, "required": true, "description": "Required on every list", "name": "program_id", "in": "query" }, { "schema": { "type": "string", "example": "25", "description": "1 to 100, default 25" }, "required": false, "description": "1 to 100, default 25", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page after it (older)" }, "required": false, "description": "Object id; returns the page after it (older)", "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page before it (newer)" }, "required": false, "description": "Object id; returns the page before it (newer)", "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner, link" }, "required": false, "description": "Relations to embed: partner, link", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "partner_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "visit", "lead", "converted" ] }, "required": false, "name": "status", "in": "query" } ], "responses": { "200": { "description": "Referrals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/referrals/{id}": { "get": { "tags": [ "Referrals" ], "summary": "Retrieve a referral", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?ref_", "example": "ref_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`ref_…`)" }, "required": true, "description": "Prefixed id (`ref_…`)", "name": "id", "in": "path" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner, link" }, "required": false, "description": "Relations to embed: partner, link", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "The referral", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Referral" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers", "description": "Six explicit statuses, `refunded` included. The envelope is the same flat `{ data, has_more, total_count }` as every other list.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Required on every list" }, "required": true, "description": "Required on every list", "name": "program_id", "in": "query" }, { "schema": { "type": "string", "example": "25", "description": "1 to 100, default 25" }, "required": false, "description": "1 to 100, default 25", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page after it (older)" }, "required": false, "description": "Object id; returns the page after it (older)", "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page before it (newer)" }, "required": false, "description": "Object id; returns the page before it (newer)", "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner, referral, link" }, "required": false, "description": "Relations to embed: partner, referral, link", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "partner_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "lead", "trial", "active", "cancelled", "refunded", "suspended" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "email", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "external_customer_id", "in": "query" } ], "responses": { "200": { "description": "Customers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Customers" ], "summary": "Create a customer", "description": "Through a click (`click_id`, the referral's identity carries over and the partner is whoever owns it) or directly to a partner (`partner_id`, recorded as `tracked_by: api`). Set `external_customer_id` so charges you send later match.\n\n**Scope:** `commissions:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreate" } } } }, "responses": { "201": { "description": "The new customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Retrieve a customer", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?cus_", "example": "cus_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`cus_…`)" }, "required": true, "description": "Prefixed id (`cus_…`)", "name": "id", "in": "path" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner, referral, link" }, "required": false, "description": "Relations to embed: partner, referral, link", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "The customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Customers" ], "summary": "Update a customer", "description": "`partner_id` reassigns the customer; the change is recorded as manual attribution and shown to both partners.\n\n**Scope:** `commissions:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?cus_", "example": "cus_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`cus_…`)" }, "required": true, "description": "Prefixed id (`cus_…`)", "name": "id", "in": "path" } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdate" } } } }, "responses": { "200": { "description": "The updated customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Customers" ], "summary": "Delete a customer", "description": "Refused once the customer has sales: money that moved stays on the ledger.\n\n**Scope:** `commissions:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?cus_", "example": "cus_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`cus_…`)" }, "required": true, "description": "Prefixed id (`cus_…`)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sales": { "get": { "tags": [ "Sales" ], "summary": "List sales", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Required on every list" }, "required": true, "description": "Required on every list", "name": "program_id", "in": "query" }, { "schema": { "type": "string", "example": "25", "description": "1 to 100, default 25" }, "required": false, "description": "1 to 100, default 25", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page after it (older)" }, "required": false, "description": "Object id; returns the page after it (older)", "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page before it (newer)" }, "required": false, "description": "Object id; returns the page before it (newer)", "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner, customer" }, "required": false, "description": "Relations to embed: partner, customer", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "partner_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "customer_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "occurred_after", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "occurred_before", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "refunded", "in": "query" } ], "responses": { "200": { "description": "Sales", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaleList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Sales" ], "summary": "Record a sale", "description": "Charge -> sale -> commission -> balance, atomically, through the same writer the processor webhooks use. Idempotent on `external_charge_id`: sending the same charge twice returns the same sale with a 200 instead of a 201. `amount_minor` is gross; tax is subtracted before the rate when the program commissions on net revenue. Customer auto-enrol runs on processor webhooks, not on this endpoint.\n\n**Scope:** `commissions:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaleCreate" } } } }, "responses": { "200": { "description": "Already recorded: the existing sale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sale" } } } }, "201": { "description": "The new sale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sale" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sales/{id}": { "get": { "tags": [ "Sales" ], "summary": "Retrieve a sale", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?sale_", "example": "sale_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`sale_…`)" }, "required": true, "description": "Prefixed id (`sale_…`)", "name": "id", "in": "path" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner, customer" }, "required": false, "description": "Relations to embed: partner, customer", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "The sale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sale" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sales/{id}/refund": { "post": { "tags": [ "Sales" ], "summary": "Refund a sale", "description": "Voids the sale's unpaid commissions; an already-paid commission becomes a clawback against the partner's next balance. Replay-safe: refunding twice is a no-op.\n\n**Scope:** `commissions:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?sale_", "example": "sale_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`sale_…`)" }, "required": true, "description": "Prefixed id (`sale_…`)", "name": "id", "in": "path" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "refunded_at": { "type": "string", "format": "date-time" }, "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "What the refund did", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/commissions": { "get": { "tags": [ "Commissions" ], "summary": "List commissions", "description": "Every commission says which flow and which branch produced it.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Required on every list" }, "required": true, "description": "Required on every list", "name": "program_id", "in": "query" }, { "schema": { "type": "string", "example": "25", "description": "1 to 100, default 25" }, "required": false, "description": "1 to 100, default 25", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page after it (older)" }, "required": false, "description": "Object id; returns the page after it (older)", "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page before it (newer)" }, "required": false, "description": "Object id; returns the page before it (newer)", "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner, customer, sale, payout, flow" }, "required": false, "description": "Relations to embed: partner, customer, sale, payout, flow", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "partner_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "approved", "due", "paid", "rejected", "voided" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "sale_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "payout_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "referral", "reward", "clawback" ] }, "required": false, "name": "kind", "in": "query" } ], "responses": { "200": { "description": "Commissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommissionList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Commissions" ], "summary": "Create a manual commission", "description": "A commission the engine did not produce: a bonus, or a missed referral attached to a sale. Approved on creation, held for the program's holding period, audited with your reason.\n\n**Scope:** `commissions:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommissionCreate" } } } }, "responses": { "201": { "description": "The new commission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Commission" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/commissions/{id}": { "get": { "tags": [ "Commissions" ], "summary": "Retrieve a commission", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?com_", "example": "com_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`com_…`)" }, "required": true, "description": "Prefixed id (`com_…`)", "name": "id", "in": "path" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner, customer, sale, payout, flow" }, "required": false, "description": "Relations to embed: partner, customer, sale, payout, flow", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "The commission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Commission" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/commissions/{id}/approve": { "post": { "tags": [ "Commissions" ], "summary": "Approve a commission", "description": "`pending` -> `approved`, or straight to `due` when the holding period has already run. Anything else is refused with the reason.\n\n**Scope:** `commissions:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?com_", "example": "com_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`com_…`)" }, "required": true, "description": "Prefixed id (`com_…`)", "name": "id", "in": "path" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommissionDecision" } } } }, "responses": { "200": { "description": "The commission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Commission" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/commissions/{id}/reject": { "post": { "tags": [ "Commissions" ], "summary": "Reject a commission", "description": "Unpaid only. The reason is required and lands in the audit log and the partner's view.\n\n**Scope:** `commissions:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?com_", "example": "com_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`com_…`)" }, "required": true, "description": "Prefixed id (`com_…`)", "name": "id", "in": "path" } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommissionReject" } } } }, "responses": { "200": { "description": "The commission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Commission" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/balances": { "get": { "tags": [ "Balances" ], "summary": "List balances", "description": "One row per partner per currency: `pending_minor` (earned, inside the hold), `due_minor` (payable now), `paid_minor` (sent). Ordered by partner then currency; the cursor is a balance id.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Required on every list" }, "required": true, "description": "Required on every list", "name": "program_id", "in": "query" }, { "schema": { "type": "string", "example": "25", "description": "1 to 100, default 25" }, "required": false, "description": "1 to 100, default 25", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page after it (older)" }, "required": false, "description": "Object id; returns the page after it (older)", "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page before it (newer)" }, "required": false, "description": "Object id; returns the page before it (newer)", "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner" }, "required": false, "description": "Relations to embed: partner", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "partner_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "currency", "in": "query" } ], "responses": { "200": { "description": "Balances", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/balances/{id}": { "get": { "tags": [ "Balances" ], "summary": "Retrieve a balance", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "bal_part_7uSyy9FqVLCFWrdPeZaK_USD" }, "required": true, "name": "id", "in": "path" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner" }, "required": false, "description": "Relations to embed: partner", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "The balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/payouts": { "get": { "tags": [ "Payouts" ], "summary": "List payouts", "description": "`not_eligible` payouts carry the reason in words. Nothing is dropped silently.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Required on every list" }, "required": true, "description": "Required on every list", "name": "program_id", "in": "query" }, { "schema": { "type": "string", "example": "25", "description": "1 to 100, default 25" }, "required": false, "description": "1 to 100, default 25", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page after it (older)" }, "required": false, "description": "Object id; returns the page after it (older)", "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page before it (newer)" }, "required": false, "description": "Object id; returns the page before it (newer)", "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner, batch" }, "required": false, "description": "Relations to embed: partner, batch", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "partner_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "batch_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "not_eligible", "pending", "processing", "paid", "failed" ] }, "required": false, "name": "status", "in": "query" } ], "responses": { "200": { "description": "Payouts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/payouts/{id}": { "get": { "tags": [ "Payouts" ], "summary": "Retrieve a payout", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?pyt_", "example": "pyt_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`pyt_…`)" }, "required": true, "description": "Prefixed id (`pyt_…`)", "name": "id", "in": "path" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner, batch" }, "required": false, "description": "Relations to embed: partner, batch", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "The payout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/payouts/{id}/mark_paid": { "post": { "tags": [ "Payouts" ], "summary": "Mark a payout paid", "description": "You paid it yourself, outside the connected rails. Moves the commissions to `paid` and the money from due to paid. Allowed from `pending` and `failed`; never while a rail has it in flight, never twice.\n\n**Scope:** `payouts:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?pyt_", "example": "pyt_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`pyt_…`)" }, "required": true, "description": "Prefixed id (`pyt_…`)", "name": "id", "in": "path" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutMarkPaid" } } } }, "responses": { "200": { "description": "The payout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/payout_batches": { "get": { "tags": [ "Payout batches" ], "summary": "List payout batches", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Required on every list" }, "required": true, "description": "Required on every list", "name": "program_id", "in": "query" }, { "schema": { "type": "string", "example": "25", "description": "1 to 100, default 25" }, "required": false, "description": "1 to 100, default 25", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page after it (older)" }, "required": false, "description": "Object id; returns the page after it (older)", "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page before it (newer)" }, "required": false, "description": "Object id; returns the page before it (newer)", "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "No relations on this resource" }, "required": false, "description": "No relations on this resource", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "Batches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutBatchList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Payout batches" ], "summary": "Generate a payout batch", "description": "Turns every `due` commission up to `period_end` into payouts, one per partner per currency, netting clawbacks and applying the threshold, payout-method and tax-form checks. Idempotent per partner per month: a second run for the same month skips partners already paid and re-evaluates the not-eligible ones. Money does not move; this creates the payable set.\n\n**Scope:** `payouts:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutBatchCreate" } } } }, "responses": { "201": { "description": "What the run produced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutBatchRun" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/payout_batches/{id}": { "get": { "tags": [ "Payout batches" ], "summary": "Retrieve a payout batch", "description": "The payouts inside it are `GET /v1/payouts?batch_id=…`.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?batch_", "example": "batch_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`batch_…`)" }, "required": true, "description": "Prefixed id (`batch_…`)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutBatch" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/flows": { "get": { "tags": [ "Flows" ], "summary": "List flows", "description": "Ordered by `priority` then specificity (partner beats group beats program-wide). Each flow carries its ordered `branches`; the first matching branch wins, falling back to the flow's own rate.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Required on every list" }, "required": true, "description": "Required on every list", "name": "program_id", "in": "query" }, { "schema": { "type": "string", "example": "25", "description": "1 to 100, default 25" }, "required": false, "description": "1 to 100, default 25", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page after it (older)" }, "required": false, "description": "Object id; returns the page after it (older)", "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page before it (newer)" }, "required": false, "description": "Object id; returns the page before it (newer)", "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: group, partner" }, "required": false, "description": "Relations to embed: group, partner", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" }, { "schema": { "type": "string", "enum": [ "active", "inactive" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "group_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "partner_id", "in": "query" } ], "responses": { "200": { "description": "Flows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Flows" ], "summary": "Create a flow", "description": "Counts against the plan's flow quota. Scope to a group or a partner, not both.\n\n**Scope:** `commissions:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowCreate" } } } }, "responses": { "201": { "description": "The new flow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Flow" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/flows/{id}": { "get": { "tags": [ "Flows" ], "summary": "Retrieve a flow", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?flw_", "example": "flw_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`flw_…`)" }, "required": true, "description": "Prefixed id (`flw_…`)", "name": "id", "in": "path" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: group, partner" }, "required": false, "description": "Relations to embed: group, partner", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "The flow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Flow" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Flows" ], "summary": "Update a flow", "description": "Send the whole flow. `branches` replaces the list: branches with an `id` are kept (and the commissions citing them keep pointing at them), the rest are created, omitted ones are deleted.\n\n**Scope:** `commissions:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?flw_", "example": "flw_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`flw_…`)" }, "required": true, "description": "Prefixed id (`flw_…`)", "name": "id", "in": "path" } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowUpdate" } } } }, "responses": { "200": { "description": "The updated flow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Flow" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Flows" ], "summary": "Delete a flow", "description": "Commissions it produced keep their `flow_id` for the audit trail.\n\n**Scope:** `commissions:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?flw_", "example": "flw_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`flw_…`)" }, "required": true, "description": "Prefixed id (`flw_…`)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reports": { "get": { "tags": [ "Reports" ], "summary": "Run a report", "description": "Clicks, leads, customers, sales, refunds, revenue and commissions, cut by `dimension` over an inclusive range. Rows keyed `direct` are money that arrived without a partner; filtering by partner, group or tag reports that slice of the partner programme and excludes direct money.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK" }, "required": true, "name": "program_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "partner", "link", "product", "group", "tag", "period" ], "default": "partner" }, "required": false, "name": "dimension", "in": "query" }, { "schema": { "type": "string", "description": "ISO date, inclusive. Defaults to twelve months back." }, "required": false, "description": "ISO date, inclusive. Defaults to twelve months back.", "name": "from", "in": "query" }, { "schema": { "type": "string", "description": "ISO date, inclusive. Defaults to now." }, "required": false, "description": "ISO date, inclusive. Defaults to now.", "name": "to", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "partner_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "group_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tag_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "day", "week", "month" ], "default": "month", "description": "Bucket size for the period dimension" }, "required": false, "description": "Bucket size for the period dimension", "name": "granularity", "in": "query" } ], "responses": { "200": { "description": "The report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/risk_flags": { "get": { "tags": [ "Risk" ], "summary": "List risk flags", "description": "Highest severity first, newest first within one. `evidence` carries what the check saw. New flags are created by the risk checks, which run on plans with fraud monitoring; history stays readable on every plan.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "program_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "open", "reviewing", "resolved", "dismissed" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "partner_id", "in": "query" }, { "schema": { "type": "string", "description": "1 to 100, default 50" }, "required": false, "description": "1 to 100, default 50", "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Risk flags", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskFlagList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/risk_flags/{id}": { "get": { "tags": [ "Risk" ], "summary": "Retrieve a risk flag", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?rsk_" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "The risk flag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskFlag" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/risk_flags/{id}/resolve": { "post": { "tags": [ "Risk" ], "summary": "Resolve a risk flag", "description": "Closes the flag as `resolved` (acted on) or `dismissed` (false alarm). The note is required: it is the audit trail for why a fraud signal was waved through or acted on, and the change lands in the audit log naming your API key.\n\n**Scope:** `write`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?rsk_" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskFlagResolve" } } } }, "responses": { "200": { "description": "The closed flag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskFlag" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/resources": { "get": { "tags": [ "Resources" ], "summary": "List resources", "description": "Everything on the shelf, folders flattened onto each row. Empty `group_ids` and `tag_ids` mean every partner sees it.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Required on every list" }, "required": true, "description": "Required on every list", "name": "program_id", "in": "query" }, { "schema": { "type": "string", "example": "25", "description": "1 to 100, default 25" }, "required": false, "description": "1 to 100, default 25", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page after it (older)" }, "required": false, "description": "Object id; returns the page after it (older)", "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page before it (newer)" }, "required": false, "description": "Object id; returns the page before it (newer)", "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "No relations on this resource" }, "required": false, "description": "No relations on this resource", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "Resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Resources" ], "summary": "Create a link resource", "description": "A link on the shelf, published straight away unless you say otherwise. File uploads happen in the dashboard.\n\n**Scope:** `write`", "security": [ { "bearerAuth": [] } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceCreate" } } } }, "responses": { "201": { "description": "The new resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/resources/{id}": { "get": { "tags": [ "Resources" ], "summary": "Retrieve a resource", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?res_", "example": "res_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`res_…`)" }, "required": true, "description": "Prefixed id (`res_…`)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Resources" ], "summary": "Update a resource", "description": "Title, folder, audience scoping and `published`; `url` on links only. Moving folders puts the resource at the end of the new one.\n\n**Scope:** `write`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?res_", "example": "res_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`res_…`)" }, "required": true, "description": "Prefixed id (`res_…`)", "name": "id", "in": "path" } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceUpdate" } } } }, "responses": { "200": { "description": "The resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Resources" ], "summary": "Delete a resource", "description": "Files also lose their stored blob, best effort.\n\n**Scope:** `write`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?res_", "example": "res_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`res_…`)" }, "required": true, "description": "Prefixed id (`res_…`)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/campaigns": { "get": { "tags": [ "Messaging" ], "summary": "List campaigns", "description": "Newest first, with delivery stats. Drafts are composed in the dashboard.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "program_id", "in": "query" } ], "responses": { "200": { "description": "Campaigns", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/campaigns/{id}": { "get": { "tags": [ "Messaging" ], "summary": "Retrieve a campaign", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?camp_" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "program_id", "in": "query" } ], "responses": { "200": { "description": "The campaign", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/campaigns/{id}/send": { "post": { "tags": [ "Messaging" ], "summary": "Send a campaign", "description": "Sends a draft or paused campaign now, to the audience saved on it: the audience is queued atomically and the sender runs exactly as the dashboard's Send button. Refused when nobody matches the audience or the campaign is not sendable from its current state.\n\n**Scope:** `write`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?camp_" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignSend" } } } }, "responses": { "200": { "description": "The campaign, now sending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sequences": { "get": { "tags": [ "Messaging" ], "summary": "List sequences", "description": "Every sequence with its trigger, step count and enrolment counts.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "program_id", "in": "query" } ], "responses": { "200": { "description": "Sequences", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sequences/{id}/pause": { "post": { "tags": [ "Messaging" ], "summary": "Pause a sequence", "description": "Nobody is dropped: a paused sequence advances nobody, and resuming carries each partner on from the step they were on.\n\n**Scope:** `write`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?seq_" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceAction" } } } }, "responses": { "200": { "description": "The paused sequence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sequence" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sequences/{id}/resume": { "post": { "tags": [ "Messaging" ], "summary": "Resume a sequence", "description": "Turns a paused sequence back on. Each enrolled partner carries on from the step they were on.\n\n**Scope:** `write`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?seq_" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceResume" } } } }, "responses": { "200": { "description": "The active sequence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sequence" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook_endpoints": { "get": { "tags": [ "Webhook endpoints" ], "summary": "List webhook endpoints", "description": "The event catalogue, payload examples and signature verification are published at https://app.affiliaterail.com/webhooks/llms.txt.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Required on every list" }, "required": true, "description": "Required on every list", "name": "program_id", "in": "query" }, { "schema": { "type": "string", "example": "25", "description": "1 to 100, default 25" }, "required": false, "description": "1 to 100, default 25", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page after it (older)" }, "required": false, "description": "Object id; returns the page after it (older)", "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page before it (newer)" }, "required": false, "description": "Object id; returns the page before it (newer)", "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "No relations on this resource" }, "required": false, "description": "No relations on this resource", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "Endpoints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Webhook endpoints" ], "summary": "Create a webhook endpoint", "description": "HTTPS, public address only. The response carries `secret` exactly once.\n\n**Scope:** `webhooks:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreate" } } } }, "responses": { "201": { "description": "The new endpoint, with its secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook_endpoints/{id}": { "get": { "tags": [ "Webhook endpoints" ], "summary": "Retrieve a webhook endpoint", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?whe_", "example": "whe_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`whe_…`)" }, "required": true, "description": "Prefixed id (`whe_…`)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Webhook endpoints" ], "summary": "Update a webhook endpoint", "description": "**Scope:** `webhooks:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?whe_", "example": "whe_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`whe_…`)" }, "required": true, "description": "Prefixed id (`whe_…`)", "name": "id", "in": "path" } ], "requestBody": { "description": "", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointUpdate" } } } }, "responses": { "200": { "description": "The updated endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Webhook endpoints" ], "summary": "Delete a webhook endpoint", "description": "**Scope:** `webhooks:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?whe_", "example": "whe_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`whe_…`)" }, "required": true, "description": "Prefixed id (`whe_…`)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook_endpoints/{id}/rotate_secret": { "post": { "tags": [ "Webhook endpoints" ], "summary": "Rotate the signing secret", "description": "Deliveries after this call are signed with the new secret, and with the old one as well for 24 hours (two `v1=` entries in `Rail-Signature`), so you can swap at your own pace.\n\n**Scope:** `webhooks:write` (or `write`)", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?whe_", "example": "whe_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`whe_…`)" }, "required": true, "description": "Prefixed id (`whe_…`)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The endpoint, with its new secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook_endpoints/{id}/deliveries": { "get": { "tags": [ "Webhook endpoints" ], "summary": "Recent deliveries", "description": "The last 50 attempts: status, attempt count, response code, and the exact body we sent.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?whe_", "example": "whe_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`whe_…`)" }, "required": true, "description": "Prefixed id (`whe_…`)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deliveries, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "has_more": { "type": "boolean" }, "total_count": { "type": "integer" } }, "required": [ "data", "has_more", "total_count" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook_events": { "get": { "tags": [ "Webhook endpoints" ], "summary": "The event catalogue", "description": "Every event type an endpoint can subscribe to, with a description and an example payload.\n\n**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Event types", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" }, "example": {} }, "required": [ "type", "description" ] } }, "has_more": { "type": "boolean" }, "total_count": { "type": "integer" } }, "required": [ "data", "has_more", "total_count" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tax_form_statuses": { "get": { "tags": [ "Tax forms" ], "summary": "List tax-form statuses", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "prg_7uSyy9FqVLCFWrdPeZaK", "description": "Required on every list" }, "required": true, "description": "Required on every list", "name": "program_id", "in": "query" }, { "schema": { "type": "string", "example": "25", "description": "1 to 100, default 25" }, "required": false, "description": "1 to 100, default 25", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page after it (older)" }, "required": false, "description": "Object id; returns the page after it (older)", "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "description": "Object id; returns the page before it (newer)" }, "required": false, "description": "Object id; returns the page before it (newer)", "name": "ending_before", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner" }, "required": false, "description": "Relations to embed: partner", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "partner_id", "in": "query" }, { "schema": { "type": "string", "enum": [ "not_required", "required", "submitted", "expired", "superseded" ] }, "required": false, "name": "status", "in": "query" } ], "responses": { "200": { "description": "Statuses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxFormStatusList" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tax_form_statuses/{id}": { "get": { "tags": [ "Tax forms" ], "summary": "Retrieve a tax-form status", "description": "**Scope:** `read`", "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^(sample_)?tax_", "example": "tax_7uSyy9FqVLCFWrdPeZaK", "description": "Prefixed id (`tax_…`)" }, "required": true, "description": "Prefixed id (`tax_…`)", "name": "id", "in": "path" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Relations to embed: partner" }, "required": false, "description": "Relations to embed: partner", "name": "expand[]", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Nothing to include on this resource" }, "required": false, "description": "Nothing to include on this resource", "name": "include[]", "in": "query" } ], "responses": { "200": { "description": "The status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxFormStatus" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in your organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The request was understood and refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited: see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": {} }