{"openapi":"3.1.0","info":{"title":"OpenPromoter API","version":"1.0.0","description":"Partner programs, tracking, commissions and payouts. Payouts prepared by API always need a person to approve them in the dashboard.","license":{"name":"AGPL-3.0","url":"https://www.gnu.org/licenses/agpl-3.0.html"}},"servers":[{"url":"https://app.openpromoter.com/api/v1"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key from Settings > API & webhooks"}}},"paths":{"/events":{"get":{"summary":"Events (same payloads as webhooks) after a cursor with the oldest first. Used by `openpromoter listen`.","tags":["Events"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"after","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/programs":{"get":{"summary":"List programs in the workspace","tags":["Programs"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/programs/{programId}/stats":{"get":{"summary":"Totals for a period (revenue, commissions, clicks, signups, customers, MRR, owed)","tags":["Programs"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"programId","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","required":false,"schema":{"default":30,"type":"integer","minimum":1,"maximum":730}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/programs/{programId}/partners":{"get":{"summary":"List partners with the newest first","tags":["Partners"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"programId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"before","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","approved","rejected","paused","banned"]}},{"name":"recruitedBy","in":"query","required":false,"schema":{"description":"Two-tier: only partners recruited by this partner id","type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}},"post":{"summary":"Invite (create and approve) a partner","tags":["Partners"],"security":[{"bearer":[]}],"x-scope":"partners:write","parameters":[{"name":"programId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"name":{"type":"string","minLength":1,"maxLength":120},"website":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"country":{"anyOf":[{"type":"string","minLength":2,"maxLength":2},{"type":"null"}]},"recruiterCode":{"description":"Two-tier: code of the approved partner who recruited this one","anyOf":[{"type":"string","maxLength":64},{"type":"null"}]}},"required":["email","name"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/partners/{partnerId}":{"get":{"summary":"Get a partner with links","tags":["Partners"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"partnerId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}},"patch":{"summary":"Change a partner's status or tier","tags":["Partners"],"security":[{"bearer":[]}],"x-scope":"partners:write","parameters":[{"name":"partnerId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"status":{"type":"string","enum":["approved","rejected","paused","banned"]},"groupId":{"type":"string"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/partners/{partnerId}/links":{"post":{"summary":"Create a short or deep link for a partner","tags":["Partners"],"security":[{"bearer":[]}],"x-scope":"partners:write","parameters":[{"name":"partnerId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"destination":{"type":"string","format":"uri"},"subId":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"key":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}]}},"required":["destination"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/programs/{programId}/embed-tokens":{"post":{"summary":"Mint a 1-hour token for the embeddable partner dashboard. Creates (and approves) the partner if needed so customers can refer from inside your app.","tags":["Partners"],"security":[{"bearer":[]}],"x-scope":"partners:write","parameters":[{"name":"programId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"name":{"type":"string","minLength":1,"maxLength":120}},"required":["email","name"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/programs/{programId}/referrals":{"get":{"summary":"List referred signups and customers","tags":["Tracking"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"programId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"before","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["lead","trialing","active","canceled","refunded"]}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/clicks":{"post":{"summary":"Record a click server-side (e.g. from your own redirect)","tags":["Tracking"],"security":[{"bearer":[]}],"x-scope":"tracking:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"programId":{"type":"string"},"code":{"type":"string","maxLength":64},"url":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"visitorId":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"ip":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"userAgent":{"anyOf":[{"type":"string","maxLength":400},{"type":"null"}]}},"required":["programId","code"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/leads":{"post":{"summary":"Record a signup (lead) before payment","tags":["Tracking"],"security":[{"bearer":[]}],"x-scope":"tracking:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"programId":{"type":"string"},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"name":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"clickId":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"visitorId":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"partnerCode":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"customerId":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["programId","email"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/conversions":{"post":{"summary":"Record a payment from a billing system without a built-in integration. Idempotent on paymentId.","tags":["Tracking"],"security":[{"bearer":[]}],"x-scope":"tracking:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"programId":{"type":"string"},"paymentId":{"type":"string","maxLength":120,"description":"Your unique id for this payment (idempotency key)"},"customerId":{"type":"string","maxLength":120},"amount":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647,"description":"Amount paid in minor units excluding tax"},"currency":{"type":"string","minLength":3,"maxLength":3},"interval":{"anyOf":[{"type":"string","enum":["month","year"]},{"type":"null"}]},"email":{"anyOf":[{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"clickId":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"partnerCode":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"promoCode":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"paidAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"required":["programId","paymentId","customerId","amount","currency"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/refunds":{"post":{"summary":"Report a refund for a payment sent to /conversions","tags":["Tracking"],"security":[{"bearer":[]}],"x-scope":"tracking:write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"programId":{"type":"string"},"paymentId":{"type":"string"},"refundId":{"type":"string"},"refundedTotal":{"type":"integer","minimum":0,"maximum":2147483647,"description":"Total refunded so far in minor units"},"chargedTotal":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647}},"required":["programId","paymentId","refundId","refundedTotal","chargedTotal"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/programs/{programId}/commissions":{"get":{"summary":"List commissions (the ledger)","tags":["Money"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"programId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"before","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","approved","held","paid","reversed"]}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["sale","lead","bounty","bonus","adjustment","override"]}},{"name":"partnerId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}},"post":{"summary":"Add a manual commission or bonus (approved immediately). Idempotent with idempotencyKey.","tags":["Money"],"security":[{"bearer":[]}],"x-scope":"commissions:write","parameters":[{"name":"programId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"partnerId":{"type":"string"},"amount":{"type":"integer","minimum":-2147483647,"maximum":2147483647},"description":{"type":"string","minLength":1,"maxLength":200},"idempotencyKey":{"type":"string","maxLength":120}},"required":["partnerId","amount","description"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/programs/{programId}/payouts":{"get":{"summary":"List payouts","tags":["Money"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"programId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":100}},{"name":"before","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["awaiting_approval","processing","paid","failed","canceled"]}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}},"post":{"summary":"Prepare payouts for partners over the minimum. They wait for a person to approve them in the dashboard; no money moves.","tags":["Money"],"security":[{"bearer":[]}],"x-scope":"payouts:request","parameters":[{"name":"programId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"partnerIds":{"maxItems":500,"type":"array","items":{"type":"string"}}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/programs/{programId}/campaigns":{"get":{"summary":"List campaigns","tags":["Growth"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"programId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}},"post":{"summary":"Create a campaign from one sentence (e.g. \"double commissions for annual plans this month\")","tags":["Growth"],"security":[{"bearer":[]}],"x-scope":"partners:write","parameters":[{"name":"programId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"prompt":{"type":"string","minLength":3,"maxLength":300},"launch":{"default":false,"type":"boolean"}},"required":["prompt","launch"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/programs/{programId}/autopilot":{"get":{"summary":"Autopilot suggestions and recent actions","tags":["Growth"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"programId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/programs/{programId}/autopilot/{actionId}/apply":{"post":{"summary":"Apply an Autopilot suggestion (payout suggestions only prepare a batch)","tags":["Growth"],"security":[{"bearer":[]}],"x-scope":"partners:write","parameters":[{"name":"programId","in":"path","required":true,"schema":{"type":"string"}},{"name":"actionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}},"/programs/{programId}/ask":{"post":{"summary":"Ask a plain-language question about the program","tags":["Growth"],"security":[{"bearer":[]}],"x-scope":"read","parameters":[{"name":"programId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"question":{"type":"string","minLength":2,"maxLength":500}},"required":["question"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Invalid request (validation errors list the fields in issues)"},"401":{"description":"Missing or invalid API key"},"403":{"description":"Key lacks the required scope"},"404":{"description":"Not found"},"429":{"description":"Rate limited"}}}}}}