API Overview
The Convertly API lets you programmatically access your brand’s data — creators, campaigns, discounts, orders, and more. Use it to build custom integrations, dashboards, or automation workflows.
Base URL
All API requests use the following base URL:
https://api.convertlyhq.com/v1
/v1 to indicate the API version.
Authentication
All requests require a valid JWT Bearer token in the Authorization header:
curl https://api.convertlyhq.com/v1/affiliates \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
Rate Limits
To ensure platform stability, the API enforces rate limits:
| Plan | Limit |
|---|
| Growth | 100 requests/minute |
| Scale | 500 requests/minute |
The Starter plan does not include API access. Upgrade to Growth or Scale to use the API.
429 Too Many Requests response with a Retry-After header indicating how many seconds to wait.
All responses return JSON with a consistent structure.
Success Response
{
"data": {
"id": "abc123",
"name": "Sarah Johnson",
"email": "sarah@example.com"
}
}
List Response
{
"data": [
{ "id": "abc123", "name": "Sarah Johnson" },
{ "id": "def456", "name": "Mike Chen" }
],
"meta": {
"total": 42,
"cursor": "eyJpZCI6ImRlZjQ1NiJ9"
}
}
Error Response
{
"statusCode": 400,
"message": "Validation failed",
"error": "Bad Request"
}
| Parameter | Description |
|---|
limit | Number of items to return (default: 20, max: 100) |
cursor | Cursor from the previous response’s meta.cursor |
# First page
GET /v1/affiliates?limit=20
# Next page (use cursor from previous response)
GET /v1/affiliates?limit=20&cursor=eyJpZCI6ImRlZjQ1NiJ9
meta.cursor is null, you have reached the last page.
Common HTTP Status Codes
| Code | Meaning |
|---|
200 | Success |
201 | Created |
400 | Bad request (validation error) |
401 | Unauthorized (missing or invalid token) |
403 | Forbidden (insufficient permissions) |
404 | Not found |
429 | Rate limit exceeded |
500 | Server error |
