openapi: 3.0.3

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: basic
  schemas:
    AffiliatePurchase:
      type: object
      properties:
        "Transaction Id":
          type: string
        "Created (GMT)":
          type: string
        "Promo Codes":
          type: array
        "Sale Total":
          type: number
        "Sale Commission":
          type: number
        "Item ID":
          type: string
        "Item Name":
          type: string
        "Item Category":
          type: string
        "Item(s) Subtotal (GBP)":
          type: number
        "Currency":
          type: string
        "Exchange rate":
          type: number
          description: only if the purchase was not made in GBP
        "Intl Subtotal":
          type: number
          description: only if the purchase was not made in GBP
        "Quantity":
          type: number
        "Retailer":
          type: string
        "ClickID":
          type: string
          description: the Avelon clickID received with the purchase, if the purchase was attributed via a click
        "AllClickIds":
          type: array
          description: all Avelon clickIDs associated with this purchase
        "SubIds":
          type: array
          description: subnetwork IDs
        "Key":
          type: string
          description: Unique key for the purchase
        "Status":
          type: string
          description: Line item status, one of "pending", "approved", "cancelled"

    Purchases:
      type: array
      items:
        $ref: "#/components/schemas/AffiliatePurchase"

info:
  title: Avelon REST Api Documentation
  description: Avelon REST Api Documentation
  version: 1.0.0
paths:
  /api/affiliate/commission:
    get:
      tags:
        - AvelonAPI
      summary: Export current commission data.
      security:
        - basic: [ ]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    type:
                      type: string
                      description: Commission type. One of [product, category, affiliate]. Product or category levels take precedence over affiliate level.
                    percent:
                      type: number
                      description: Commission percent. Value is between 0 and 1. E.g. 0.2512 means 25.12% commission
                    retailer:
                      type: string
                      description: The retailer the commission applies to
                    product:
                      type: string
                      description: Product ID the commission applies to (if product level)
                      required: false
                    category:
                      type: string
                      description: Category the commission applies to (if category level)
                      required: false
                    created:
                      type: string
                      description: DateTime the commission was added
                  example: [
                    {
                      "type": "product",
                      "percent": "0.1350",
                      "retailer": "retailerpk",
                      "product": "productId",
                      "created": "2024-01-17T10:33:29"
                    }
                  ]
  /api/affiliate/link/create:
    post:
      tags:
        - AvelonAPI
      summary: Create affiliate link
      security:
        - basic: [ ]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                retailer:
                  type: string
                  description: The ID for the retailer you are creating the link for
                destination:
                  type: string
                  description: The the full URL destination of the link. The link domain must be the same as the retailer's base domain.
                alias:
                  type: string
                  description: The link's name
                source:
                  type: string
                  description: UTM source (optional)
                medium:
                  type: string
                  description: UTM medium (optional)
                campaign:
                  type: string
                  description: UTM description (optional)
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  link:
                    type: string
                    description: The affiliate link
  /api/affiliate/links:
    get:
      tags:
        - AvelonAPI
      summary: List all affiliate links. Add format=json as URL parameter to get JSON instead of CSV
      security:
        - basic: [ ]
      parameters:
        - name: cutoffInclusive
          in: query
          description: Return links created on or after this date, returns all if not supplied
          example: 2024-11-25
          required: false
          schema:
            type: string
        - name: includeSubAccounts
          in: query
          description: Whether to include links from sub-accounts if there are any
          example: true
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: OK
          content:
            text/csv:
              schema:
                properties:
                  affiliatePk:
                    type: string
                    description: Affiliate PK the link belongs to. Will be your main account's PK or one of your sub-accounts (if you have any).
                  alias:
                    type: string
                    description: Link alias
                  linkPk:
                    type: string
                    description: Link PK
                  destination:
                    type: string
                    description: Link destination on the retailer's website
                  affiliateLink:
                    type: string
                    description: Avelon affiliate link
                  retailer:
                    type: string
                    description: Retailer PK
                  utmSource:
                    type: string
                    description: UTM source
                  utmMedium:
                    type: string
                    description: UTM medium
                  utmCampaign:
                    type: string
                    description: UTM campaign
                  created:
                    type: string
                    description: Date the link was created
                  live:
                    type: boolean
                    description: Whether the link is live (not revoked)
  /api/affiliate/productfeed/download/{retailerPk}:
    get:
      tags:
        - AvelonAPI
      summary: Download product feed for the specific retailer in CSV format
      security:
        - basic: [ ]
      responses:
        '200':
          description: OK
          content:
            text/csv:
              schema:
                properties:
                  Product Name:
                    type: string
                  Retailer:
                    type: string
                  MPN:
                    type: string
                  Make:
                    type: string
                  Model:
                    type: string
                  RRP:
                    type: string
                  Price:
                    type: string
                  Sale Price:
                    type: string
                  Currency:
                    type: string
                  Image URL:
                    type: string
                    description: The product's image URL
                  UPC:
                    type: string
                  EAN:
                    type: string
                  SKU:
                    type: string
                  ASIN:
                    type: string
                  In Stock:
                    type: string
                    description: Yes or No. Pre-ordered is considered to be in stock.
                  Offer URL:
                    type: string
                    description: Avelon Affiliate URL
                  Offer Clean URL:
                    type: string
                    description: Product URL on the retailer's website. This is the target of the affiliate URL.
  /api/affiliate/retailers:
    get:
      tags:
        - AvelonAPI
      summary: Returns a list of retailers the whose program the affiliate has been approved for.
      security:
        - basic: [ ]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                properties:
                  retailers:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Numerical ID
                        pk:
                          type: string
                          description: Retailer PK
                        name:
                          type: string
                          description: Retailer name
                        website:
                          type: string
                          description: Retailer website
                        baseCommission:
                          type: number
                          description: Base commission that can be overridden by commission rules (see commission endpoint). Value is between 0 and 1. E.g. 0.2512 means 25.12% commission
                        attributionDays:
                          type: integer
                          description: How long after after a click will purchases be attributable for
                        cpcOffering:
                          type: boolean
                          description: Does the retailer pay for clicks
                        countryCode:
                          type: string
                          description: ISO country code of the retailer
                        categories:
                          type: array
                          items:
                            type: string
                            description: List of categories
                example: {
                  "retailers": [
                    {
                      "pk": "test",
                      "name": "test name",
                      "website": "https://example.com",
                      "baseCommission": 0.1000,
                      "attributionDays": 365,
                      "cpcOffering": true
                    },
                    {
                      "pk": "anotherpk",
                      "name": "Another Name",
                      "website": "https://www.test.co.uk",
                      "baseCommission": 0.2000,
                      "attributionDays": 90,
                      "cpcOffering": false
                    }
                  ]
                }


  /api/affiliate/purchases/{monthStartDay}:
    get:
      tags:
        - AvelonAPI
      summary: Returns a CSV or JSON of purchases for a whole month.
      parameters:
        - name: monthStartDay
          in: path
          required: true
          schema:
            type: string
            format: date
          description: First day of month, e.g 2024-03-01
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [ csv, json ]
            default: csv
            description: Response format. Use `json` for JSON; otherwise CSV is returned.
        - name: includeCancelled
          in: query
          required: false
          schema:
            type: boolean
            default: false
            description: Whether to include cancelled purchases
      security:
        - basic: [ ]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Purchases"
            text/csv:
              schema:
                $ref: "#/components/schemas/Purchases"

  /api/affiliate/purchasesRange:
    get:
      tags:
        - AvelonAPI
      summary: Returns a CSV or JSON of purchases for a given range.
      parameters:
        - name: startDay
          in: query
          required: true
          schema:
            type: string
            format: date
          description: start day, e.g 2024-03-06
        - name: endDay
          in: query
          required: false
          schema:
            type: string
            format: date
            default: same as startDay
          description: end day, e.g 2024-03-12
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [ csv, json ]
            default: csv
            description: Response format. Use `json` for JSON; otherwise CSV is returned.
        - name: includeCancelled
          in: query
          required: false
          schema:
            type: boolean
            default: false
            description: Whether to include cancelled purchases
      security:
        - basic: [ ]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Purchases"
            text/csv:
              schema:
                $ref: "#/components/schemas/Purchases"

  /api/retailer/purchase/list/{monthStartDay}:
    get:
      tags:
        - AvelonAPI
      summary: Returns a CSV of purchases for the given month.
      parameters:
        - name: monthStartDay
          in: path
          required: true
          schema:
            type: string
            format: date
          description: First day of month, e.g 2024-03-01
        - name: includeCancelled
          in: query
          required: false
          schema:
            type: boolean
            default: false
            description: Whether to include cancelled purchases
      security:
        - basic: [ ]
      responses:
        '200':
          description: OK
          content:
            text/csv:
              schema:
                type: array
                properties:
                  "Transaction Id":
                    type: string
                  "Created (GMT)":
                    type: string
                  "Promo Codes":
                    type: array
                  "Sale Total":
                    type: number
                  "Sale Commission":
                    type: number
                  "Item ID":
                    type: string
                  "Item Name":
                    type: string
                  "Item Category":
                    type: string
                  "Item(s) Subtotal (GBP)":
                    type: number
                  "Currency":
                    type: string
                  "Exchange rate":
                    type: number
                    description: only if the purchase was not made in GBP
                  "Intl Subtotal":
                    type: number
                    description: only if the purchase was not made in GBP
                  "Quantity":
                    type: number
                  "Affiliates":
                    type: string
                    description: list of affiliates the sale is attributed to (name and PK)
                  "ClickID":
                    type: string
                    description: the Avelon clickID received with the purchase, if the purchase was attributed via a click
                  "AllClickIds":
                    type: array
                    description: all Avelon clickIDs associated with this purchase
                  "Status":
                    type: string
                    description: Line item status, one of "pending", "approved", "cancelled"

