Intelligems Create Experience API

openapi: 3.2.0
info:
  title: Intelligems External Create Experience 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: Create Experience
  description: 'The following experience types are supported by the Intelligems Experiments API:


    - `content/advanced` — Advanced content test (custom CSS/JS injection)

    - `content/onsiteEdits` — Onsite edits (visual editor changes)

    - `content/url` — URL redirects

    - `content/theme` — Theme redirects

    - `content/template` — Template redirects

    - `personalization` — Personalization rules

    - `personalization/offer` — Offer test (structured discount campaigns configured via the `offer` field on each variation)


    The…'
paths:
  /v25-10-beta/experiences:
    post:
      tags:
      - Create Experience
      description: 'Creates a new experience.


        The experience will be created in a draft state and must be activated separately before it will be served to visitors.


        ### Required Fields


        - `name` - A unique name for the experience

        - `type` - The type of test (content, redirect, etc.)

        - `variations` - At least one variation must be provided


        ### Optional Fields


        - `audience` — Audience targeting rules

        - `excludeCurrency` — Currency/geo-based visitor targeting. When `exclude` is

        `true`, only visitors matching the given `currency` (ISO 4217 code) are included in the experience; everyone

        else is excluded. Set `currency` to `null` (with `exclude: false`) to disable.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                experience:
                  type: object
                  properties:
                    name:
                      type: string
                      minLength: 1
                      description: Short display name shown in dashboards and reports. Aim for under ~60 characters. Summarize rather than enumerate — do NOT list every product. For 3 or more products, describe the set (e.g. '+10% price test — 5 bestsellers' or '+$3 price test — Watches collection'), not the individual titles.
                    description:
                      description: Internal note explaining what this experience tests. Helpful for team context. Free-text and human-owned — it is never regenerated automatically, so if you later add products to this experience, update it yourself if it has gone stale.
                      anyOf:
                      - type: string
                      - type: 'null'
                    currency:
                      description: Currency for price display and analytics. Omit to default to USD.
                      anyOf:
                      - type: object
                        properties:
                          code:
                            default: USD
                            description: ISO 4217 currency code used for analytics and price calculations.
                            type: string
                          country:
                            description: ISO country code for locale-specific formatting.
                            type: string
                          options:
                            description: Additional locale-specific formatting options.
                          symbol:
                            default: $
                            description: Display symbol prepended to amounts (e.g., '$', '€').
                            type: string
                          suffix:
                            description: Text appended after amounts for postfix currencies (e.g., 'kr' in '100 kr').
                            type: string
                      - type: 'null'
                    previewPath:
                      description: Store URL path for generating preview links (e.g., '/products/example').
                      anyOf:
                      - type: string
                      - type: 'null'
                    type:
                      type: string
                      enum:
                      - content/advanced
                      - content/onsiteEdits
                      - content/url
                      - content/theme
                      - content/template
                      - personalization
                      - personalization/offer
                      - pricing
                      - checkoutBlock
                      description: Immutable after creation. Must match the existing value from GET response.
                    experienceAnalysis:
                      type: object
                      properties:
                        analyticsViewType:
                          default: none
                          description: Scope of orders included in analytics results. Determines whether only tested products or all store orders are counted.
                          type: string
                          enum:
                          - test_orders_only
                          - sitewide_orders
                          - none
                      description: Controls which orders are included in analytics results.
                    productVariantAction:
                      anyOf:
                      - type: object
                        properties:
                          type:
                            type: string
                            const: analytics
                          location:
                            type: object
                            properties:
                              bucket:
                                type: string
                              key:
                                type: string
                            required:
                            - bucket
                            - key
                        required:
                        - type
                        - location
                      - type: object
                        properties:
                          type:
                            type: string
                            const: price
                          location:
                            type: object
                            properties:
                              bucket:
                                type: string
                              key:
                                type: string
                            required:
                            - bucket
                            - key
                        required:
                        - type
                        - location
                      - type: object
                        properties:
                          type:
                            type: string
                            const: offer
                          location:
                            type: object
                            properties:
                              bucket:
                                type: string
                              key:
                                type: string
                            required:
                            - bucket
                            - key
                        required:
                        - type
                        - location
                    variations:
                      description: 'Full replacement — include ALL variations to keep. Omitted variations are deleted. One must be control, percentages must sum to 100. Match variation mechanisms to experience type: onsiteEdits for DOM changes, onsiteInjection for CSS/JS, redirects for URL/theme/template tests.'
                      minItems: 1
                      type: array
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                            minLength: 1
                            maxLength: 255
                            description: Display name (e.g., 'Control', 'Variant A'). Must be unique across variations.
                          percentage:
                            type: number
                            minimum: 0
                            maximum: 100
                            description: Traffic allocation weight. All percentages across variations must sum to 100.
                          isControl:
                            default: false
                            description: The baseline variation all others are measured against. Exactly one per experience.
                            type: boolean
                          order:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                            description: Display order in analytics. Must be unique across variations. 0-indexed.
                          priceChange:
                            description: 'Group-level price transform for a pricing-type experience. Set on each non-control test group to define its price change relative to each product''s base price (e.g. ''10'' with priceChangeUnit ''percent'' for +10%, or ''-5'' for a discount). Leave null/empty on the control group so it keeps the base price. This defines the group''s transform only; NO products are attached here. REQUIRED NEXT STEP: after this create returns an experienceId, call prepare_seed_price_test_products with that id and the chosen product variants to attach them and compute per-variant prices — it reads this transform back off the experience. A pricing experience created here has no products until you run that seed step.'
                            anyOf:
                            - type: string
                            - type: 'null'
                          priceChangeUnit:
                            description: 'How priceChange is applied: ''percent'' (a percentage of the base price) or ''dollar'' (a fixed monetary amount).'
                            anyOf:
                            - type: string
                              enum:
                              - percent
                              - dollar
                            - type: 'null'
                          priceRoundingType:
                            description: 'Rounding applied after priceChange: ''none'', ''nearest'', ''up'', or ''down'' (e.g. ''down'' with priceRoundingAmount ''0.99'' for charm pricing).'
                            anyOf:
                            - type: string
                              enum:
                              - none
                              - nearest
                              - up
                              - down
                            - type: 'null'
                          priceRoundingAmount:
                            description: Target value for rounding, e.g. '0.99' for charm pricing like $X.99. Only meaningful when priceRoundingType is not 'none'.
                            anyOf:
                            - type: string
                            - type: 'null'
                          excludeProducts:
                            description: Flag (not a product list). When true, specific products are excluded from the price change. Mutually exclusive with includeProducts. Products themselves are attached in the seed step, not here.
                            default: false
                            type: boolean
                          includeProducts:
                            description: Flag (not a product list). When true, only specific products receive the price change. Mutually exclusive with excludeProducts. Products themselves are attached in the seed step, not here.
                            default: false
                            type: boolean
                          cartTargeting:
                            description: Cart-based targeting rules that determine when this variation is shown based on cart contents.
                            default: []
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                expression:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      query:
                                        type: object
                                        properties:
                                          key:
                                            type: string
                                            enum:
                                            - anything
                                            - productId
                                            - collection
                                            - tag
                                            - cartSubtotal
                                            - cartItemCount
                                            - subscription
                                          type:
                                            type: string
                                            enum:
                                            - anything
                                            - productId
                                            - collection
                                            - tag
                                            - cartSubtotal
                                            - cartItemCount
                                            - subscription
                                          filter:
                                            type: string
                                            enum:
                                            - includes
                                            - doesNotInclude
                                            - greaterThan
                                            - lessThan
                                            - equalTo
                                            - greaterThanOrEqual
                                            - lessThanOrEqual
                                            - between
                                          value:
                                            anyOf:
                                            - type: string
                                            - type: number
                                            - type: object
                                              propertyNames:
                                                type: string
                                              additionalProperties:
                                                type: array
                                                items:
                                                  type: object
                                                  properties:
                                                    variantId:
                                                      type: string
                                                    inclusionType:
                                                      type: string
                                                      enum:
                                                      - include
                                                      - exclude
                                                  required:
                                                  - variantId
                                                  - inclusionType
                                        required:
                                        - key
                                        - type
                                        - filter
                                      operator:
                                        type: string
                                        enum:
                                        - and
                                        - or
                                        - start_paren
                                        - end_paren
                              required:
                              - id
                              - expression
                          components:
                            description: Onsite component configurations (e.g. onsite upsells) rendered on the storefront for this variation.
                            default: []
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  description: Server-generated. Read-only.
                                variationId:
                                  type: string
                                  format: uuid
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  description: References the parent variation this component belongs to.
                                config:
                                  oneOf:
                                  - type: object
                                    properties:
                                      type:
                                        type: string
                                        const: onsiteUpsell
                                        description: Discriminator for the component kind.
                                      placement:
                                        type: object
                                        properties:
                                          selector:
                                            type: string
                                            description: CSS selector for the anchor element the upsell is inserted near.
                                          insertType:
                                            type: string
                                            enum:
                                            - beforebegin
                                            - afterbegin
                                            - beforeend
                                            - afterend
                                            description: Where, relative to the anchor element, the upsell is inserted (before/after, inside start/end).
                                          location:
                                            type: string
                                            enum:
                                            - pdp
                                            - cart
                                            description: Semantic page context this upsell renders in (pdp or cart). Drives the plugin's activation/re-render strategy and labels/groups the upsell in analytics.
                                        required:
                                        - selector
                                        - insertType
                                        - location
                                        description: Where in the DOM the rendered upsell is injected.
                                      template:
                                        type: string
                                        description: 'HTML for the upsell, including all static copy written inline. The per-product card is the markup between {{#each products}} and {{/each}}. May only reference declared slots: product.* data slots and the named slots (atc, variant-select); everything else is literal HTML.'
                                      maxProductLimit:
                                        type: integer
                                        minimum: -9007199254740991
                                        maximum: 9007199254740991
                                        description: Maximum number of products to render.
                                      excludeOutOfStock:
                                        default: true
                                        description: Exclude products whose variants are all out of stock. Defaults to true.
                                        type: boolean
                                      excludeItemsInCart:
                                        default: true
                                        description: Exclude products already in the shopper's cart. Defaults to true.
                                        type: boolean
                                      discount:
                                        description: Optional discount applied to products added from this upsell.
                                        type: object
                                        properties:
                                          discountType:
                                            default: none
                                            type: string
                                            enum:
                                            - none
                                            - percentage
                                            - fixed
                                          discountValue:
                                            anyOf:
                                            - type: number
                                            - type: 'null'
                                          compareAtPriceDisplay:
                                            default: none
                                            type: string
                                            enum:
                                            - none
                                            - compareAtPrice
                                            - regularPrice
                                      rules:
                                        type: array
                                        items:
                                          type: object
                                          properties:
                                            id:
                                              type: string
                                              description: Stable identifier for this rule. Owns the rule's targeting row(s) in the targeting table.
                                            priority:
                                              type: integer
                                              minimum: -9007199254740991
                                              maximum: 9007199254740991
                                              description: Evaluation order. Lower numbers are checked first; the first rule whose targeting matches wins.
                                            action:
                                              type: array
                                              items:
                                                type: object
                                                properties:
                                                  query:
                                                    type: object
                                                    properties:
                                                      key:
                                                        type: string
                                                        enum:
                                                        - shopifyRecommendations
                                                        - productId
                                                        - collection
                                                        - tag
                                                      type:
                                                        type: string
                                                        enum:
                                                        - shopifyRecommendations
                                                        - productId
                                                        - collection
                                                        - tag
                                                      filter:
                                                        type: string
                                                        enum:
                                                        - includes
                                                        - doesNotInclude
                                                      value:
                                                        anyOf:
                                                        - type: string
                                                        - type: number
                                                        - type: array
                                                          items:
                                                            type: object
                                                            properties:
                                                              order:
                                                                type: number
                                                              productId:
                                                                type: string
                                                              productTitle:
                                                                type: string
                                                              handle:
                                                                anyOf:
                                                                - type: string
                                                                - type: 'null'
                                                              productImage:
                                                                anyOf:
                                                                - type: string
                                                                - type: 'null'
                                                              description:
                                                                anyOf:
                                                                - type: string
                                                                - type: 'null'
                                                              options:
                                                                type: array
                                                                items:
                                                                  type: object
                                                                  properties:
                                                                    name:
                                                                      type: string
                                                                    values:
                                                                      type: array
                                                                      items:
                                                                        type: string
                                                                  required:
                                                                  - name
                                                                  - values
                                                              variants:
                                                                type: array
                                                                items:
                                                                  type: object
                                                                  properties:
                                                                    variantId:
                                                                      type: string
                                                                    variantTitle:
                                                                      type: string
                                                                    variantImage:
                                                                      anyOf:
                                                                      - type: string
                                                                      - type: 'null'
                                                                    price:
                                                                      type: number
                                                                    compareAtPrice:
                                                                      anyOf:
                                                                      - type: number
                                                                      - type: 'null'
                                                                    currencyCode:
                                                                      type: string
                                                                    availableForSale:
                                                                      type: boolean
                                                                    sig:
                                                                      anyOf:
                                                                      - type: string
                                                                      - type: 'null'
                                                                    inclusionType:
                                                                      type: string
                                                                      enum:
                                                                      - include
                                                                      - exclude
                                                                    variantOptions:
                                                                      type: array
                                                                      items:
                                                                        type: object
                                                                        properties:
                                                                          name:
                                                                            type: string
                                                                          value:
                                                                            type: string
                                                                        required:
                                                                        - name
                                                                        - value
                                                                  required:
                                                                  - variantId
                                                                  - variantTitle
                                                                  - price
                                                                  - inclusi

# --- truncated at 32 KB (413 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/intelligems/refs/heads/main/openapi/intelligems-create-experience-api-openapi.yml