Folium Publisher API (1.6)

Retrieve paginated product catalog with commission information.

Features

• Paginated results (500 items per page by default)
• Filter by brand, country, and platform (Amazon or Walmart)
• Includes commission rates for your publisher account
• Real-time pricing and availability
• Multi-country support with country-specific pricing and commission rates
• Multi-platform support: Amazon (default) and Walmart catalogs

Country Code Notes

• UK → GB Conversion: If you send country_code=UK, it will be automatically converted to GB (ISO 3166-1 alpha-2 standard) as the database stores United Kingdom data with the GB country code.
• Supported Countries: US, CA, GB, DE, FR, IT, ES, JP, AU, MX, IN, BR, NL, SE, PL, TR, AE, SG

Performance

• Average response time: < 200ms
• Cache duration: 5 minutes

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 current and upcoming deals for products in your authorized brands.

Features

• Rich Filtering: Filter by brand, deal type, dates, pricing, and more
• Advanced Operators: Use comparison operators for flexible filtering
• Pagination: Handle large result sets efficiently
• Real-time Data: Updated as deals are created/modified
• Multi-country: Access deals across all supported marketplaces

Deal Types

• LIGHTNING_DEAL: Limited time offers with countdown
• BEST_DEAL: Featured best deals
• DOTD: Deal of the Day
• PRIME_EXCLUSIVE: Exclusive to Prime members
• PRICE_DISCOUNT: Standard price discounts
• PRIME_EXCLUSIVE_DISCOUNT: Prime-only discounts

Advanced Filtering System

The API supports powerful filtering with operators. Use the pattern field__operator=value to apply filters.

Filter Operators

Operator	Description	Example	Use Case
(none)	Exact match	?campaign_status=ACTIVE	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=LIGHTNING_DEAL,BEST_DEAL	Multiple values
__contains	Contains text	?campaign_name__contains=Prime	Text search (case-insensitive)

Filterable Fields

Text Fields:

• asin, deal_type, campaign_id, campaign_name, campaign_status
• marketplace, event_tags, asin_status, sku, currency_code, brand_code
• Operators: exact match, __in, __contains

Numeric Fields:

• seller_price, deal_price, discount_percentage, seller_quantity, deal_quantity, total_asins_in_campaign
• 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

Boolean Fields:

• is_included
• Values: true, false, 1, 0, yes, no

Filter Examples

Find deals under $50:

GET /deals?deal_price__lt=50

Find deals with 30% or more discount:

GET /deals?discount_percentage__gte=30

Find cheap deals with good discounts:

GET /deals?deal_price__lte=100&discount_percentage__gt=20

Find lightning or best deals:

GET /deals?deal_type__in=LIGHTNING_DEAL,BEST_DEAL

Find deals starting in December 2025:

GET /deals?start_date__gte=2025-12-01&start_date__lte=2025-12-31

Find active Prime-related campaigns:

GET /deals?campaign_name__contains=Prime&campaign_status=ACTIVE

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

GET /deals?country_code=US&campaign_status=ACTIVE&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

• Date Format: All dates (start_date, end_date) are returned in ISO 8601 format (YYYY-MM-DDThh:mm:ss)
• Discount Percentage: Returned as a percentage value (e.g., 20.01 means 20.01%, not 0.2001)
• Removed Fields: The following fields are no longer included in the response:
  • created_by_user_id
  • created_by_email
  • seller_id
  • organization_id

Performance

• Results cached for 5 minutes
• Maximum 500 items per page
• Efficient indexing on commonly filtered fields

Generate an Amazon Attribution tag for tracking advertising campaigns.

Features

• Creates unique campaign identifiers
• Generates trackable attribution links
• Supports multi-channel campaigns with country-specific regional endpoints
• Automatic campaign naming
• Multi-country support (US, CA, GB, DE, FR, IT, ES, JP, AU, MX, etc.)

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.

Response

Returns the attribution link, a system-generated campaign name, 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)