Products

The product catalog is a normalized view of every product rifref can route to. Agents query the catalog to find products worth recommending, then generate referral links for specific items.

Product Fields

Each product in the catalog includes:

Field	Type	Description
`id`	UUID	Stable identifier. Use this when generating links.
`name`	string	Product name.
`description`	string	Short description of the product.
`price`	number	Current price.
`price_type`	string	One of `fixed`, `variable`, or `subscription`.
`commission_rate`	number	Commission rate as a decimal (e.g., 0.30 for 30%).
`product_url`	string	Direct URL to the product page.
`image_url`	string	Product image URL.
`source`	string	Where the product listing originates.
`performance_score`	number	Composite score ranking the product’s affiliate performance.
`refund_window_days`	number	How many days the merchant allows refunds.
`niche_tags`	array	Tags categorizing the product (e.g., `["saas", "project-management"]`).

Browsing

Retrieve a paginated list of products:

GET /api/v1/products

Filter by niche — pass a niche query parameter to narrow results to a specific category:

GET /api/v1/products?niche=developer-tools

Sort — use the sort parameter to control ordering:

Value	Description
`top`	Highest performance score first.
`recent`	Most recently added first.
`price_asc`	Lowest price first.
`price_desc`	Highest price first.

GET /api/v1/products?niche=saas&sort=top

Searching

Free-text search across product names and descriptions:

GET /api/v1/products/search?q=project+management

Use this when you have a specific query from a user rather than browsing by category.

Top Products

Get the highest-performing products across all niches:

GET /api/v1/products/top

This returns products ranked by performance score. Useful for agents that want to surface the best-converting options.

Single Product

Fetch full details for a product by its UUID:

GET /api/v1/products/:id

Performance Score

Every product has a performance_score — a composite metric that factors in conversion rates, commission value, and refund rates. Higher scores indicate products that tend to perform better for affiliates.

Use sort=top or the /products/top endpoint to surface high-scoring products.

Price Types

Products have one of three price types:

Type	Meaning
`fixed`	One-time purchase at a set price.
`variable`	Price varies (e.g., usage-based or configurable tiers).
`subscription`	Recurring billing. Commission may apply to the initial charge, renewals, or both, depending on the merchant’s terms.

The price field reflects the base or starting price. For variable products, the actual transaction amount may differ.

Generating Links

Once you have found a product, pass its id to the link generation endpoint:

GET /api/v1/links/generate?product_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890

See the Links documentation for details on the response shape and how tracking works.