Intelligems Update Experience API

openapi: 3.2.0
info:
  title: Intelligems External Update 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: Update Experience
  description: 'Updates an existing experience. This is a full PUT replacement — the entire experience configuration is replaced with the provided data.


    All required fields must be included in every request. Any optional fields omitted will be reset to their defaults.


    All nested entities (variations, key metrics, page targeting, audience) must include their `id` field from the original GET response. All fields are nested inside a single `experience` object in the request body.'
paths:
  /v25-10-beta/experiences/{experienceId}:
    put:
      tags:
      - Update Experience
      description: 'Updates an existing experience by ID. This is a full PUT replacement — the entire experience configuration is replaced with the provided data.


        All required fields must be included in every request. Any optional fields omitted will be reset to their defaults.


        ### Required Fields (inside `experience`)


        - `id` (UUID) — ID of the experience to update

        - `name` (string) — Name of the experience

        - `type` (string) — One of: `"content/advanced"`, `"content/onsiteEdits"`, `"content/url"`, `"content/theme"`, `"content/template"`

        - `experienceAnalysis` — Analysis configuration (includes `analyticsViewType`)

        - `variations` — Array of variation objects. Each variation must include its `id`.

        - `experienceKeyMetrics` — Array of key metric objects. Each must include its `id`.


        ### Optional Fields (inside `experience`)


        - `description` (string) — Description of the experience

        - `currency` — Currency display settings

        - `previewPath` (string) — URL path for previewing

        - `audience` — Audience targeting rules (must include `id` if provided)

        - `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.

        - `experiencePageTargeting` — Array of page targeting rules (each must include `id`)


        ### Important Notes


        - The experience must exist and belong to your organization

        - Updating a running experience may affect active visitors

        - Variation weights must sum to 100

        - All nested entities (variations, key metrics, page targeting, audience) must include their `id` field'
      parameters:
      - in: path
        name: experienceId
        schema:
          type: string
      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
                    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: Copy from GET response. Identifies which experience to update.
                    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
                                

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