AffiliateRail Reports API

openapi: 3.2.0
info:
  title: Affiliaterail Com Reports API
  version: '2026-08-21'
  description: 'Operations tagged Reports across 2 of this provider''s published API definitions: affiliaterail-com-docs-openapi.json, affiliaterail-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.affiliaterail.com
  description: Production
tags:
- name: Reports
paths:
  /v1/reports:
    get:
      tags:
      - Reports
      summary: Run a report
      description: 'Clicks, leads, customers, sales, refunds, revenue and commissions, cut by `dimension` over an inclusive range. Rows keyed `direct` are money that arrived without a partner; filtering by partner, group or tag reports that slice of the partner programme and excludes direct money. The window of the same length immediately before `from` rides along as `previous_period` with a basis-point `delta`, so a chart never needs two round trips; pass `compare=none` to skip it. `drill_down_config` says how a row''s key becomes a filter.


        **Scope:** `read`'
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          example: prg_7uSyy9FqVLCFWrdPeZaK
        required: true
        name: program_id
        in: query
      - schema:
          type: string
          enum:
          - partner
          - link
          - product
          - group
          - tag
          - period
          default: partner
        required: false
        name: dimension
        in: query
      - schema:
          type: string
          description: ISO date, inclusive. Defaults to twelve months back.
        required: false
        description: ISO date, inclusive. Defaults to twelve months back.
        name: from
        in: query
      - schema:
          type: string
          description: ISO date, inclusive. Defaults to now.
        required: false
        description: ISO date, inclusive. Defaults to now.
        name: to
        in: query
      - schema:
          type: string
        required: false
        name: partner_id
        in: query
      - schema:
          type: string
        required: false
        name: group_id
        in: query
      - schema:
          type: string
        required: false
        name: tag_id
        in: query
      - schema:
          type: string
          enum:
          - day
          - week
          - month
          default: month
          description: Bucket size for the period dimension
        required: false
        description: Bucket size for the period dimension
        name: granularity
        in: query
      - schema:
          type: string
          enum:
          - previous_period
          - none
          default: previous_period
          description: '`previous_period` (the default) returns the preceding window and the delta in the same response'
        required: false
        description: '`previous_period` (the default) returns the preceding window and the delta in the same response'
        name: compare
        in: query
      responses:
        '200':
          description: The report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Report'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or unknown API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Key lacks the required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such object in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The request was understood and refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limited: see Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getV1Reports
      x-operation-id-source: derived
    servers:
    - url: https://api.affiliaterail.com
      description: Production
components:
  schemas:
    Report:
      type: object
      properties:
        object:
          type: string
          enum:
          - report
        dimension:
          type: string
          enum:
          - partner
          - link
          - product
          - group
          - tag
          - period
        currency:
          type: string
          minLength: 3
          maxLength: 3
          example: USD
          description: ISO-4217
        from:
          type: string
          format: date-time
          example: '2026-08-21T10:15:30.000Z'
          description: ISO-8601, UTC
        to:
          type: string
          format: date-time
          example: '2026-08-21T10:15:30.000Z'
          description: ISO-8601, UTC
        rows:
          type: array
          items:
            $ref: '#/components/schemas/ReportRow'
        totals:
          allOf:
          - $ref: '#/components/schemas/ReportRow'
          - description: The true totals for the filter, computed without the grouping. Includes direct sales, so revenue matches the dashboard headline.
        previous_period:
          $ref: '#/components/schemas/ReportPeriod'
        delta:
          $ref: '#/components/schemas/ReportDelta'
        drill_down_config:
          $ref: '#/components/schemas/DrillDownConfig'
      required:
      - object
      - dimension
      - currency
      - from
      - to
      - rows
      - totals
      - previous_period
      - delta
      - drill_down_config
    ReportPeriod:
      type:
      - object
      - 'null'
      properties:
        from:
          type: string
          format: date-time
          example: '2026-08-21T10:15:30.000Z'
          description: ISO-8601, UTC
        to:
          type: string
          format: date-time
          example: '2026-08-21T10:15:30.000Z'
          description: ISO-8601, UTC
        rows:
          type: array
          items:
            $ref: '#/components/schemas/ReportRow'
        totals:
          $ref: '#/components/schemas/ReportRow'
      required:
      - from
      - to
      - rows
      - totals
      description: The window of the same length immediately before `from`, in the same response, so no chart needs a second round trip. Null when `compare=none`.
    CountDelta:
      type:
      - object
      - 'null'
      properties:
        absolute:
          type: integer
          description: current minus previous
        change_bps:
          type:
          - integer
          - 'null'
          description: 'The change as basis points of the previous value: +2083 = +20.83%. Null when the previous period was zero.'
      required:
      - absolute
      - change_bps
    ReportRow:
      type: object
      properties:
        key:
          type:
          - string
          - 'null'
          description: 'The grouping value: an id, a product name, an ISO day, or `direct`. Null is "none".'
        label:
          type: string
        clicks:
          type:
          - integer
          - 'null'
        leads:
          type:
          - integer
          - 'null'
        customers:
          type: integer
        sales:
          type: integer
        refunded:
          type: integer
        revenue_minor:
          type: integer
          example: 2500
          description: Integer minor units (cents, pence). Never a float, never a string.
        commissions_minor:
          type: integer
          example: 2500
          description: Integer minor units (cents, pence). Never a float, never a string.
        conversion_bps:
          type:
          - integer
          - 'null'
          description: customers / clicks in basis points; null with no clicks
        refund_bps:
          type:
          - integer
          - 'null'
      required:
      - key
      - label
      - clicks
      - leads
      - customers
      - sales
      - refunded
      - revenue_minor
      - commissions_minor
      - conversion_bps
      - refund_bps
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
              - authentication_error
              - permission_error
              - invalid_request_error
              - not_found_error
              - conflict_error
              - rate_limit_error
              - plan_error
              - not_implemented_error
              - api_error
            code:
              type: string
            message:
              type: string
            param:
              type: string
          required:
          - type
          - code
          - message
      required:
      - error
    ReportDelta:
      type:
      - object
      - 'null'
      properties:
        clicks:
          $ref: '#/components/schemas/CountDelta'
        leads:
          $ref: '#/components/schemas/CountDelta'
        customers:
          $ref: '#/components/schemas/CountDelta'
        sales:
          $ref: '#/components/schemas/CountDelta'
        refunded:
          $ref: '#/components/schemas/CountDelta'
        revenue:
          $ref: '#/components/schemas/MoneyDelta'
        commissions:
          $ref: '#/components/schemas/MoneyDelta'
      required:
      - clicks
      - leads
      - customers
      - sales
      - refunded
      - revenue
      - commissions
      description: Totals against the previous period, basis points and all integers. Null when `compare=none`.
    MoneyDelta:
      type: object
      properties:
        absolute_minor:
          type: integer
          description: current minus previous, integer minor units in the report's currency
        change_bps:
          type:
          - integer
          - 'null'
          description: 'The change as basis points of the previous value: +2083 = +20.83%. Null when the previous period was zero.'
      required:
      - absolute_minor
      - change_bps
    DrillDownConfig:
      type: object
      properties:
        field:
          type: string
        filter_type:
          type: string
        value_prop:
          type: string
      required:
      - field
      - filter_type
      - value_prop
      description: How a row's `key` becomes a filter on the report and list endpoints
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: rail_live_… or rail_test_…
      description: Create keys in Settings → API keys. Each key carries scopes; the docs name the scope every route needs.
x-refined-from:
- affiliaterail-com-docs-openapi.json
- affiliaterail-com-openapi.json