Iterable Commerce API

openapi: 3.2.0
info:
  title: Iterable Commerce API
  version: '1.0'
  description: 'Operations tagged commerce across 2 of this provider''s published API definitions: iterable-api-openapi.json, iterable-rest-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.iterable.com/
- url: https://api.iterable.com/api
  description: US Data Center (USDC)
- url: https://api.eu.iterable.com/api
  description: European Data Center (EDC)
tags:
- name: commerce
paths:
  /api/commerce/trackPurchase:
    post:
      description: Track purchase events. <code>shoppingCartItems</code> field on the user profile is cleared. User profile is also updated if it already exists (created otherwise) using the user request field. Also, note that there is a soft limit on the number of unique fields a user can have (default is 1,000). Types of data fields must match the types sent in previous requests, across all data fields in the project.<br/><br/>Learn about <a href="https://support.iterable.com/hc/articles/29156459027348">identifying users by <code>userId</code> and <code>email</code></a>.
      operationId: trackPurchase
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableApiResponse'
        '400':
          description: Invalid parameters
        '401':
          description: Invalid API key
        '409':
          description: Email/userId conflict
      summary: Track a purchase
      tags:
      - commerce
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackPurchaseRequest'
        description: purchase data
        required: true
      security:
      - api_key: []
    servers:
    - url: https://api.iterable.com/
  /api/commerce/updateCart:
    post:
      description: Update the <code>shoppingCartItems</code> field on the user profile with shopping cart items. User profile is updated if it already exists (created otherwise) via the user field. Types of data fields must match the types sent in previous requests, across all data fields in the project.<br/><br/>Learn about <a href="https://support.iterable.com/hc/articles/29156459027348">identifying users by <code>userId</code> and <code>email</code></a>.
      operationId: updateCart
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableApiResponse'
        '400':
          description: Invalid parameters
        '401':
          description: Invalid API key
        '409':
          description: Email/userId conflict
      summary: Update a user's shopping cart items
      tags:
      - commerce
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCartRequest'
        description: state of the cart
        required: true
      security:
      - api_key: []
    servers:
    - url: https://api.iterable.com/
  /commerce/trackPurchase:
    post:
      operationId: trackPurchase
      summary: Track a purchase event
      description: Tracks a purchase event for a user, including the items purchased, total value, and associated properties. Purchase data is used for revenue attribution and campaign triggering.
      tags:
      - commerce
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseRequest'
      responses:
        '200':
          description: Purchase tracked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
      - apiKeyAuth: []
    servers:
    - url: https://api.iterable.com/api
      description: US Data Center (USDC)
    - url: https://api.eu.iterable.com/api
      description: European Data Center (EDC)
  /commerce/updateCart:
    post:
      operationId: updateCart
      summary: Update a user's shopping cart
      description: Updates the shopping cart contents for a user. Cart data can be used for abandoned cart campaigns and personalization.
      tags:
      - commerce
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  type: object
                  properties:
                    email:
                      type: string
                      description: Email address of the user
                    userId:
                      type: string
                      description: UserId of the user
                items:
                  type: array
                  description: Array of cart items
                  items:
                    $ref: '#/components/schemas/CommerceItem_2'
      responses:
        '200':
          description: Cart updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IterableResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
      - apiKeyAuth: []
    servers:
    - url: https://api.iterable.com/api
      description: US Data Center (USDC)
    - url: https://api.eu.iterable.com/api
      description: European Data Center (EDC)
components:
  schemas:
    CommerceItem:
      properties:
        categories:
          description: Categories this product belongs to. It can belong to multiple categories. Each category is a breadcrumb in list form.
          items:
            type: string
          type: array
        dataFields:
          description: Additional item properties
          type: object
        description:
          type: string
        id:
          description: Unique product identifier
          type: string
        imageUrl:
          description: URL to an image of the item.
          type: string
        name:
          type: string
        price:
          format: double
          type: number
        quantity:
          format: int64
          type: integer
        sku:
          type: string
        url:
          description: URL to the item.
          type: string
      required:
      - id
      - name
      - price
      - quantity
      type: object
    UpdateCartRequest:
      properties:
        items:
          items:
            $ref: '#/components/schemas/CommerceItem'
          type: array
        user:
          $ref: '#/components/schemas/ApiUserUpdateRequest'
      required:
      - items
      - user
      type: object
    ApiUserUpdateRequest:
      properties:
        createNewFields:
          description: Whether new fields should be ingested and added to the schema. Defaults to project's setting to allow or drop unrecognized fields.
          example: false
          type: boolean
        dataFields:
          description: Data to store on the user profile identified by <code>userId</code> or <code>email</code>.
          type: object
        email:
          description: An email address that identifies a user profile in Iterable. Provide an <code>email</code> or a <code>userId</code> (but not both), depending on <a href="https://support.iterable.com/hc/articles/29156459027348">how your project identifies users</a>.
          type: string
        mergeNestedObjects:
          description: Merge top-level objects instead of overwriting them. Defaults to <code>false</code>. For example, if a user profile has data <code>{"mySettings":{"mobile":true}}</code> and the request has data <code>{"mySettings":{"email":true}}</code>, merging results in <code>{"mySettings":{"mobile":true,"email":true}}</code>.
          example: false
          type: boolean
        preferUserId:
          description: Whether or not a new user should be created if the request includes a <code>userId</code> that doesn't yet exist in the Iterable project. Defaults to <code>false</code>. Only respected in API calls for <a href="https://support.iterable.com/hc/articles/29156459027348">email-based projects</a>.
          example: false
          type: boolean
        userId:
          description: A user ID that identifies a user profile in Iterable. Provide an <code>email</code> or a <code>userId</code> (but not both), depending on <a href="https://support.iterable.com/hc/articles/29156459027348">how your project identifies users</a>.
          type: string
      type: object
    TrackPurchaseRequest:
      properties:
        campaignId:
          format: int32
          type: integer
        createdAt:
          description: Time event happened. Set to the time event was received if unspecified. Expects a Unix timestamp.
          format: int64
          type: integer
        dataFields:
          description: Additional fields to be tracked.
          type: object
        id:
          description: Optional purchase id. If a purchase exists with that id, the purchase will be updated. If none is specified, a new id will automatically be generated and returned. Note that this ID cannot be longer than 512 bytes.
          type: string
        items:
          items:
            $ref: '#/components/schemas/CommerceItem'
          type: array
        templateId:
          description: Used in AB testing attribution
          format: int32
          type: integer
        total:
          description: Total order dollar amount
          format: double
          type: number
        user:
          $ref: '#/components/schemas/ApiUserUpdateRequest'
      required:
      - items
      - total
      - user
      type: object
    IterableApiResponse:
      properties:
        code:
          enum:
          - Success
          - BadApiKey
          - BadAuthorizationHeader
          - BadJsonBody
          - BadParams
          - BatchTooLarge
          - DatabaseError
          - EmailAlreadyExists
          - ExternalKeyConflict
          - Forbidden
          - ForbiddenParamsError
          - ForgottenUserError
          - GenericError
          - InvalidEmailAddressError
          - InvalidJwtPayload
          - InvalidUserIdError
          - JwtUserIdentifiersMismatched
          - NotFound
          - QueueEmailError
          - RateLimitExceeded
          - RequestFieldsTypesMismatched
          - Unauthorized
          - UniqueFieldsLimitExceeded
          - UnknownEmailError
          - UnknownUserIdError
          - UserIdAlreadyExists
          type: string
        msg:
          description: Response description
          type: string
        params:
          description: Additional info
          type: object
      required:
      - code
      - msg
      type: object
    PurchaseRequest:
      type: object
      description: Request body for tracking a purchase event
      required:
      - user
      - items
      - total
      properties:
        user:
          type: object
          description: The user who made the purchase
          properties:
            email:
              type: string
              format: email
              description: Email address of the user
            userId:
              type: string
              description: UserId of the user
            dataFields:
              type: object
              description: Additional user data fields to update
              additionalProperties: true
        items:
          type: array
          description: Array of items purchased
          items:
            $ref: '#/components/schemas/CommerceItem_2'
        total:
          type: number
          description: Total value of the purchase
        createdAt:
          type: integer
          description: Unix timestamp of the purchase
        dataFields:
          type: object
          description: Additional purchase data fields
          additionalProperties: true
        campaignId:
          type: integer
          description: Campaign ID to attribute the purchase to
        templateId:
          type: integer
          description: Template ID to attribute the purchase to
    CommerceItem_2:
      type: object
      description: A commerce item in a purchase or cart
      required:
      - id
      - name
      - price
      - quantity
      properties:
        id:
          type: string
          description: Item ID or SKU
        sku:
          type: string
          description: Item SKU
        name:
          type: string
          description: Item name
        description:
          type: string
          description: Item description
        categories:
          type: array
          description: Item categories
          items:
            type: string
        price:
          type: number
          description: Item price
        quantity:
          type: integer
          description: Quantity purchased
        imageUrl:
          type: string
          format: uri
          description: URL of the item image
        url:
          type: string
          format: uri
          description: URL of the item page
        dataFields:
          type: object
          description: Additional item data fields
          additionalProperties: true
    IterableResponse:
      type: object
      description: Standard Iterable API response indicating success or failure
      properties:
        msg:
          type: string
          description: Human-readable response message
        code:
          type: string
          description: Response code indicating success or error type
        params:
          type: object
          description: Additional response parameters
          additionalProperties: true
  securitySchemes:
    api_key:
      in: header
      name: Api-Key
      type: apiKey
    apiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
      description: Iterable API key passed in the Api-Key header. API keys can be created and managed in the Iterable project settings.
externalDocs:
  description: Iterable API Documentation
  url: https://api.iterable.com/api/docs
x-refined-from:
- iterable-api-openapi.json
- iterable-rest-api-openapi.yml