openapi: 3.0.3
info:
  title: Feedico Partner API
  version: "1.0.0"
  description: |
    Live coupon codes, deals, merchants and products from affiliate networks (CJ, Awin, Impact, Admitad and more).
    **Every result includes a tracked `goUrl` that carries your partner ID**: when your users buy through it, you
    keep 65% of the network commission. No network applications needed.

    - Join the free Partner Program at https://partner.feedico.io, verify your website (or send your app / AI agent
      for review) and create a partner token in Settings.
    - Auth: `Authorization: Bearer fdcp_...`
    - Show `goUrl` to your users and let them click. Do not request `goUrl` from a server, bot or AI agent: use
      `POST /api/links/validate` to check links without creating clicks.
    - AI assistants: the same data is available as an MCP server (`npx feedico-mcp` or https://mcp.feedico.io/mcp),
      see https://feedico.io/ai-coupon-agent
  contact:
    email: support@feedico.io
    url: https://partner.feedico.io/docs
servers:
  - url: https://partner.feedico.io
security:
  - partnerToken: []
tags:
  - name: Catalog
  - name: Links
  - name: Reports
paths:
  /api/catalog/coupons:
    post:
      tags: [Catalog]
      operationId: searchCoupons
      summary: Search active coupon codes and deals
      description: Active offers only (expired codes are filtered out). Each row has a tracked goUrl (with `c=` for the code).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                q: { type: string, description: "Keyword or store name, e.g. \"nike\"", example: nike }
                merchant: { type: string, description: "Store id (goSlug) from /api/catalog/merchants" }
                countries: { type: array, items: { type: string, example: US }, description: ISO 3166-1 alpha-2 codes }
                endingWithinDays: { type: integer, minimum: 1, description: Only offers ending within N days }
                sort: { type: string, description: Sort order }
                page: { type: integer, minimum: 1, default: 1 }
                pageSize: { type: integer, minimum: 1, maximum: 200, default: 48 }
      responses:
        "200":
          description: Coupons
          content:
            application/json:
              schema:
                type: object
                properties:
                  coupons: { type: array, items: { $ref: "#/components/schemas/Coupon" } }
                  meta: { $ref: "#/components/schemas/Meta" }
                  partnerPublicId: { type: string }
        "401": { $ref: "#/components/responses/Unauthorized" }
  /api/catalog/merchants:
    post:
      tags: [Catalog]
      operationId: searchMerchants
      summary: Search stores (merchants)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                q: { type: string, description: Store name or domain, example: adidas }
                hasCoupons: { type: boolean }
                minCoupons: { type: integer }
                countries: { type: array, items: { type: string } }
                page: { type: integer, minimum: 1, default: 1 }
                pageSize: { type: integer, minimum: 1, maximum: 200, default: 48 }
      responses:
        "200":
          description: Merchants
          content:
            application/json:
              schema:
                type: object
                properties:
                  merchants: { type: array, items: { $ref: "#/components/schemas/Merchant" } }
                  meta: { $ref: "#/components/schemas/Meta" }
                  partnerPublicId: { type: string }
        "401": { $ref: "#/components/responses/Unauthorized" }
  /api/catalog/products:
    post:
      tags: [Catalog]
      operationId: searchProducts
      summary: Search products (keyword, brand, store, SKU, price)
      description: Millions of affiliate products with prices, sale prices and images. Product goUrls carry `sku=`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                q: { type: string, example: running shoes }
                brand: { type: string }
                sku: { type: string, description: Exact SKU / manufacturer part number }
                firmName: { type: string, description: Limit to one store name }
                merchant: { type: string, description: Store id (merchantKey) }
                onSale: { type: boolean, description: Only discounted products }
                minPrice: { type: number }
                maxPrice: { type: number }
                currency: { type: string, example: USD }
                countries: { type: array, items: { type: string } }
                pageSize: { type: integer, minimum: 1, maximum: 500, default: 50 }
                cursor: { type: string, description: nextCursor from the previous page }
      responses:
        "200":
          description: Products
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  products: { type: array, items: { $ref: "#/components/schemas/Product" } }
                  recordCount: { type: integer }
                  recordCountApproximate: { type: boolean }
                  nextCursor: { type: string, nullable: true }
                  partnerPublicId: { type: string }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "503": { description: "query_timeout: search too broad; add a store, brand or narrower q" }
  /api/links:
    post:
      tags: [Links]
      operationId: createLink
      summary: Create a tracked link for a store (optionally with a coupon code)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [merchantSlug]
              properties:
                merchantSlug: { type: string, description: Store id (goSlug) }
                code: { type: string, nullable: true }
      responses:
        "200":
          description: Link
          content:
            application/json:
              schema:
                type: object
                properties:
                  url: { type: string, example: "https://feedico.io/go/104407?p=YOUR_ID&c=SAVE10" }
                  merchantSlug: { type: string }
                  code: { type: string, nullable: true }
                  partnerPublicId: { type: string }
        "404": { description: merchant_not_found }
        "429": { description: rate_limited }
  /api/links/validate:
    post:
      tags: [Links]
      operationId: validateLinks
      summary: Check up to 50 of your links without creating clicks
      description: |
        Same resolution as a real click (store, network, coupon code, deep link `url=`, temporary rerouting),
        but nothing is logged, redirected or sent to a network. Use it for automated link checks. 20 requests/minute.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [links]
              properties:
                links:
                  type: array
                  maxItems: 50
                  items:
                    oneOf:
                      - type: string
                        example: "https://feedico.io/go/234909?p=YOUR_ID&c=SAVE10"
                      - type: object
                        properties:
                          merchantSlug: { type: string }
                          code: { type: string, nullable: true }
                          url: { type: string, nullable: true, description: Deep link target on the store's site }
                          sku: { type: string, nullable: true }
      responses:
        "200":
          description: One result per link, in order
          content:
            application/json:
              schema:
                type: object
                properties:
                  results: { type: array, items: { $ref: "#/components/schemas/LinkCheck" } }
                  summary:
                    type: object
                    properties:
                      checked: { type: integer }
                      ok: { type: integer }
                      notOk: { type: integer }
                  note: { type: string }
  /api/reports/clicks:
    get:
      tags: [Reports]
      operationId: listClicks
      summary: Your recent clicks (with suspected-bot flags)
      parameters:
        - { name: days, in: query, schema: { type: integer, default: 30 } }
        - { name: since, in: query, schema: { type: string, format: date-time } }
        - { name: merchant, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, default: 100 } }
      responses:
        "200":
          description: Clicks
          content:
            application/json:
              schema:
                type: object
                properties:
                  clicks: { type: array, items: { $ref: "#/components/schemas/Click" } }
                  summary: { type: object }
  /api/reports/commissions:
    get:
      tags: [Reports]
      operationId: listCommissions
      summary: Your commissions (your share only)
      parameters:
        - { name: days, in: query, schema: { type: integer, default: 90 } }
        - { name: status, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, default: 100 } }
      responses:
        "200":
          description: Commissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  commissions: { type: array, items: { $ref: "#/components/schemas/Commission" } }
components:
  securitySchemes:
    partnerToken:
      type: http
      scheme: bearer
      description: Partner token (fdcp_...) from https://partner.feedico.io/settings
  responses:
    Unauthorized:
      description: Missing or invalid partner token
  schemas:
    Meta:
      type: object
      properties:
        total: { type: integer }
        limit: { type: integer }
        offset: { type: integer }
        hasMore: { type: boolean }
    Coupon:
      type: object
      properties:
        id: { type: string }
        goSlug: { type: string, description: Store id }
        merchantName: { type: string }
        provider: { type: string, example: cj_affiliate }
        code: { type: string, description: "Empty for deals without a code" }
        title: { type: string }
        endsAt: { type: string, format: date-time, nullable: true }
        websiteUrl: { type: string, nullable: true }
        countries: { type: array, items: { type: string } }
        goUrl: { type: string, description: Tracked link with your partner ID }
    Merchant:
      type: object
      properties:
        goSlug: { type: string }
        name: { type: string }
        provider: { type: string }
        websiteUrl: { type: string, nullable: true }
        couponCount: { type: integer }
        goUrl: { type: string }
    Product:
      type: object
      properties:
        id: { type: string }
        firmName: { type: string }
        merchantKey: { type: string }
        merchantDomain: { type: string, nullable: true }
        provider: { type: string }
        externalProductId: { type: string }
        title: { type: string, nullable: true }
        description: { type: string, nullable: true }
        brand: { type: string, nullable: true }
        sku: { type: string, nullable: true }
        gtin: { type: string, nullable: true }
        price: { type: number, nullable: true }
        salePrice: { type: number, nullable: true }
        discountPercentage: { type: number, nullable: true }
        currency: { type: string, nullable: true }
        availability: { type: string, nullable: true }
        countries: { type: array, items: { type: string }, nullable: true }
        images:
          type: array
          items:
            type: object
            properties:
              url: { type: string }
              sortOrder: { type: integer }
              isPrimary: { type: boolean }
        thumbnailUrl: { type: string, nullable: true, description: https image (proxied when the feed image is http) }
        goUrl: { type: string }
    LinkCheck:
      type: object
      properties:
        input: { type: string }
        ok: { type: boolean, description: A click now would land on a tracked network link (commission possible) }
        status:
          type: string
          enum: [ok, store_only, unknown_partner, unknown_merchant, no_destination, not_your_link, not_a_feedico_go_link, invalid_url, invalid_link]
        merchant:
          type: object
          properties:
            slug: { type: string }
            name: { type: string, nullable: true }
            website: { type: string, nullable: true }
        network: { type: string, nullable: true }
        commission: { type: boolean }
        rerouted: { type: boolean }
        coupon:
          type: object
          nullable: true
          properties:
            code: { type: string }
            active: { type: boolean }
            endsAt: { type: string, nullable: true }
        product:
          type: object
          nullable: true
          properties:
            sku: { type: string }
            found: { type: boolean }
        deepLink:
          type: object
          nullable: true
          properties:
            url: { type: string }
            status: { type: string, enum: [will_apply, invalid, off-site, unsupported, ignored] }
        notes: { type: array, items: { type: string } }
    Click:
      type: object
      properties:
        clickId: { type: string }
        merchantSlug: { type: string }
        couponCode: { type: string, nullable: true }
        provider: { type: string, nullable: true }
        countryCode: { type: string, nullable: true }
        city: { type: string, nullable: true }
        createdAt: { type: string, format: date-time }
        goPath: { type: string, nullable: true }
        productSku: { type: string, nullable: true }
        productTitle: { type: string, nullable: true }
        commissionStatus: { type: string, nullable: true }
    Commission:
      type: object
      properties:
        id: { type: integer }
        provider: { type: string }
        externalActionId: { type: string }
        clickId: { type: string, nullable: true }
        merchantSlug: { type: string, nullable: true }
        publisherAmount: { type: number, description: Your share only }
        currency: { type: string }
        shareBps: { type: integer }
        status: { type: string }
        networkStatus: { type: string, nullable: true }
        occurredAt: { type: string, nullable: true }
        ingestedAt: { type: string }
