FreshStore API Specification

Every store has an API that can be used to get data from or update your store. That includes products, settings, analytics, and more.

Please note that using an API requires some technical knowledge.

Fill Categories

Automatically fill categories with products from merchant APIs using AI-powered search. Jobs run in the background.

POST /api/categories/fill

Response 202: Jobs are queued in the background.

{
  "data": {
    "categories_queued": 3,
    "quantity_per_category": 5,
    "api_name": "amazon",
    "locale": "us"
  }
}

Import Links

Import products by pasting Amazon links or ASINs. Products are imported in the background.

POST /api/products/import-links

Response 202: Each link is validated and queued.

{
  "data": {
    "total": 3,
    "importing": 2,
    "duplicates": 1,
    "failed": 0,
    "links": [
      {"link": "https://www.amazon.com/dp/B09V3KXJPB", "asin": "B09V3KXJPB", "locale": "us", "status": "importing"},
      {"link": "B07XJ8C8F5", "asin": "B07XJ8C8F5", "locale": "us", "status": "importing"},
      {"link": "https://www.amazon.com/dp/B08N5WRWNW", "asin": "B08N5WRWNW", "locale": "us", "status": "duplicate", "reason": "Product already exists", "product_id": 42}
    ]
  }
}

Getting Started

1. Create an API Key

Go to Settings > API Keys in the store admin area and click Create API Key. Give it a name, choose the permissions you need, and optionally set an expiry date.

Once created, you'll see the API key once - copy it and store it securely. It cannot be retrieved again.

2. Authenticate Requests

Include your API key in the Authorization   header of every request:

Authorization: Bearer YOUR_API_KEY

3. Permissions

When creating an API key, you can choose:

• Full Access: read and write everything
• Read / Write: broad read or write access across all resources
• Per-resource: granular access like "Products: Read", "Offers: Write", etc.

If a request exceeds the key's permissions, you'll receive a 403 Forbidden   response.

Rate Limiting

All endpoints are rate-limited to 60 requests per minute.

WAF (Web Application Firewall) Approval

Your stores are protected by a WAF and common products/services are whitelisted. If you get a 403 response, check the following:

• User-Agent header: Your requests must include a valid browser-style User-Agent. Generic user-agents such as curl, python-requests, axios, or empty User-Agent strings will be blocked. Use a standard browser User-Agent string, for example: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
• IP whitelisting: If you are still blocked after setting a valid User-Agent, contact support with your server IP to request a whitelist.

Both conditions must be met: a valid User-Agent and an approved IP (if your IP range is flagged).

Base URL

All of the endpoints listed below are accessible from your store url.

API Base URL: https://{your-store-domain}/  

Response Format

Success

All responses wrap data in a data   key:

{
  "data": { ... }
}

List endpoints return paginated results:

{
  "data": [ ... ],
  "links": {
    "first": "...?page=1",
    "last": "...?page=10",
    "prev": null,
    "next": "...?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 10,
    "per_page": 15,
    "to": 15,
    "total": 150
  }
}

Errors

Pagination

All list endpoints accept these query parameters:

Store

Get Status (Public)

GET /api/store/status

No authentication required. Returns whether the store is online.

{
  "data": {
    "up": true
  }
}

Get Store Info

GET /api/store/info

{
  "data": {
    "name": "My Store",
    "url": "https://store.example.com",
    "niche": "tech",
    "live": true,
    "default_country": "US",
    "enabled_countries": ["US", "GB", "DE"],
    "version": "3.2.0",
    "cart_enabled": false,
    "advanced_mode": true
  }
}

Get Store Stats

GET /api/store/stats

{
  "data": {
    "brands": 12,
    "articles": 45,
    "products": 150,
    "categories": 23,
    "offers": 320,
    "articles_generated": 30
  }
}

Also available at GET /api/data/stats   .

Get Store Warnings

GET /api/store/warnings

{
  "data": [
    {
      "message": "To get paid for your Amazon sales you need to add an Amazon Affiliate Tag",
      "action": "Find Out More",
      "url": "/admin/store-health"
    }
  ]
}

Get Store Locales

GET /api/store/locales

Returns the enabled country/locale configurations.

{
  "data": {
    "us": { "name": "United States", "iso_3166_2": "US", "..." : "..." },
    "gb": { "name": "United Kingdom", "iso_3166_2": "GB", "..." : "..." }
  }
}

Users

List Users

GET /api/users

Response: Paginated list.

{
  "data": [
    {
      "id": 1,
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane@example.com",
      "roles": ["admin"]
    }
  ]
}

Create User

POST /api/users

If a user with the given email already exists (including deleted users), the existing user is returned.

Get Login Link

GET /api/users/login-link?email=jane@example.com

Generates a magic login link for the given user.

{
  "data": {
    "loginLink": "https://store.example.com/magiclink/..."
  }
}

Get User

GET /api/users/{id}

Update User

PATCH /api/users/{id}

Settings

Get All Settings

GET /api/settings

Returns all settings as flat key-value pairs using {group}_{setting}   keys.

{
  "data": {
    "store_name": "My Fresh Store",
    "store_niche": "tech",
    "product_show_reviews": true,
    "offers_amazon_enabled": true
  }
}

Update All Settings

PATCH /api/settings

Send one or more settings using {group}_{setting}   keys.

{
  "store_name": "My Updated Store",
  "product_show_reviews": false
}

Response:

{
  "message": "Settings saved successfully."
}

Get Settings by Group

GET /api/settings/{group}

Available groups: store   , offers   , product   , traffic   , article   , social   , template   , xml-sitemap  

Returns settings for that group only, with keys without the group prefix.

{
  "data": {
    "name": "My Fresh Store",
    "niche": "tech",
    "live": true,
    "default_country": "US"
  }
}

Update Settings by Group

PATCH /api/settings/{group}

Available groups: store   , offers   , product   , traffic   , article   , social   , template   , xml-sitemap  

Send keys without the group prefix.

{
  "name": "My Updated Store",
  "niche": "tech"
}

Products

Product Fields

List Products

GET /api/products

Create Product

POST /api/products

Response 201  

Get Product

GET /api/products/{id}

Use ?include=brand,offers,categories   to load related data.

{
  "data": {
    "id": 1,
    "title": "Example Product",
    "brand": { "id": 5, "title": "Acme" },
    "offers": [{ "id": 10, "title": "..." }],
    "categories": [{ "id": 3, "title": "..." }]
  }
}

Update Product

PATCH /api/products/{id}

Same fields as Create. All optional. Only provided fields are updated.

Delete Product

DELETE /api/products/{id}

Soft-deletes the product. Response 204   (no content).

Get Product Offers

GET /api/products/{id}/offers

Paginated list of offers linked to this product.

Get Product Categories

GET /api/products/{id}/categories

{
  "data": [{ "id": 1, "title": "Electronics" }]
}

Sync Product Categories

Replace all category associations for a product.

POST /api/products/{id}/categories

{
  "category_ids": [1, 2, 3]
}

Get Product Analytics

GET /api/products/{id}/analytics

{
  "data": {
    "analytics_visits": 1250,
    "total_clicks": 89,
    "affiliate_clicks": 45
  }
}

Offers

Offer Fields

Get Enabled Merchants

GET /api/offers/merchants

{
  "data": {
    "amazon": "Amazon",
    "ebay": "eBay",
    "etsy": "Etsy"
  }
}

List Offers

GET /api/offers

Create Offer

POST /api/offers

Response 201  

Get Offer

GET /api/offers/{id}

Update Offer

PATCH /api/offers/{id}

Same fields as Create. All optional.

Delete Offer

DELETE /api/offers/{id}

Response 204   (no content).

Sync Offer Products

Replace all product associations for an offer.

POST /api/offers/{id}/products

{
  "product_ids": [1, 2, 3]
}

Categories

Category Fields

Get Category Tree

GET /api/categories/tree

Returns all categories as a nested tree structure.

{
  "data": [
    {
      "id": 1,
      "title": "Electronics",
      "children": [
        {
          "id": 5,
          "title": "Phones",
          "children": []
        }
      ]
    }
  ]
}

List Categories

GET /api/categories

Create Category

POST /api/categories

Response 201  

Get Category

GET /api/categories/{id}

Update Category

PATCH /api/categories/{id}

Same fields as Create. All optional.

Delete Category

DELETE /api/categories/{id}

Response 204   (no content).

Get Category Products

GET /api/categories/{id}/products

Paginated list of products in this category.

Brands

Brand Fields

List Brands

GET /api/brands

Create Brand

POST /api/brands

Response 201  

Get Brand

GET /api/brands/{id}

Update Brand

PATCH /api/brands/{id}

Same fields as Create. All optional.

Delete Brand

DELETE /api/brands/{id}

Response 204   (no content).

Get Brand Products

GET /api/brands/{id}/products

Paginated list of products for this brand.

Articles

Article Fields

List Articles

GET /api/articles

Create Article

POST /api/articles

Response 201  

When generate_ai_content is true, the article title is used as the AI generation topic. Content, metadata, and optionally images are generated in the background. The article is returned immediately with a 201 status and the generated content will populate once the background job completes.

Get Article

GET /api/articles/{id}

Includes article_categories   .

Update Article

PATCH /api/articles/{id}

Same fields as Create. All optional.

Delete Article

DELETE /api/articles/{id}

Response 204   (no content).

Article Categories

Article Category Fields

List Article Categories

GET /api/article-categories

Create Article Category

POST /api/article-categories

Response 201  

Get Article Category

GET /api/article-categories/{id}

Update Article Category

PATCH /api/article-categories/{id}

Same fields as Create. All optional.

Delete Article Category

DELETE /api/article-categories/{id}

Response 204   (no content).

Pages

Page Fields

List Pages

GET /api/pages

Create Page

POST /api/pages

Response 201  

Get Page

GET /api/pages/{id}

Update Page

PATCH /api/pages/{id}

Same fields as Create. All optional.

Delete Page

DELETE /api/pages/{id}

Response 204   (no content).

Analytics

Get Visits Summary

GET /api/analytics/visits/summary

{
  "data": {
    "2026-03-06": { "nb_uniq_visitors": 45, "nb_visits": 52, "nb_actions": 120 },
    "2026-03-05": { "..." }
  }
}

List Visits

GET /api/analytics/visits

Returns paginated visit records with fields: id   , ip_address   , country_code   , region   , city   , visits   , actions   , events   , visit_duration_seconds   , referrer_type_name   , device_type   , browser   , first_action_at   , last_action_at   .

List Visitors

GET /api/analytics/visitors

Returns paginated visitor records with fields: id   , matomo_visitor_id   , first_seen   , last_seen   , visits_count   , clicks_count   .

Get Visitor

GET /api/analytics/visitors/{id}

Get Pages Analytics

GET /api/analytics/pages

{
  "data": [
    {
      "id": 1,
      "label": "/products/example",
      "visitors": 120,
      "hits": 145,
      "average_time_on_page": 42,
      "bounce_rate": "35%",
      "exit_rate": "20%"
    }
  ]
}

Get Countries Analytics

GET /api/analytics/countries

{
  "data": [
    {
      "id": 1,
      "locale": "us",
      "country_name": "United States",
      "visitors": 500,
      "visits": 620,
      "actions": 1800,
      "visit_duration_seconds": 45000
    }
  ]
}

Get Devices Analytics

GET /api/analytics/devices

{
  "data": [
    {
      "id": 1,
      "device": "Desktop",
      "visitors": 300,
      "visits": 400,
      "actions": 1200,
      "visit_duration_seconds": 30000
    }
  ]
}

Get Sources Analytics

GET /api/analytics/sources

{
  "data": [
    {
      "id": 1,
      "source": "Google",
      "visitors": 200,
      "visits": 250,
      "actions": 600,
      "visit_duration_seconds": 18000
    }
  ]
}

Affiliate Clicks Summary

Revenue and click counts for affiliate link clicks, with a breakdown by merchant and per-period time series.

GET /api/analytics/clicks/summary

{
  "data": {
    "total_clicks": 1500,
    "affiliate_clicks": 890,
    "affiliate_revenue": 3245.50,
    "by_merchant": {
      "amazon": { "clicks": 450, "revenue": 1820.00 },
      "ebay": { "clicks": 200, "revenue": 875.50 },
      "etsy": { "clicks": 240, "revenue": 550.00 }
    },
    "periods": {
      "2026-03-07": { "clicks": 12, "affiliate_clicks": 5, "revenue": 125.00 },
      "2026-03-08": { "clicks": 8, "affiliate_clicks": 3, "revenue": 75.50 },
      "2026-03-09": { "clicks": 0, "affiliate_clicks": 0, "revenue": 0.0 }
    }
  }
}

total_clicks   includes all clicks (affiliate and non-affiliate). affiliate_clicks   and affiliate_revenue   are for affiliate clicks only. The periods   key contains a time-series breakdown. Periods with no activity are included as zeros.

List Clicks

Returns all tracked clicks, both affiliate outbound clicks and internal clicks. Use ?affiliate=true   to get only affiliate clicks (outbound clicks to merchants like Amazon, eBay, etc.).

GET /api/analytics/clicks

Parameters:

Each click record includes:

Cart Checkouts Summary

Revenue and checkout counts, broken down by today, this month, all time, and per-period time series.

GET /api/analytics/checkouts/summary

{
  "data": {
    "today": { "checkouts": 5, "revenue": 245.00 },
    "this_month": { "checkouts": 120, "revenue": 6500.00 },
    "all_time": { "checkouts": 3400, "revenue": 185000.00 },
    "periods": {
      "2026-03-07": { "checkouts": 3, "revenue": 150.00 },
      "2026-03-08": { "checkouts": 2, "revenue": 95.00 }
    }
  }
}

List Cart Checkouts

Paginated list of individual cart checkout records.

GET /api/analytics/checkouts

Each checkout record includes:

List Actions

Paginated list of tracked user actions (page views, events, etc.).

GET /api/analytics/actions

Each action record includes: id   , visit_id   , visitor_id   , type   , url   , title   , time_spent_seconds   , created_at   .

AI Token Usage

GET /api/data/openai-tokens

{
  "data": {
    "tokens_used": 125000,
    "tokens_limit": 500000,
    "tokens_remaining": 375000,
    "resets_at": "2026-04-01"
  }
}

Quick Reference