Folium Publisher API (1.14)

Returns the products you can promote, with the commission rates Folium has set for your account. Covers Amazon (seller and vendor catalogs) and Walmart, across every marketplace you are enabled for.

Commission fields at a glance

Each program has its own field:

Field	Program	What it tells you
cc_total_commission_percentage	Amazon Creator Connections	Total rate you earn while the product is in an active campaign. null when no campaign is active.
cc_incremental_commission_percentage	Amazon Creator Connections	The part of that total Folium adds on top of Amazon's campaign rate.
attribution_commission_percentage	Amazon Attribution	Rate for traffic you send through tagged attribution links.
commission_percentage	Amazon or Walmart	The rate Folium has set for your account. For Walmart items this is the Walmart rate.

All rates are percentages: 15.0 means 15%.

Example

A product is in a Creator Connections campaign that pays 10%, and Folium pays you 15% in total:

"commission_percentage": 15.0,
"cc_total_commission_percentage": 15.0,
"cc_incremental_commission_percentage": 5.0

You earn 15%: Amazon's 10% plus Folium's 5%. The incremental value is part of the total, so do not add them together.

When the campaign ends, both Creator Connections fields become null, while commission_percentage still shows 15.0.

Creator Connections campaigns (select publishers)

Available to select publishers. Contact contact@foliumagency.com to request access.

For enabled accounts:

• Every item includes cc_campaigns, the list of active Amazon Creator Connections campaigns that include the product, with each campaign's ID, name, commission rate, and start and end dates.
• commission_type=cc also returns US Amazon products on your account that are in an active campaign, even when Folium's rate for them is 0.
• On any US product where commission_percentage is 0.0 but the product is in an active campaign, cc_total_commission_percentage shows the highest active campaign rate and cc_incremental_commission_percentage is 0.0, because Folium adds nothing on top.

A campaign is active when Amazon reports it as live and today falls between its start and end dates. Dates are US Pacific time.

To see a full response, choose Select publishers: Creator Connections campaigns in the Example menu under Response samples.

Pages and ordering

Each page returns up to 500 items, sorted by product ID and then country, so the order is the same on every request. With platform=all, Amazon items come first, then Walmart items. Keep requesting next_page until has_more is false. When the last page is exactly full, has_more is true and the following page is empty.

Countries

Catalog data is available for US, CA, MX, GB, DE, FR, IT, ES and NL. Send UK or GB for the United Kingdom; results always use GB.

Retrieve list of all brands that Folium manages

Features

• Returns all brands authorized for your publisher account
• Includes brand codes for filtering other endpoints
• Shows marketplaces (countries) where each brand sells products (across Amazon and Walmart catalogs)
• Indicates Amazon Attribution connection status for each brand

Submit performance data including sales, shipments, and revenue metrics.

Features

• Batch Processing: Submit up to 1,000 records per request
• Partial Success: Valid records are processed even if some fail
• Validation: Comprehensive validation with detailed error messages
• Duplicate Handling: Smart deduplication based on ASIN and date

Validation Rules

• ASIN must be exactly 10 characters
• Date must be in YYYY-MM-DD format (not future dates)
• Quantity can be negative (for returns)
• Revenue sign must match quantity sign
• Price is optional (calculated as abs(revenue/quantity) if not provided)

Important: Commissions are ALWAYS calculated by Folium from our commission database. You only need to send ASIN, date, quantity, and revenue. Price is optional and used only for analytics.

Response Behavior

• 200 OK: At least one record was successfully processed
• 400 Bad Request: All records failed validation
• 422 Unprocessable: Records valid but no products recognized

Performance Tips

• Batch records to minimize API calls
• Submit data daily for best accuracy
• Include returns as negative quantities

Submit data about where Folium ASINs are placed on your site(s) with optional performance metrics.

Features

• Flexible Metrics: Submit with or without performance data
• Batch Processing: Up to 500 placements per request
• Smart Updates: Automatic upsert based on URL, ASIN, and date
• Partial Success: Valid records processed even if some fail

Validation Rules

• URL must be valid HTTPS URL
• ASIN must be exactly 10 characters
• Date must be valid (not future)
• Metrics (if provided) must be non-negative

Update Behavior

If a placement already exists (same publisher_id, asin, url, date, country_code):

• All metrics are updated with new values
• Updated timestamp is refreshed

Retrieve upcoming and running Amazon deals for products in your authorized brands.

Only deals are returned. Coupons, price discounts and basket-building promotions are not deals and are never included.

Features

• Live schedules: every deal Amazon currently has booked for your brands, including upcoming sales events
• Rich Filtering: filter by brand name, status, dates, pricing, and more
• Advanced Operators: comparison operators for flexible filtering
• Pagination: handle large result sets efficiently
• Multi-country: deals across all supported marketplaces

Deal Types

• deal: a standard Amazon deal (the deal format itself is not broken out)
• Some deals carry a more specific lowercase label, for example best_deal

Advanced Filtering System

Every response field can be filtered by name. Use the pattern field__operator=value to apply filters.

Filter Operators

Operator	Description	Example	Use Case
(none)	Exact match	?status=running	Find exact matches
__lt	Less than	?deal_price__lt=50	Deals under $50
__lte	Less than or equal	?deal_price__lte=100	Deals $100 or less
__gt	Greater than	?discount_percentage__gt=30	Discounts over 30%
__gte	Greater than or equal	?discount_percentage__gte=25	Discounts 25% or more
__in	In list	?deal_type__in=deal,best_deal	Multiple values
__contains	Contains text	?deal_name__contains=Serum	Text search (case-insensitive)

Filterable Fields

Text Fields:

• asin, deal_type, deal_name, brand, status, event_name, currency_code, product_category
• Operators: exact match, __in, __contains
• country_code: exact match and __in only

Numeric Fields:

• regular_price, deal_price, discount_percentage, product_rating, product_review_count
• Operators: exact match, __lt, __lte, __gt, __gte, __in

Date Fields:

• start_date, end_date
• Operators: exact match (by date), __lt, __lte, __gt, __gte
• Format: YYYY-MM-DD, compared against the deal's date in the marketplace's local time (a US deal ending 23:59 Pacific on Nov 30 matches end_date__lte=2026-11-30)

Legacy names campaign_name, campaign_status, seller_price and event_tags are accepted as aliases of deal_name, status, regular_price and event_name.

Filter Examples

Deals running right now:

GET /deals?status=running

Find deals under $50:

GET /deals?deal_price__lt=50

Find deals with 30% or more discount:

GET /deals?discount_percentage__gte=30

Find deals starting in November 2026:

GET /deals?start_date__gte=2026-11-01&start_date__lte=2026-11-30

Find Black Friday deals:

GET /deals?event_name__contains=Black Friday

Find one brand's deals:

GET /deals?brand__contains=Acme

Complex filter - upcoming US deals under $80 with 20%+ discount:

GET /deals?country_code=US&status=upcoming&deal_price__lte=80&discount_percentage__gte=20

Filter Behavior

• Multiple filters are combined with AND logic
• Invalid filter values are silently ignored (query continues with remaining valid filters)
• Empty or null filter values are ignored
• Text searches with __contains are case-insensitive
• Brand authorization is always enforced - you only see deals for brands you have access to

Response Format

• Sort order: latest-starting deals first
• Date Format: start_date and end_date are ISO 8601 timestamps in the marketplace's local time, with the UTC offset (2026-11-19T00:00:00-08:00 is midnight Pacific)
• Discount Percentage: a whole-number percentage (15 means 15%, not 0.15)
• Prices: regular_price and deal_price are in currency_code

Performance

• Maximum 500 items per page

Generate an Amazon Attribution link for one ASIN. Sales that come through the link are tracked by Amazon Attribution and paid at your attribution commission rate for that ASIN.

Before you call this endpoint

1. Call GET /catalog?commission_type=attribution. Add country_code for a marketplace other than US.
2. Read the asin and the attribution_commission_percentage from each row. This is the rate you earn on the ASIN.
3. Generate links only for these ASINs.

Warning. This endpoint accepts only ASINs that have an attribution commission rate on your account for the requested country. These are exactly the products that GET /catalog?commission_type=attribution lists. Any other ASIN returns 403. An ASIN that is not in the Folium catalog for that country returns 404.

Campaign name

Folium sets the campaign name. It is FOLIUM_{PUBLISHER}_{BRAND} in upper case, for example FOLIUM_BUTTON_BAOR. Folium uses this name to pay the sales from the link to your account. Do not change the campaign name in the link.

adgroupID and creativeID are optional. Use them to tell your own placements apart in the attribution reports. Folium generates random values when you omit them.

Country Code & Regional Endpoints

The country_code parameter determines which Amazon regional API endpoint is used:

• NA (North America): US, CA, MX, BR
• EU (Europe): GB, DE, FR, IT, ES, NL, SE, PL, BE, TR, AE, SA, EG, IN, ZA
• FE (Far East): JP, AU, SG

If country_code is not provided, it defaults to US. The brand must have an advertising profile for that country, or the request returns 400.

Response

Returns the attribution link, the campaign name, the ad group and creative identifiers, the brand code and the country code used.

Returns Amazon Attribution campaign performance data for the last 30 days (rolling window from today).

Use this endpoint to answer: "How is my traffic converting?" — track the full funnel from clicks through to purchases and revenue, grouped by creative or ad group.

This endpoint does NOT include: per-product breakdowns, product names, commission rates, or commission earned. For that, use /reports/products.

Replaces: The previous /attribution-reports endpoint has been removed. This endpoint returns the same underlying data with cleaner field names and the addition of the group_by parameter.

Data Source

Amazon Attribution. Data is reported with a 14-day attribution window — a purchase is attributed to a click if it occurs within 14 days. This is standard Amazon Attribution behavior.

Time Range

Always returns the last 30 days from today. This is not configurable. For example, if today is January 31, you will receive data from January 1–31.

Grouping Levels

The group_by parameter controls the granularity. Each row in the response represents one date + one entity at the chosen level:

• creative (default): One row per creative per day. The campaign_id, adgroup_id, and creative_id fields are all populated.
• adgroup: One row per ad group per day. The campaign_id and adgroup_id fields are populated. The creative_id field is still present but represents the ad group's identifier.

Fields Returned

Field	Description
clicks	Number of click-throughs to Amazon
detail_page_views	Product detail page views within 14-day window
add_to_cart	Add-to-cart events within 14-day window
purchases	Purchases within 14-day window
units_sold	Total units sold within 14-day window
revenue	Total attributed sales in local currency (e.g., GBP for UK) — this is the full sale amount, not commission
revenue_usd	Same revenue converted to USD (null if exchange rate unavailable)
brb_bonus_amount	Amazon Brand Referral Bonus in local currency
brb_bonus_amount_usd	BRB converted to USD (null if exchange rate unavailable)
exchange_rate_used	The exchange rate applied for USD conversion (1.0 for USD data, null if unavailable)

Returns per-product attribution performance data for the last 30 days (rolling window from today).

Use this endpoint to answer: "Which products are selling and how much commission am I earning?" — see revenue, commission rate, commission earned, and new-to-brand metrics broken down by ASIN.

This endpoint does NOT include: click-through counts or BRB (Brand Referral Bonus) amounts. For traffic funnel data, use /reports/campaigns.

Replaces: The previous /attribution-reports endpoint has been removed. This endpoint provides product-level data that was not available in the old endpoint.

Data Source

Amazon Attribution (enriched with commission data from Folium). Data is reported with a 14-day attribution window — a purchase is attributed to a click if it occurs within 14 days.

Time Range

Always returns the last 30 days from today. This is not configurable.

How This Differs from /reports/campaigns

	/reports/campaigns	/reports/products
Granularity	Per creative or ad group	Per ASIN (product)
Includes clicks	Yes	No
Includes BRB bonus	Yes	No
Includes product name	No	Yes
Includes commission rate	No	Yes
Includes commission earned	No	Yes
Includes new-to-brand data	No	Yes
Filterable by ASIN	No	Yes
Filterable by group_by	Yes	No

Fields Returned

Field	Description
asin	Amazon Standard Identification Number (10 characters)
product_name	Full product title from Amazon
brand_name	Brand name of the product
campaign_id	The campaign that generated this attribution data
detail_page_views	Product detail page views within 14-day window
add_to_cart	Add-to-cart events within 14-day window
purchases	Purchases within 14-day window
units_sold	Total units sold within 14-day window
revenue	Total attributed sales in local currency — this is the full sale amount, not commission
revenue_usd	Same revenue converted to USD (null if exchange rate unavailable)
commission_rate	Your commission rate as a decimal (e.g., 0.2 = 20%). Null if no commission rate is set for this product.
commission_earned	Commission amount earned in local currency (calculated as revenue × commission_rate). Null if no commission rate is set.
commission_earned_usd	Commission earned converted to USD (null if exchange rate or commission rate unavailable)
new_to_brand_purchases	Purchases from customers who had not bought from this brand in the last 12 months. Null if not tracked.
new_to_brand_revenue	Revenue from new-to-brand customers in local currency. Null if not tracked.
exchange_rate_used	The exchange rate applied for USD conversion (1.0 for USD data, null if unavailable)