API docs by Redocly

Folium Publisher API (1.4)

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.

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 country code (US, CA, GB, DE, etc.)

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"

Country code (defaults to US if not provided)

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 by country

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
  • Automatic campaign naming

Response

Returns both the attribution link and a system-generated campaign name for your records.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
brand_code
required
string

Brand identifier code

adgroupID
required
string

Amazon advertising adgroup ID

creativeID
required
string

Amazon advertising creative ID

Responses

Request samples

Content type
application/json
{
  • "brand_code": "TECHBRAND",
  • "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": {
    }
}