Smile.io Customers API

# Smile.io REST API - grounded on the published spec at https://dev.smile.io/schemas/rest-api.json
openapi: 3.1.0
info:
  title: Smile.io REST API
  description: A RESTful interface for interacting with Smile.io loyalty programs - customers and customer
    identities, points transactions and settings, points products and purchases, earning rules, rewards
    and reward fulfillments, VIP tiers, and activities. Resource-oriented URLs return JSON and use standard
    HTTP status codes. Authenticated with an HTTP Bearer token (a merchant API key, or an app OAuth access
    token). REST API access is available on the Plus and Enterprise plans.
  version: 1.0.0
  contact:
    name: Smile.io Developer Support
    url: https://dev.smile.io
  license:
    name: Proprietary
    url: https://smile.io/terms-of-service
servers:
- url: https://api.smile.io/v1
  description: Smile.io REST API
paths:
  /activities:
    post:
      summary: Create an activity
      operationId: post__activities
      tags:
      - Activities
      responses:
        '201':
          description: The activity was successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  activity:
                    $ref: '#/components/schemas/Activity'
      description: Creates a record of a customer having performed a given action.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                activity:
                  type: object
                  properties:
                    token:
                      type: string
                      description: A token identifying the activity that was performed.
                      example: activity_f57a9b5a8d0ac5
                    distinct_id:
                      type: string
                      description: A unique identifier for the activity in the external system (e.g. the
                        order number).
                      example: '212993'
                    created_on_origin_at:
                      type: string
                      description: The date and time the activity was performed by the customer in the
                        external system (e.g. when the action actually occurred, which is often earlier
                        than when the activity is created in Smile).
                      format: date-time
                      example: '2024-04-04T15:10:42.030Z'
                  required:
                  - token
                  oneOf:
                  - title: With customer ID
                    properties:
                      customer_id:
                        type: integer
                        example: 304169228
                        description: The ID of the customer who performed the activity. Required if `customer_email`
                          is not provided.
                    required:
                    - customer_id
                  - title: With customer email
                    properties:
                      customer_email:
                        type: string
                        example: jane@doe.com
                        description: The email of the customer who performed the activity. Required if
                          `customer_id` is not provided.
                        format: email
                    required:
                    - customer_email
              required:
              - activity
  /earning_rules:
    get:
      summary: List earning rules
      operationId: get__earning_rules
      tags:
      - Earning Rules
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  earning_rules:
                    type: array
                    items:
                      $ref: '#/components/schemas/EarningRule'
                  metadata:
                    $ref: '#/components/schemas/PaginationMetadata'
      description: Retrieves a list of enabled earning rules.
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          description: The maximum number of earning rules to retrieve.
          minimum: 1
          maximum: 250
          default: 50
        description: The maximum number of earning rules to retrieve.
      - name: cursor
        in: query
        required: false
        schema:
          type: string
          description: Cursor for the page of earning rules to retrieve.
        description: Cursor for the page of earning rules to retrieve.
  /reward_fulfillments:
    get:
      summary: List reward fulfillments
      operationId: get__reward_fulfillments
      tags:
      - Reward Fulfillments
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  reward_fulfillments:
                    type: array
                    items:
                      $ref: '#/components/schemas/RewardFulfillment'
                  metadata:
                    $ref: '#/components/schemas/PaginationMetadata'
      description: Retrieves a list of reward fulfillments.
      parameters:
      - name: customer_id
        in: query
        required: false
        schema:
          type: integer
          description: Filter results to only reward fulfillments with the provided Smile customer ID.
        description: Filter results to only reward fulfillments with the provided Smile customer ID.
      - name: fulfillment_status
        in: query
        required: false
        schema:
          type: string
          description: Filter results to only reward fulfillments whose fulfillment status matches the
            provided value.
          enum:
          - pending
          - issued
          - cancelled
          - failed
        description: Filter results to only reward fulfillments whose fulfillment status matches the provided
          value.
      - name: usage_status
        in: query
        required: false
        schema:
          type: string
          description: Filter results to only reward fulfillments whose usage status matches the provided
            values.
          enum:
          - used
          - unused
          - untracked
        description: Filter results to only reward fulfillments whose usage status matches the provided
          values.
      - name: updated_at_min
        in: query
        required: false
        schema:
          type: string
          description: Filter results to only reward fulfillments updated after the provided date and
            time.
          format: date-time
        description: Filter results to only reward fulfillments updated after the provided date and time.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          description: The maximum number of reward fulfillments to retrieve.
          example: 1
          minimum: 1
          maximum: 250
          default: 50
        description: The maximum number of reward fulfillments to retrieve.
      - name: cursor
        in: query
        required: false
        schema:
          type: string
          description: Cursor for the page of reward fulfillments to retrieve.
        description: Cursor for the page of reward fulfillments to retrieve.
  /customer_identities/create_or_update:
    post:
      summary: Create or update a customer identity
      operationId: post__customer_identities_create_or_update
      tags:
      - Customer Identities
      responses:
        '200':
          description: Customer identity successfully updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  customer_identity:
                    $ref: '#/components/schemas/CustomerIdentity'
        '201':
          description: Customer identity successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  customer_identity:
                    $ref: '#/components/schemas/CustomerIdentity'
      description: Creates a new customer identity or updates an existing one.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_identity:
                  type: object
                  properties:
                    first_name:
                      type: string
                      description: The first name of the customer in the external system.
                      example: Jane
                    last_name:
                      type: string
                      description: The last name of the customer in the external system.
                      example: Doe
                    email:
                      type: string
                      description: The email of the customer in the external system.
                      format: email
                      example: jane@doe.com
                    distinct_id:
                      type: string
                      description: The unique identifier for the customer in the external system.
                      example: cust_19238475
                    properties:
                      type: object
                      description: A restricted hash of additional attributes for the customer identity.
                        Keys are allowlisted on a per-integration basis.
                  required:
                  - email
                  - distinct_id
              required:
              - customer_identity
  /points_products/{id}/purchase:
    post:
      summary: Purchase a points product
      operationId: post__points_products_id_purchase
      tags:
      - Points Products
      responses:
        '201':
          description: The points product was successfully purchased.
          content:
            application/json:
              schema:
                type: object
                properties:
                  points_purchase:
                    $ref: '#/components/schemas/PointsPurchase'
      description: Exchanges a customer's points for a reward by purchasing a points product.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          description: ID of the points product to purchase.
          example: 132456921
        description: ID of the points product to purchase.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_id:
                  type: integer
                  description: ID of the customer who is purchasing the points product.
                  example: 304169228
                points_to_spend:
                  type: integer
                  description: The number of points that will be spent on behalf of the customer. Only
                    applies when purchasing a points product whose `exchange_type` is `variable`, otherwise
                    should be left blank.
                  example: 500
              required:
              - customer_id
  /points_products:
    get:
      summary: List points products
      operationId: get__points_products
      tags:
      - Points Products
      responses:
        '200':
          description: The points products were successfully retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  points_products:
                    type: array
                    items:
                      $ref: '#/components/schemas/PointsProduct'
      description: Retrieves a list of points products based on the specified filters.
      parameters:
      - name: exchange_type
        in: query
        required: false
        schema:
          type: string
          description: Filter results to only points products with the provided `exchange_type`.
          enum:
          - fixed
          - variable
          example: variable
        description: Filter results to only points products with the provided `exchange_type`.
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          description: The maximum number of points products to retrieve.
          minimum: 1
          maximum: 250
          default: 50
        description: The maximum number of points products to retrieve.
      - name: page
        in: query
        required: false
        schema:
          type: integer
          description: The page of points products to retrieve.
          default: 1
        description: The page of points products to retrieve.
  /points_products/{id}:
    get:
      summary: Retrieve a points product
      operationId: get__points_products_id
      tags:
      - Points Products
      responses:
        '200':
          description: The points product was successfully retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  points_product:
                    $ref: '#/components/schemas/PointsProduct'
      description: Retrieves a single points product by ID.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          description: ID of the points product to retrieve.
        description: ID of the points product to retrieve.
  /points_transactions:
    post:
      summary: Create a points transaction
      operationId: post__points_transactions
      tags:
      - Points Transactions
      responses:
        '201':
          description: The points transaction was successfully created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  points_transaction:
                    $ref: '#/components/schemas/PointsTransaction'
      description: Add or remove points from a customer's points balance by creating a points transaction.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                points_transaction:
                  type: object
                  properties:
                    customer_id:
                      type: integer
                      description: The ID of the customer whose balance this points transaction applies
                        to.
                      example: 304169228
                    points_change:
                      type: integer
                      description: The number of points added or removed from the customer's points balance.
                        The value is positive if points were added to the customer's balance and negative
                        if points were deducted.
                      example: 100
                    description:
                      type: string
                      description: A message visible to the customer that describes the reason for the
                        points change.
                      example: Points correction
                    internal_note:
                      type: string
                      description: A note that is visible to the merchant. This note should never be visible
                        to customers.
                      example: 'Due to issue with order #6834'
                  required:
                  - customer_id
                  - points_change
              required:
              - points_transaction
    get:
      summary: List points transactions
      operationId: get__points_transactions
      tags:
      - Points Transactions
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  points_transactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/PointsTransaction'
                  metadata:
                    $ref: '#/components/schemas/PaginationMetadata'
      description: Retrieves a list of points transactions.
      parameters:
      - name: customer_id
        in: query
        required: false
        schema:
          type: integer
          description: Filter results to only points transactions with the provided Smile customer ID.
        description: Filter results to only points transactions with the provided Smile customer ID.
      - name: updated_at_min
        in: query
        required: false
        schema:
          type: string
          description: Filter results to only points transactions updated at or after the provided date
            and time.
          format: date-time
        description: Filter results to only points transactions updated at or after the provided date
          and time.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          description: The maximum number of points transactions to retrieve.
          example: 1
          minimum: 1
          maximum: 250
          default: 50
        description: The maximum number of points transactions to retrieve.
      - name: cursor
        in: query
        required: false
        schema:
          type: string
          description: Cursor for the page of points transactions to retrieve.
        description: Cursor for the page of points transactions to retrieve.
  /points_transactions/{id}:
    get:
      summary: Retrieve a points transaction
      operationId: get__points_transactions_id
      tags:
      - Points Transactions
      responses:
        '200':
          description: The points transaction was successfully retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  points_transaction:
                    $ref: '#/components/schemas/PointsTransaction'
      description: Retrieves a single points transaction by ID.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          description: ID of the points transaction to retrieve.
        description: ID of the points transaction to retrieve.
  /vip_tiers:
    get:
      summary: List VIP tiers
      operationId: get__vip_tiers
      tags:
      - VIP Tiers
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  vip_tiers:
                    type: array
                    items:
                      $ref: '#/components/schemas/VipTier'
      description: Retrieves a list of VIP tiers.
      parameters:
      - name: include
        in: query
        required: false
        schema:
          type: string
          description: A comma-separated list of nested objects to include in the response.
          enum:
          - perks
          - entry_rewards
        description: A comma-separated list of nested objects to include in the response.
  /points_settings:
    get:
      summary: Get points settings
      operationId: get__points_settings
      tags:
      - Points Settings
      responses:
        '200':
          description: The points settings were successfully retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  points_settings:
                    $ref: '#/components/schemas/PointsSettings'
      description: Retrieves the configuration for the account's points program.
  /customers/{id}:
    get:
      summary: Retrieve a customer
      operationId: get__customers_id
      tags:
      - Customers
      responses:
        '200':
          description: The customer was successfully retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  customer:
                    $ref: '#/components/schemas/Customer'
      description: Retrieves a single customer by ID.
      parameters:
      - name: include
        in: query
        required: false
        schema:
          type: string
          description: A comma-separated list of related objects to include in the response.
          enum:
          - vip_status
          - vip_status.vip_tier
          - vip_status.next_vip_tier
        description: A comma-separated list of related objects to include in the response.
      - name: id
        in: path
        required: true
        schema:
          type: integer
          description: ID of the customer (in Smile) to retrieve.
        description: ID of the customer (in Smile) to retrieve.
  /customers:
    get:
      summary: List customers
      operationId: get__customers
      tags:
      - Customers
      responses:
        '200':
          description: The customers were successfully retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  customers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                  metadata:
                    $ref: '#/components/schemas/PaginationMetadata'
      description: Retrieves a list of customers based on a set of provided filters.
      parameters:
      - name: email
        in: query
        required: false
        schema:
          type: string
          description: Filter results to only customers with the provided email address.
        description: Filter results to only customers with the provided email address.
      - name: state
        in: query
        required: false
        schema:
          type: string
          description: Filter results to only customers with the provided state.
          enum:
          - candidate
          - member
          - disabled
        description: Filter results to only customers with the provided state.
      - name: updated_at_min
        in: query
        required: false
        schema:
          type: string
          description: Filter results to only customers updated after the provided date and time.
          format: date-time
          example: '2024-04-04T15:10:42.030Z'
        description: Filter results to only customers updated after the provided date and time.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          description: The maximum number of customers to retrieve.
          example: 1
          minimum: 1
          maximum: 250
          default: 50
        description: The maximum number of customers to retrieve.
      - name: cursor
        in: query
        required: false
        schema:
          type: string
          description: Cursor for the page of customers to retrieve.
        description: Cursor for the page of customers to retrieve.
      - name: include
        in: query
        required: false
        schema:
          type: string
          description: A comma-separated list of related objects to include in the response.
          enum:
          - vip_status
        description: A comma-separated list of related objects to include in the response.
components:
  schemas:
    PaginationMetadata:
      type: object
      properties:
        next_cursor:
          type:
          - string
          - 'null'
          example: aWQ6MixkaXJlY3Rpb246bmV4dA==
          description: A cursor value that when present, can be used to retrieve the next page of results.
        previous_cursor:
          type:
          - string
          - 'null'
          example: ''
          description: A cursor value that when present, can be used to retrieve the previous page of
            results.
    Customer:
      type: object
      properties:
        id:
          type: integer
          example: 304169228
          description: Unique identifier for the customer in Smile.
        first_name:
          type:
          - string
          - 'null'
          example: Jane
          description: The customer's first name.
        last_name:
          type:
          - string
          - 'null'
          example: Doe
          description: The customer's last name.
        email:
          type: string
          example: jane@doe.com
          description: The customer's email address.
        state:
          type: string
          enum:
          - candidate
          - member
          - disabled
          example: member
          description: The customer's state in the loyalty program.
        date_of_birth:
          type:
          - string
          - 'null'
          format: date
          example: '1004-05-27'
          description: The customer's birthday. A year value of `1004` means only the customer's birth
            day and month was entered.
        points_balance:
          type: integer
          example: 300
          description: The customer's current points balance.
        referral_url:
          type: string
          example: http://i.refs.cc/9qr5Pw
          description: The customer's unique referral URL. Used to share with friends as part of the referral
            program.
        vip_tier_id:
          type:
          - integer
          - 'null'
          example: 426715794
          deprecated: true
          description: The ID of the customer's current VIP tier. This field is now deprecated, use the
            nested `vip_status.vip_tier_id` instead.
        vip_status:
          type: object
          properties:
            vip_tier_id:
              type:
              - integer
              - 'null'
              example: 426715794
              description: The ID of the customer's current VIP tier.
            vip_tier_expires_at:
              type:
              - string
              - 'null'
              format: date-time
              example: '2026-12-31T23:59:59.999Z'
              description: The date the customer's current VIP tier expires. For all-time VIP programs,
                this will be `null` because tiers do not expire.
            progress_value:
              type:
              - number
              - 'null'
              format: float
              example: 300
              description: The amount the customer has already spent or earned within the current VIP
                period.
            current_vip_period_end:
              type:
              - string
              - 'null'
              format: date-time
              example: '2025-12-31T23:59:59.999Z'
              description: The end date for the current VIP period. For calendar-year VIP programs, this
                will be the end of the current calendar year. For all-time VIP programs, this will be
                `null`.
            delta_to_retain_vip_tier:
              type:
              - number
              - 'null'
              format: float
              description: The additional amount the customer must spend or earn before the end of the
                current VIP period to retain their VIP tier until the end of the next VIP period. For
                all-time VIP programs or if the customer has already spent or earned enough this period
                to retain their current VIP tier, this will be `null`.
            next_vip_tier_id:
              type:
              - integer
              - 'null'
              example: 426715799
              description: The ID of the next VIP tier that the customer will move into if they meet the
                minimum spending or earning requirement. If the customer is already in the highest tier,
                this will be `null`.
            delta_to_next_vip_tier:
              type:
              - number
              - 'null'
              format: float
              example: 200
              description: The amount the customer must spend or earn within the current VIP period to
                reach the next VIP tier. If the customer is already in the highest tier, this will be
                `null`.
          description: An object containing details about the customer's status within the VIP program.
        created_at:
          type: string
          format: date-time
          example: '2024-04-04T15:10:42.030Z'
          description: The date and time when the customer was created.
        updated_at:
          type: string
          format: date-time
          example: '2025-04-04T15:10:42.030Z'
          description: The date and time when the customer was last updated.
    VipTier:
      type: object
      properties:
        id:
          type: integer
          example: 426715799
          description: Unique identifier for the VIP tier.
        name:
          type: string
          example: Gold
          description: The display name of the VIP tier.
        image_url:
          type: string
          example: https://platform.smile.io/v1/images/vip_tiers/vip-tier-3.svg
          description: The image of the VIP tier.
        milestone:
          type: number
          format: float
          example: 500
          description: The threshold that a customer must reach to be eligible for the VIP tier. Represents
            either an amount of points or a dollar amount, depending on the loyalty program's configuration.
        perks:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                example: Early access to new product releases
                description: A description of the benefit.
          description: A set of nested objects representing the ongoing benefits a customer is entitled
            to when they are in the VIP tier.
        entry_rewards:
          type: array
          items:
            $ref: '#/components/schemas/Reward'
          description: A set of nested Reward objects representing the rewards that are issued to a customer
            when they enter the VIP tier.
    PointsTransaction:
      type: object
      properties:
        id:
          type: integer
          example: 825673452
          description: Unique identifier for the points transaction.
        customer_id:
          type: integer
          example: 304169228
          description: The ID of the customer whose balance this points transaction applies to.
        points_change:
          type: integer
          example: 100
          description: The number of points added or removed from the customer's points balance. The value
            is positive if points were added to the customer's balance and negative if points were deducted.
        description:
          type: string
          example: Points correction
          description: A message visible to the customer that describes the reason for the points change.
        internal_note:
          type:
          - string
          - 'null'
          example: 'Due to issue with order #6834'
          description: A note that is visible to the merchant. This note should never be visible to customers.
        created_at:
          type: string
          format: date-time
          example: '2024-12-07T20:15:27.893Z'
          description: The date and time when the points transaction was created.
        updated_at:
          type: string
          format: date-time
          example: '2024-12-07T20:15:27.893Z'
          description: The date and time when the points transaction was last updated.
    PointsProduct:
      type: object
      properties:
        id:
          type: integer
          example: 132456921
          description: Unique identifier for the points product.
        exchange_type:
          type: string
          enum:
          - fixed
          - variable
          example: variable
          description: How points are exchanged for the reward.
        exchange_description:
          type: string
          example: 100 Points = $1 off
          description: A human readable description of how a custome

# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smile-io/refs/heads/main/openapi/smile-io-openapi.yml