Skip to main content
GET
List affiliates

📌 Endpoint

GET /stores/{storeId}/affiliates Searches and filters the store’s affiliates. With statistics=true, the response includes the statistics (net revenue — already net of gateway fees, sales and clicks calculated on the fly) and the period metrics (from/to).

⚙️ How the commission is resolved

At sale time, the percentage is resolved per item:
  1. Among the affiliate’s commissionRules, the ones that match the item are considered:
    • PRODUCT → the item is the product (targetId);
    • CATEGORY → the item belongs to the category (targetId);
    • COUPON → the coupon applied to the payment is (targetId);
    • DEFAULT → always matches any item.
  2. The rule with the lowest position among the matches wins.
  3. If no other rule matches, the DEFAULT (highest position) is the affiliate’s default percentage.
targetId validation happens at POST/PUT: for PRODUCT, CATEGORY and COUPON it must exist in the store. Rules whose target was removed later are ignored during resolution, without affecting the sale.

🔐 Authentication

  • Private route.
  • Requires the Authorization header with your API key and an active plan.

🔎 Query params


🔄 Cursor pagination

For large lists (more than ~100 items), prefer cursor pagination instead of page:
  1. Make the first call without cursor.
  2. If hasMore is true, the response includes the nextCursor field.
  3. Send that nextCursor in the cursor parameter of the next request to fetch the next page.
In cursor mode, pagination is returned only with nextCursor, hasMore and limit:
  • cursor and page cannot be used together (400 INVALID_PAGINATION).
  • nextCursor: null with hasMore: false indicate the end of the list (the API responds 200 with an empty array).

✅ Request example — list with filters


✅ Request example — full information about an affiliate


📦 Success response (200)

The first call (without cursor) already returns nextCursor and hasMore in the pagination, allowing cursor pagination to start without extra calls.

⚠️ Possible errors

  • 400 INVALID_DATA → invalid parameters (id, name, invalid email or longer than 120 characters, code, status, from, to, or storeId)
  • 400 INVALID_PAGINATION_LIMIT → limit outside the allowed range (1 to 100)
  • 400 INVALID_PAGINATION_PAGE → invalid page
  • 400 INVALID_PAGINATION_CURSOR → invalid or malformed cursor
  • 400 INVALID_PAGINATION → page and cursor used together
  • 401 API_KEY_NOT_PROVIDED → Authorization header not provided
  • 401 INVALID_API_KEY → invalid API key
  • 401 UNAUTHENTICATED → unauthenticated user
  • 403 USER_DISABLED → user disabled
  • 403 NO_ACTIVE_SUBSCRIPTION → no active plan
  • 404 STORE_NOT_FOUND → store not found
  • 404 AFFILIATE_NOT_FOUND → informed id not found (applies only in offset mode, without cursor)
  • 429 RATE_LIMIT_EXCEEDED → per-minute rate limit exceeded
  • 500 INTERNAL_SERVER_ERROR → internal server error
  • 503 SERVICE_UNAVAILABLE → service unavailable

Authorizations

Authorization
string
header
default:YOUR_API_KEY_HERE
required

Path Parameters

storeId
string
required
Required string length: 1 - 50

Query Parameters

id
string
Maximum string length: 50
name
string
Maximum string length: 56
email
string<email>
Maximum string length: 120
code
string
Maximum string length: 50
status
enum<string>
Available options:
ativo,
inativo
from
string

Start date filter (RFC3339 or YYYY-MM-DD).

to
string

End date filter (RFC3339 or YYYY-MM-DD).

page
integer
default:1
Required range: x >= 1
limit
integer
default:20
Required range: 1 <= x <= 100
cursor
string

Opaque cursor from previous page (do not combine with page).

statistics
boolean

Response

List affiliates.

code
string
required
Example:

"AFFILIATES_FETCHED"

affiliates
object[]
required
pagination
object
required