Folium Seller API
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.

Two report endpoints, same base URL and the same response shape:

  • Creator Connections — POST https://zuesvpmmz1.execute-api.us-east-1.amazonaws.com/Prod/seller/creator-connections
  • Attribution — POST https://zuesvpmmz1.execute-api.us-east-1.amazonaws.com/Prod/seller/attribution

Both share one response shape: totals (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. Your API 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.

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

POST /seller/creator-connections returns your Creator Connections (CC) performance — sales, orders, clicks, and spend — as totals, a totals_by_brand breakdown, and a records list at the grain you choose with group_by (by ASIN+date, by date, or by campaign).

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 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 section intro 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": [
    ]
}

Attribution

POST /seller/attribution returns your Amazon attribution performance — the sales, orders, and engagement attributed to your products. Same envelope as Creator Connections — totals, totals_by_brand, and grouped records — with group_by = asin_date (default), date, or asin.

Metrics (all 14-day-attributed, gross, USD)

Field Meaning
sales Attributed sales revenue
orders Attributed purchases (orders)
units Attributed units sold
detail_page_views Product detail-page views
add_to_cart Add-to-cart events
new_to_brand_orders Orders from customers new to your brand
new_to_brand_sales Sales from new-to-brand customers
commission Commission on these attributed sales

These are 14-day attribution figures (Amazon's model): each day's values are the sales attributed within 14 days of the activity on that day. All metrics sum cleanly at every grain (no de-duplication caveat like Creator Connections clicks).

Notes

  • US marketplace only (v1); figures are gross attributed (not net of returns).
  • If your brands have no attribution in a period, you get a 200 with zero totals, empty records, and a message.

Amazon attribution performance

Returns your Amazon attribution performance for a date range — the sales, orders, and engagement attributed to your products. Same envelope as /seller/creator-connections — totals (always present) + totals_by_brand + grouped records.

See the section intro above for the metric definitions and the 14-day attribution model. All metrics sum cleanly at every grain.

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 asin.
asins No Narrow to specific ASINs. Max 1000.
page, page_size No Pagination for records (default 1 / 500, max 1000). totals always cover the full range.
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" "asin"
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
{
  • "status": "success",
  • "group_by": "asin_date",
  • "data_as_of": "2026-07-19",
  • "last_updated": "2026-07-20T06:00:00Z",
  • "filters_applied": {
    },
  • "totals": {
    },
  • "totals_by_brand": [
    ],
  • "pagination": {
    },
  • "records": [
    ]
}