openapi: 3.1.0
info:
  title: Smile.io REST Activities Reward Fulfillments 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
security:
- bearerAuth: []
tags:
- name: Reward Fulfillments
  description: Fulfillment records for rewards a customer has redeemed.
paths:
  /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.
components:
  schemas:
    RewardFulfillment:
      type: object
      properties:
        id:
          type: integer
          example: 625478984
          description: Unique identifier for the reward fulfillment.
        name:
          type: string
          example: $5 off coupon
          description: The name of the reward fulfillment.
        code:
          type: string
          example: 5off-e26d02e39149
          description: A unique code for the customer to use or apply the reward fulfillment. This is commonly a discount code the customer applies at checkout on their next order, but it can be a unique code they use for other purposes like accessing an exclusive page on the merchant's website.
        customer_id:
          type: integer
          example: 304169228
          description: The ID of the customer that the reward fulfillment belongs to.
        fulfillment_status:
          type: string
          enum:
          - pending
          - issued
          - cancelled
          - failed
          example: issued
          description: The fulfillment status of the reward fulfillment, indicating whether the reward is available to the customer.
        image_url:
          type: string
          example: https://platform-images.smilecdn.co/9283449.png
          description: An image for the reward fulfillment.
        action_text:
          type:
          - string
          - 'null'
          description: A short call-to-action style text, appropriate for use in buttons or links, guiding the customer on how to use the reward fulfillment. This field may be blank
        action_url:
          type:
          - string
          - 'null'
          description: A URL destination guiding the customer on how to use the reward, often paired with the `action_text` for use in buttons or links. This field may be blank.
        usage_instructions:
          type:
          - string
          - 'null'
          example: Use this discount code on your next order!
          description: A description of how the customer can use or apply the reward fulfillment.
        terms_and_conditions:
          type:
          - string
          - 'null'
          example: Reward expires on June 7, 2025. Reward can only be used on purchase of $50 or more. Reward can only be used on select product collections.
          description: A description of the reward fulfillment's limitations or restrictions. When the reward is a discount code, this commonly includes expiry date, minimum order amounts, or applicability to specific product collections.
        expires_at:
          type:
          - string
          - 'null'
          format: date-time
          example: '2025-06-07T23:59:59.999Z'
          description: The date and time when the reward fulfillment expires. When the reward is a discount code, this refers to the expiry date of the discount, and a `null` value indicates that the discount code does not expire.
        usage_status:
          type: string
          enum:
          - used
          - unused
          - untracked
          example: unused
          description: The usage status of the reward fulfillment, indicating whether the generated reward has been used by the customer.
        used_at:
          type:
          - string
          - 'null'
          format: date-time
          description: The date and time when the reward fulfillment was used by the customer. If the reward fulfillments does not support usage tracking, this field may be `null` even after the reward fulfillment has been used.
        created_at:
          type: string
          format: date-time
          example: '2024-12-07T20:15:27.893Z'
          description: The date and time when the reward fulfillment was created.
        updated_at:
          type: string
          format: date-time
          example: '2024-12-07T20:15:27.893Z'
          description: The date and time when the reward fulfillment was last updated.
    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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer