Intelligems Get Holiday Benchmark Data API

openapi: 3.2.0
info:
  title: Intelligems External Get Holiday Benchmark Data API
  version: v25-10-beta
  description: Programmatic access to manage Intelligems A/B tests, personalizations, and experiences, to define custom events, and to pull experiment and sitewide analytics for a Shopify store. Authenticate with an API key in the `intelligems-access-token` header.
  contact:
    name: Intelligems
    url: https://docs.intelligems.io/developer-resources/external-api
servers:
- url: https://api.intelligems.io
  description: Production
security:
- intelligems_access_token: []
tags:
- name: Get Holiday Benchmark Data
paths:
  /v25-10-beta/analytics/event/snapshot:
    post:
      tags:
      - Get Holiday Benchmark Data
      description: 'Retrieve a seasonal event benchmarking snapshot (Holiday Index and Brand Benchmark) for a shopping event such as BFCM or Labor Day.


        Returns a single KPI object summarizing the brand''s performance across the requested window. To match the Intelligems dashboard''s "Q4 to Date" tile, pass Oct 1 → Dec 31 of the event year. For time-indexed chart data across the event window, use `POST /analytics/event/timeseries`.


        ### Enumerations


        **`event`** — the seasonal event identifier:


        - `"BFCM"` — Black Friday / Cyber Monday

        - `"laborDay"`

        - `"memorialDay"`

        - `"presidentsDay"`


        **`metric`** — the KPI to return:


        - `"revenue"` — net revenue

        - `"orders"` — order count

        - `"priceLevels"` — average unit price


        ### Request


        | Field | Required | Type | Notes |

        | -------- | -------- | ------------------------ | ------------------------------------------------------------------------------------------ |

        | `event` | yes | event enum | See above. |

        | `metric` | yes | metric enum | See above. |

        | `year` | no | integer (2021–2026) | Which event year. Defaults to the most recently completed occurrence. |

        | `start` | **yes** | ISO 8601 datetime string | Beginning of the analysis window. For the dashboard Q4 view, pass Oct 1 of the event year. |

        | `end` | **yes** | ISO 8601 datetime string | End of the analysis window. For the dashboard Q4 view, pass Dec 31 of the event year. |


        ### Response


        ```json

        {

        "currency": "USD",

        "snapshot": {

        "periodToDateValue": 125000.5,

        "vsLastYear": 0.12,

        "avgDailyIndexPercent": 1.27,

        "currentIndexPercent": 1.23

        }

        }

        ```


        - `periodToDateValue` — brand actual value for the selected metric across the event window. Maps to the dashboard''s "Q4 {Metric} to Date" tile.

        - `vsLastYear` — percent change vs. the same period in the prior event year (e.g. `0.12` = +12%). Maps to the ±% pill on the "Q4 to Date" tile.

        - `avgDailyIndexPercent` — the brand''s average daily value as a percent of its own full-day baseline, across the window. Maps to the dashboard''s "Avg Daily {Metric} (% of typical day)" tile.

        - `currentIndexPercent` — the industry-wide average daily index across the window (percent of full-day baseline, aggregated across the ~1,000-brand basket). Maps to the dashboard''s "Index (% of typical day)" tile.


        All numeric fields are `number | null`.


        ### Rate limits


        Uses the same rate limit as the `/analytics/sitewide/*` endpoints. Aggregated, cacheable data — see the Rate Limiting Reference.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                event:
                  type: string
                  enum:
                  - BFCM
                  - laborDay
                  - memorialDay
                  - presidentsDay
                  description: 'Seasonal event identifier. Supported values: "BFCM" (Black Friday / Cyber Monday), "laborDay", "memorialDay", "presidentsDay".'
                metric:
                  type: string
                  enum:
                  - revenue
                  - orders
                  - priceLevels
                  description: 'Metric to return. Supported values: "revenue" (net revenue), "orders" (order count), "priceLevels" (average unit price).'
                year:
                  description: Which year of the event to fetch (e.g. 2025 for BFCM 2025). Defaults to the most recently completed occurrence of the event. The prior-year comparison cohort is always year - 1. For hourly granularity, leave this unset or pass a year matching `end`'s year — passing a mismatched year + end will yield nonsensical results.
                  type: integer
                  minimum: 2021
                  maximum: 2026
                start:
                  type: string
                  format: date-time
                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                  description: Required. Start of analysis period as an ISO 8601 datetime string. Used to size the window before the event (days-before-holiday); does not influence which event year is fetched. For hourly granularity, ignored. To match the Intelligems dashboard's Q4 view, pass Oct 1 of the event year (58 days before BFCM).
                end:
                  type: string
                  format: date-time
                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                  description: Required. End of analysis period as an ISO 8601 datetime string. Used to size the window after the event (days-after-holiday); does not influence which event year is fetched. For hourly granularity this is interpreted as "the day to analyze" and is expected to fall within `year`. To match the Intelligems dashboard's Q4 view, pass Dec 31 of the event year (33 days after BFCM).
              required:
              - event
              - metric
              - start
              - end
      responses:
        '200':
          description: OK
          headers:
            access-control-allow-origin:
              schema:
                type: string
              description: CORS allow-origin header.
            access-control-allow-credentials:
              schema:
                type: string
              description: CORS allow-credentials header.
            content-type:
              schema:
                type: string
              description: Response content type.
            Timing-Allow-Origin:
              schema:
                type: string
              description: Allowed origin for Timing headers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  currency:
                    type: string
                    description: ISO 4217 currency code for monetary values (e.g. 'USD').
                  snapshot:
                    type: object
                    properties:
                      periodToDateValue:
                        anyOf:
                        - type: number
                        - type: 'null'
                        description: The brand's period-to-date actual value for the selected metric across the event window.
                      vsLastYear:
                        anyOf:
                        - type: number
                        - type: 'null'
                        description: Percent change of the brand's period-to-date value vs the same period in the prior event year (e.g. 0.12 = +12%).
                      avgDailyIndexPercent:
                        anyOf:
                        - type: number
                        - type: 'null'
                        description: The brand's average daily value as a percent of its own full-day baseline, across the event window. Maps to the dashboard's 'Avg Daily {Metric} (% of typical day)' tile.
                      currentIndexPercent:
                        anyOf:
                        - type: number
                        - type: 'null'
                        description: The industry-wide average daily index across the event window (percent of full-day baseline, aggregated across the ~1,000-brand basket). Maps to the dashboard's 'Index (% of typical day)' tile.
                    required:
                    - periodToDateValue
                    - vsLastYear
                    - avgDailyIndexPercent
                    - currentIndexPercent
                    additionalProperties: false
                    description: KPI snapshot covering the brand's period-to-date event metrics.
                required:
                - currency
                - snapshot
                additionalProperties: false
      summary: Create v25 10 beta analytics event snapshot
      x-summary-source: derived
      operationId: postV2510BetaAnalyticsEventSnapshot
      x-operation-id-source: derived
  /v25-10-beta/analytics/event/timeseries:
    post:
      tags:
      - Get Holiday Benchmark Data
      description: Retrieve seasonal event benchmarking timeseries data (Holiday Index and Brand Benchmark) for a shopping event such as BFCM or Labor Day.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                event:
                  type: string
                  enum:
                  - BFCM
                  - laborDay
                  - memorialDay
                  - presidentsDay
                  description: 'Seasonal event identifier. Supported values: "BFCM" (Black Friday / Cyber Monday), "laborDay", "memorialDay", "presidentsDay".'
                metric:
                  type: string
                  enum:
                  - revenue
                  - orders
                  - priceLevels
                  description: 'Metric to return. Supported values: "revenue" (net revenue), "orders" (order count), "priceLevels" (average unit price).'
                xAxis:
                  type: string
                  enum:
                  - actualDate
                  - daysFromEvent
                  description: How each datapoint's `dt` is labeled. "actualDate" returns an ISO 8601 datetime; "daysFromEvent" returns a signed integer string (e.g. "-3", "0", "2") relative to the event day.
                granularity:
                  type: string
                  enum:
                  - hourly
                  - daily
                  description: '"hourly" returns one datapoint per hour for the event day (uses the holiday_benchmarking_single_day dataset). "daily" returns one datapoint per day across a range spanning the event (uses holiday_benchmarking_multiple_days).'
                mode:
                  type: string
                  enum:
                  - index
                  - brand
                  - brandWithIndex
                  description: '"index" returns industry-wide index values only (currentYearIndex, priorYearIndex). "brand" returns the caller''s brand actuals vs baseline (currentValue, baselineValue, priorYearValue). "brandWithIndex" returns brand actuals plus the brand''s own index (brandIndex) and industry index overlays.'
                year:
                  description: Which year of the event to fetch (e.g. 2025 for BFCM 2025). Defaults to the most recently completed occurrence of the event. The prior-year comparison cohort is always year - 1. For hourly granularity, leave this unset or pass a year matching `end`'s year — passing a mismatched year + end will yield nonsensical results.
                  type: integer
                  minimum: 2021
                  maximum: 2026
                start:
                  type: string
                  format: date-time
                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                  description: Required. Start of analysis period as an ISO 8601 datetime string. Used to size the window before the event (days-before-holiday); does not influence which event year is fetched. For hourly granularity, ignored. To match the Intelligems dashboard's Q4 view, pass Oct 1 of the event year (58 days before BFCM).
                end:
                  type: string
                  format: date-time
                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                  description: Required. End of analysis period as an ISO 8601 datetime string. Used to size the window after the event (days-after-holiday); does not influence which event year is fetched. For hourly granularity this is interpreted as "the day to analyze" and is expected to fall within `year`. To match the Intelligems dashboard's Q4 view, pass Dec 31 of the event year (33 days after BFCM).
              required:
              - event
              - metric
              - xAxis
              - granularity
              - mode
              - start
              - end
      responses:
        '200':
          description: OK
          headers:
            access-control-allow-origin:
              schema:
                type: string
              description: CORS allow-origin header.
            access-control-allow-credentials:
              schema:
                type: string
              description: CORS allow-credentials header.
            content-type:
              schema:
                type: string
              description: Response content type.
            Timing-Allow-Origin:
              schema:
                type: string
              description: Allowed origin for Timing headers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  currency:
                    type: string
                    description: ISO 4217 currency code for monetary values (e.g. 'USD').
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        dt:
                          type: string
                          description: Datapoint label — an ISO 8601 datetime (when xAxis='actualDate') or a signed day offset as a string (when xAxis='daysFromEvent').
                        dayOffset:
                          description: Signed integer event-offset for this datapoint (0 = event day, negative = before, positive = after). Present on daily-granularity responses; omitted on hourly responses.
                          type: integer
                          minimum: -9007199254740991
                          maximum: 9007199254740991
                        currentValue:
                          description: Brand actual value for the selected metric during the current event year. Populated when mode is 'brand' or 'brandWithIndex'.
                          anyOf:
                          - type: number
                          - type: 'null'
                        baselineValue:
                          description: Brand typical-day baseline value for the selected metric. Populated when mode is 'brand' or 'brandWithIndex'.
                          anyOf:
                          - type: number
                          - type: 'null'
                        priorYearValue:
                          description: Brand actual value for the selected metric during the prior event year. Populated when mode is 'brand' or 'brandWithIndex'.
                          anyOf:
                          - type: number
                          - type: 'null'
                        currentYearIndex:
                          description: Industry-wide index value (percent of full-day baseline) for the current event year. Populated when mode is 'index' or 'brandWithIndex'.
                          anyOf:
                          - type: number
                          - type: 'null'
                        priorYearIndex:
                          description: Industry-wide index value for the prior event year. Populated when mode is 'index' or 'brandWithIndex'.
                          anyOf:
                          - type: number
                          - type: 'null'
                        brandIndex:
                          description: The brand's own value expressed as a percent of its full-day baseline. Populated when mode is 'brandWithIndex'.
                          anyOf:
                          - type: number
                          - type: 'null'
                      required:
                      - dt
                      additionalProperties: false
                    description: Array of datapoints indexed by `dt`. Each entry may populate a subset of value fields depending on the requested `mode`.
                required:
                - currency
                - data
                additionalProperties: false
      summary: Create v25 10 beta analytics event timeseries
      x-summary-source: derived
      operationId: postV2510BetaAnalyticsEventTimeseries
      x-operation-id-source: derived
components:
  securitySchemes:
    intelligems_access_token:
      type: apiKey
      in: header
      name: intelligems-access-token
      description: Intelligems external API access token.