API docs by Redocly

Folium Seller API (1.0)

Download OpenAPI specification:

API for Folium sellers (brands) and brand aggregators to programmatically access their own performance data.

Endpoint: POST https://zuesvpmmz1.execute-api.us-east-1.amazonaws.com/Prod/seller/creator-connections

Authentication: Include your API key in the Authorization header as Bearer YOUR_API_KEY

Support: contact@foliumagency.com

🔒 Access by invitation. Seller and brand-aggregator API keys are provisioned by Folium. If you do not have a key yet, email contact@foliumagency.com to request one. All examples below use fictional brands (Acme, Zenith, Orbit) and figures for illustration.

Creator Connections reporting

POST /seller/creator-connections returns your Creator Connections (CC) performance — sales, orders, clicks, and spend — with:

  • a totals summary (always present),
  • a totals_by_brand breakdown (per brand — a single-brand seller sees one entry),
  • and a records list at the grain you choose with group_by (by ASIN+date, by date, or by campaign).

Your key determines your scope automatically: a seller key returns your brand(s); a brand-aggregator key returns every brand you manage, each row tagged with its brand_name.

Understanding spend

spend is the Creator Connections spend Amazon reports on these sales (the CC commission cost), in USD.

Freshness — data_as_of vs last_updated

These answer two different questions, and the gap between them is normal:

Field Meaning Timezone
data_as_of The most recent day your data covers A calendar date as Amazon reports it — Amazon's US marketplace reports in Pacific Time. No time-of-day.
last_updated When Folium last refreshed your data from Amazon A timestamp in UTC (ends with Z).

So you might see data_as_of: 2026-07-20 but last_updated: 2026-07-22T07:02:35Z — your latest day of activity is the 20th, and we last pulled it on the 22nd. CC data is refreshed Mon/Wed/Fri, so expect a 1–3 day lag. If your numbers differ from a Folium dashboard, compare these fields first — a difference is usually a refresh-timing gap, not a data error.

How clicks are counted (important)

Amazon reports clicks at the creator/ASIN/day level and repeats the same value on each campaign a creator ran. Folium de-duplicates clicks so they aren't over-counted:

  • totals.clicks, totals_by_brand[].clicks, and group_by=asin_date / group_by=date records are the authoritative, de-duplicated numbers — these match Folium's dashboards.
  • group_by=campaign records show clicks per campaign, which OVERLAP (the same creator/day clicks appear under each of that creator's campaigns). Summing campaign clicks will exceed the true total — always use totals.clicks for the real figure.

sales, orders, and spend sum cleanly at every grain.

Methodology

  • US marketplace only (v1).
  • Sales from publishers you have a separate/direct relationship with are excluded, so this API matches Folium's dashboards and billing.
  • Deleted and duplicate (re-uploaded) rows are removed.

Creator Connections

Your Creator Connections performance — totals, a per-brand breakdown, and records grouped by ASIN+date, date, or campaign. Scope is determined server-side by your API key.

Creator Connections performance — totals, per-brand breakdown, and grouped records

Returns your Creator Connections performance for a date range. Every response has totals (overall) and totals_by_brand (per brand); records are grouped at the grain set by group_by (default asin_date).

See the API overview above for how spend (CC commission cost), freshness (data_as_of vs last_updated), and click de-duplication work.

Request fields

Field Required Description
start_date, end_date Yes Inclusive range, YYYY-MM-DD. Max span 366 days.
group_by No Records grain: asin_date (default), date, or campaign.
campaign_ids No Narrowing filter (bare CAMPAIGN1234 or amzn1.campaign.*). Max 200.
asins No Narrowing filter, 10-char ASINs. Max 1000.
page, page_size No Pagination for records. Default page 1, page_size 500 (max 1000). totals always cover the FULL range regardless of paging.

All filters can only ever shrink your results — they never grant access outside your scope.

Pagination: keep fetching while has_more is true. If your total is an exact multiple of page_size, has_more may be true on the last full page and the next page returns empty — stop when a page has no records. Out-of-range page/page_size are clamped, not rejected.

Rate limits: none published (fair use). Contact Folium for high-volume access.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
start_date
required
string <date>
end_date
required
string <date>
group_by
string
Default: "asin_date"
Enum: "asin_date" "date" "campaign"
campaign_ids
Array of strings <= 200 items
asins
Array of strings <= 1000 items [ items^[A-Z0-9]{10}$ ]
page
integer >= 1
Default: 1
page_size
integer [ 1 .. 1000 ]
Default: 500

Responses

Request samples

Content type
application/json
Example
{
  • "start_date": "2026-06-01",
  • "end_date": "2026-06-30"
}

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "group_by": "asin_date",
  • "data_as_of": "2026-07-20",
  • "last_updated": "2026-07-22T07:02:35Z",
  • "filters_applied": {
    },
  • "totals": {
    },
  • "totals_by_brand": [
    ],
  • "pagination": {
    },
  • "records": [
    ]
}