API docs by Redocly

Folium Publisher API (1.5)

Download OpenAPI specification:

Enterprise API for publishers to access product catalogs, submit performance data, and track attribution metrics.

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

Support: contact@foliumagency.com

Catalog

Access product catalog with detailed product information, pricing, and commission rates. Perfect for building product recommendation systems and content creation tools.

Get Product Catalog

Retrieve paginated product catalog with commission information.

Features

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

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
Authorizations:
ApiKeyAuth
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number for pagination (starts at 1)

brand_code
string
Example: brand_code=TECHBRAND

Filter results by brand code (e.g., "TECHBRAND")

country_code
string^[A-Z]{2}$
Example: country_code=US

Filter results by country code. If not provided, returns catalog items from all countries.

Supported Country Codes:

  • US - United States
  • CA - Canada
  • GB - United Kingdom (Note: UK is automatically converted to GB)
  • DE - Germany
  • FR - France
  • IT - Italy
  • ES - Spain
  • JP - Japan
  • AU - Australia
  • MX - Mexico
  • IN - India
  • BR - Brazil
  • NL - Netherlands
  • SE - Sweden
  • PL - Poland
  • TR - Turkey
  • AE - United Arab Emirates
  • SG - Singapore

Note: The country code UK is automatically converted to GB (ISO 3166-1 alpha-2 standard) as the database stores United Kingdom data with the GB country code.

include_history
boolean
Example: include_history=true

Include commission history per ASIN+country. Accepts true, 1, yes, or history (case-insensitive).

commission_type
string
Default: "associates"
Enum: "associates" "attribution" "all"
Example: commission_type=associates

Filter catalog by commission type. Controls which products are returned based on their commission rates.

  • associates (default): Returns products with associates commission rates. Fully backward compatible with existing integrations.
  • attribution: Returns products with attribution commission rates only.
  • all: Returns products with either associates or attribution commission rates.

Note: The attribution_commission_percentage field is always included in the response regardless of this parameter.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "pagination": {
    },
  • "catalog": [
    ]
}

Get Available Brands

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
  • Indicates Amazon Attribution connection status for each brand
Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "brands": [
    ]
}

Performance

Submit performance data including sales, clicks, impressions, and revenue metrics. Enables real-time performance tracking and optimization.

Submit Associates Performance Data

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
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
required
Array of objects (PerformanceRecord) [ 1 .. 1000 ] items

Array of performance records (max 1000 per request)

country_code
required
string^[A-Z]{2}$

Two-letter ISO 3166-1 alpha-2 country code for the marketplace where the sales occurred.

Supported Country Codes:

  • US - United States
  • CA - Canada
  • GB - United Kingdom (Note: UK is automatically converted to GB)
  • DE - Germany
  • FR - France
  • IT - Italy
  • ES - Spain
  • JP - Japan
  • AU - Australia
  • MX - Mexico
  • IN - India
  • BR - Brazil
  • NL - Netherlands
  • SE - Sweden
  • PL - Poland
  • TR - Turkey
  • AE - United Arab Emirates
  • SG - Singapore

Note: The country code UK is automatically converted to GB (ISO 3166-1 alpha-2 standard).

Responses

Request samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "country_code": "US"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "summary": {
    },
  • "results": {
    },
  • "warnings": [
    ],
  • "metadata": {
    }
}

Placements

Submit where Folium ASIN content appears (URLs), along with placement-level performance metrics. This data will help us correlate performance to placements. Essential for content strategy and optimization.

Submit Placement Data

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
Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
required
Array of objects (PlacementRecord) [ 1 .. 500 ] items
country_code
string^[A-Z]{2}$
Default: "US"

Two-letter ISO 3166-1 alpha-2 country code for the marketplace where the placements occurred. Defaults to US if not provided.

Supported Country Codes:

  • US - United States
  • CA - Canada
  • GB - United Kingdom (Note: UK is automatically converted to GB)
  • DE - Germany
  • FR - France
  • IT - Italy
  • ES - Spain
  • JP - Japan
  • AU - Australia
  • MX - Mexico
  • IN - India
  • BR - Brazil
  • NL - Netherlands
  • SE - Sweden
  • PL - Poland
  • TR - Turkey
  • AE - United Arab Emirates
  • SG - Singapore

Note: The country code UK is automatically converted to GB (ISO 3166-1 alpha-2 standard).

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
{
  • "success": true,
  • "summary": {
    },
  • "results": {
    },
  • "metadata": {
    }
}

Deals

Access curated deals, promotions, and special offers across all authorized brands. Stay ahead with exclusive promotional opportunities.

Get Deals Information

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
Authorizations:
ApiKeyAuth
query Parameters
page
integer >= 1
Default: 1

Page number

limit
integer [ 1 .. 500 ]
Default: 100

Items per page (max 500)

country_code
string
Example: country_code=US

Filter results by country code. If not provided, returns deals from all countries.

Supported Country Codes:

  • US - United States
  • CA - Canada
  • GB - United Kingdom (Note: UK is automatically converted to GB)
  • DE - Germany
  • FR - France
  • IT - Italy
  • ES - Spain
  • JP - Japan
  • AU - Australia
  • MX - Mexico
  • IN - India
  • BR - Brazil
  • NL - Netherlands
  • SE - Sweden
  • PL - Poland
  • TR - Turkey
  • AE - United Arab Emirates
  • SG - Singapore

Note: The country code UK is automatically converted to GB (ISO 3166-1 alpha-2 standard).

brand_code
string
Example: brand_code=TECHBRAND

Filter by brand

deal_type
string
Enum: "LIGHTNING_DEAL" "BEST_DEAL" "DOTD" "PRIME_EXCLUSIVE"

Filter by deal type

campaign_status
string
Enum: "SCHEDULED" "ACTIVE" "COMPLETED" "CANCELLED"

Filter by campaign status

start_date_from
string <date>
Example: start_date_from=2025-01-01

Deals starting from this date

start_date_to
string <date>
Example: start_date_to=2025-01-31

Deals starting before this date

end_date_from
string <date>

Deals ending from this date

end_date_to
string <date>

Deals ending before this date

min_deal_price
number <float>

Minimum deal price

max_deal_price
number <float>

Maximum deal price

min_discount_percentage
number <float>
Example: min_discount_percentage=20

Minimum discount percentage (e.g., 20 for 20%). Value should be in percentage format, not decimal (20 means 20%, not 0.20)

event_tags
string
Example: event_tags=Prime Day

Filter by event tags (partial match)

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "pagination": {
    },
  • "filters_applied": {
    },
  • "deals": [
    ]
}

Attribution

Generate attribution tags and access detailed performance reports for campaign tracking. Complete attribution solution for multi-channel campaigns.

Generate Attribution Tag

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.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
asin
required
string^[A-Z0-9]{10}$

Amazon Standard Identification Number for the product

country_code
string^[A-Z]{2}$

Two-letter ISO 3166-1 alpha-2 country code for the marketplace. Defaults to US if not provided. Determines which regional Amazon Advertising API endpoint is used for tag generation.

Supported Country Codes (grouped by Amazon region):

NA (North America): US, CA, MX, BR

EU (Europe): GB, DE, FR, IT, ES, NL, SE, PL, TR, AE, IN

FE (Far East): JP, AU, SG

Note: The country code UK is automatically converted to GB (ISO 3166-1 alpha-2 standard).

adgroupID
string

Optional Amazon advertising adgroup ID

creativeID
string

Optional Amazon advertising creative ID

Responses

Request samples

Content type
application/json
Example
{
  • "asin": "B08N5WRWNW",
  • "adgroupID": "social_campaign_jan",
  • "creativeID": "banner_headphones_v2"
}

Response samples

Content type
application/json
{}

Get Attribution Performance Reports

Retrieve attribution performance data for the last 30 days.

Features

  • Creative-level performance metrics
  • Last 30 days of data
  • Full funnel metrics (impressions → purchases)
  • Revenue and conversion tracking

Metrics Included

  • Impressions & Clicks
  • Click-through Rate (CTR)
  • Detail Page Views
  • Add to Cart events
  • Purchases & Revenue
  • Units Sold
Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}