feedico-io Coupons API

openapi: 3.2.0
info:
  title: Feedico customer data Coupons API
  version: 1.4.0
  description: 'Feedico exposes complementary **POST-only** list APIs (JSON body, may be `{}`). **`GET`** is not supported (`405`).


    ### Auth (tenant identity)

    **`Authorization: Bearer fdco_...`** from dashboard **Account**.

    The API **never** accepts `userId` / account id in the JSON body — the tenant is resolved only from the token → `app_users`.


    ### Your account (`/api/v1/me/*`)

    Merchant programmes, coupons, and **products** from **your** connected affiliate networks.

    Coupon/product rows may include **`offerUrl`** (your synced affiliate links). Products include **`images[]`**.


    ### Global catalogue (`/api/v1/catalog/*`)

    Aggregated index across **all Feedico tenants** — useful for discovery, SEO tooling, and coupon-site research.

    - **`POST /api/v1/catalog/networks`** — firms deduplicated by **display name**.

    - **`POST /api/v1/catalog/coupons`** — promo codes with a non-empty **`code`**, deduplicated by **brand + code**.

    - **`POST /api/v1/catalog/products`** — products (newest first; no `offerUrl`).

    - Rows from Feedico''s managed catalogue include a ready tracked link, **`goUrl`** (null for stores we don''t manage). Use it as the link on your "Get deal" / "Shop" buttons. Want to earn the commission yourself? Join the free Partner Program (you keep 65%): its API returns links with your own partner ID.

    - Includes **CJ, Impact, Admitad, …** unified rows **and** **Awin** programme + voucher snapshots (coupons/firms).


    ### Auth & quota

    Each successful **`/api/v1/me/*`** or **`/api/v1/catalog/*`** response counts **one** request against your plan’s monthly API cap (UTC month). Over limit → **`429`** **`monthly_api_limit`**.


    ### Pagination & filters

    - **`recordCount`** — total matching filters. On `/api/v1/catalog/products`, filtered queries return an exact count up to 10,000 (`recordCountApproximate: false`), above 10,000, or when counting takes too long, it is a lower bound with `recordCountApproximate: true`. Unfiltered browsing returns the catalogue size estimate.

    - **`page`** / **`pageSize`** — firms/coupons max **200**; **products max 500** (default **50**). Prefer **`cursor`** / **`nextCursor`** for large product feeds (keyset pagination; avoids deep OFFSET).

    - **`provider`** — e.g. `cj_affiliate`; omit for all sources.

    - **`firmName`**, product extras: **`q`**, **`brand`**, **`sku`**, **`currency`**, **`minPrice`**, **`maxPrice`**.

    - **`includeInactive`** — default `false`.'
servers:
- url: https://api.feedico.io
  description: Production
- url: http://127.0.0.1:3010
  description: Local Next (`next start` same port as systemd feedico-web)
tags:
- name: Coupons
  description: Your account coupons (`POST /api/v1/me/coupons`).
paths:
  /api/v1/me/coupons:
    post:
      tags:
      - Coupons
      summary: List coupons - paginated POST
      operationId: meCoupons
      security:
      - ApiTokenBearer: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerDataListRequest'
      responses:
        '200':
          description: Page of coupons
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CouponListResponse'
        '400':
          description: Invalid JSON body
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeError'
        '429':
          description: Monthly plan API quota exceeded (each successful call counts  -  Starter / Pro / Business each have a `/api/v1/me/*` request cap per UTC month)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonthlyApiQuotaError'
components:
  schemas:
    MeError:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    MonthlyApiQuotaError:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    CustomerDataListRequest:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    CouponListResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true