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.

Note: Fill skips products that are currently out of stock at the merchant. This protects your store from importing items visitors cannot buy. To import out-of-stock or pre-order items on purpose, use the Link Importer or the Product Finder in the dashboard.

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.

Note: Import Links treats every link as an explicit choice. Out-of-stock and pre-order items are imported as requested. To clear out-of-stock items later, use the Clean Store endpoint with operations: ["out_of_stock_offers"].

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", "..." : "..." }
  }
}

Clean Store

POST /api/store/clean

Removes expired offers, offerless products, empty brands, and empty categories. Optionally also removes out-of-stock offers. Mirrors the Store Cleaner tool in your store dashboard.

What each operation does

• expired_offers: deletes offers that the merchant no longer lists in their API (the product has been removed or delisted entirely).
• out_of_stock_offers: deletes offers that are currently out of stock at the merchant. Opt-in only, because out-of-stock items can come back in stock at any time. Run this only when you want to clear those products from your store now.
• offerless_products: deletes products that have no offers attached.
• empty_brands: deletes brands with no products.
• empty_categories: deletes categories with no products and no children.

Response 200

{
  "data": {
    "deleted": {
      "expired_offers": 12,
      "offerless_products": 3,
      "empty_brands": 1,
      "empty_categories": 0
    }
  }
}

The response only contains keys for the operations that were requested. To run the out-of-stock cleanup, pass operations: ["out_of_stock_offers"] on its own or alongside other operations.

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

Example body

{
  "merchant": "amazon",
  "merchant_offer_id": "B0GR52QJCF",
  "title": "Amazon Product",
  "url_detail": "https://www.amazon.com/dp/B0GR52QJCF"
}

To attach the new offer to one or more existing products, follow up with a POST /api/offers/{id}/products   call.

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  

Generate Category List (AI)

POST /api/categories/generate-list

AI-suggest a structured category tree for the store's niche. Returns the proposed tree as JSON; the caller is expected to then POST /api/categories for each one (optionally with generate_ai_content / generate_images). Chips are billed once for the AI call via RequestContent.

Response 200  

{
  "data": {
    "niche": "vintage cameras",
    "categories": [
      {
        "title": "Film SLRs",
        "subcategories": ["35mm", "Medium Format", "Manual Focus"]
      },
      {
        "title": "Rangefinders",
        "subcategories": ["Fixed Lens", "Interchangeable Lens"]
      }
    ]
  }
}

If the AI call fails, returns 503 with the standard error envelope.

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).

Fill Empty Images

POST /api/articles/{id}/fill-empty-images

Copies the article's Hero Image into the Listing and Social image slots when those slots are empty. Mirrors the Fill Empty Images checkbox on the article edit page. Existing images are never overwritten. If the article has no Hero Image set, the call is a no-op.

This is useful for saving AI Chips: generate only the Hero Image on article creation (generate_images: ["hero"], ~50k chips) and then call this endpoint to populate the Listing and Social slots for free.

Response 200

{
  "data": {
    "filled": ["listingImage", "socialImage"]
  }
}

The filled array lists which image collections were populated by this call. An empty array means either the Hero Image was not set, or both slots were already populated.

Generate Article Topics (AI)

POST /api/articles/generate-topics

Generate a batch of niche-appropriate article topic suggestions for the store. Each topic is one AI call so chips are billed N times. The suggestions are intended as inputs to POST /api/articles (with generate_ai_content: true to write the article itself).

Response 200  

{
  "data": {
    "topics": [
      "Beginners Guide to Buying Your First Film Camera",
      "Caring for Vintage Camera Leather and Bellows",
      "How to Spot a Rangefinder That\'s Worth the Price"
    ],
    "requested": 3,
    "returned": 3
  }
}

returned may be less than requested if the AI returned a duplicate suggestion or an empty result for one of the calls.

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. The generate_ai_content flag works here too: pass true on an existing page (e.g. the auto-created homepage page on a fresh store) and the page's title, subtitle, meta, and homepage hero content block will be AI-filled in the background.

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