openapi: 3.1.0
info:
  title: Stay AI API
  version: '2.0'
  description: >-
    Documented public REST API for Stay AI (formerly Retextion), a subscription
    retention and growth platform for Shopify DTC brands. All endpoints are
    authenticated with an API key sent in the X-RETEXTION-ACCESS-TOKEN header.
    Paths, methods, and query/path parameters are taken from the Stay AI
    developer documentation at https://docs.stay.ai; request and response body
    schemas are simplified representations - consult the live reference for full
    payload details.
  contact:
    name: Stay AI
    url: https://docs.stay.ai
servers:
- url: https://api.retextion.com/api/v2
components:
  securitySchemes:
    accessToken:
      type: apiKey
      in: header
      name: X-RETEXTION-ACCESS-TOKEN
  schemas:
    Success:
      type: object
      properties:
        success:
          type: boolean
security:
- accessToken: []
paths:
  /subscriptions:
    get:
      operationId: query-all-subscriptions
      summary: Query All Subscriptions
      tags:
      - Subscriptions
      parameters:
      - name: email
        in: query
        description: Customer email
        schema:
          type: string
      - name: status
        in: query
        description: Subscription status (ACTIVE or PAUSED or CANCELLED)
        schema:
          type: string
      - name: createdAtMin
        in: query
        description: Created date min timestamp
        schema:
          type: integer
          format: int64
      - name: createdAtMax
        in: query
        description: Created date max timestamp
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: A list of subscriptions
  /subscriptions/{subscriptionId}:
    get:
      operationId: query-subscription-by-id
      summary: Query Subscription by ID
      tags:
      - Subscriptions
      parameters:
      - name: subscriptionId
        in: path
        required: true
        description: Internal or external subscription ID
        schema:
          type: string
      responses:
        '200':
          description: The requested subscription
  /subscriptions/{subscriptionId}/cancel:
    post:
      operationId: cancel-subscription
      summary: Cancel Subscription
      tags:
      - Subscriptions
      parameters:
      - name: subscriptionId
        in: path
        required: true
        description: Internal or external subscription ID
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                cancellationReasons:
                  type: array
                  description: A list of reasons for cancellation of the subscription
                  items:
                    type: string
      responses:
        '200':
          description: Cancellation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
  /subscriptions/{subscriptionId}/change-frequency:
    post:
      operationId: change-frequency
      summary: Change Frequency
      tags:
      - Subscriptions
      parameters:
      - name: subscriptionId
        in: path
        required: true
        description: Internal or external subscription ID
        schema:
          type: string
      responses:
        '200':
          description: Frequency updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
  /subscriptions/{subscriptionId}/get-order-now:
    post:
      operationId: create-subscription-order
      summary: Create Subscription Order
      description: Initiates a new recurring charge for a single subscription.
      tags:
      - Orders
      parameters:
      - name: subscriptionId
        in: path
        required: true
        description: Internal or external subscription ID
        schema:
          type: string
      responses:
        '200':
          description: Order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
  /subscriptions/{subscriptionId}/lines/{lineId}:
    put:
      operationId: update-line
      summary: Update Line
      tags:
      - Subscriptions
      parameters:
      - name: subscriptionId
        in: path
        required: true
        schema:
          type: string
      - name: lineId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Line item updated
  /subscriptions/{subscriptionId}/remove-lines:
    post:
      operationId: remove-lines
      summary: Remove Lines
      tags:
      - Subscriptions
      parameters:
      - name: subscriptionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Line items removed
  /subscriptions/{subscriptionId}/order-notes:
    put:
      operationId: update-order-notes
      summary: Update Order Notes
      tags:
      - Subscriptions
      parameters:
      - name: subscriptionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Order notes updated
  /subscriptions/{subscriptionId}/meta-data:
    post:
      operationId: add-meta-data
      summary: Add Meta Data Field
      tags:
      - Subscriptions
      parameters:
      - name: subscriptionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Metadata field added
  /subscriptions/{subscriptionId}/set-shipping-address:
    post:
      operationId: set-shipping-address
      summary: Set Shipping Address
      tags:
      - Subscriptions
      parameters:
      - name: subscriptionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Shipping address updated
  /subscriptions/generate-portal-link:
    post:
      operationId: generate-portal-link
      summary: Generate Portal Link
      tags:
      - Customer Portal
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: Customer email address
                phone:
                  type: string
                  description: Customer phone number
      responses:
        '200':
          description: A customer portal link
  /orders:
    get:
      operationId: query-orders
      summary: Query Orders
      tags:
      - Orders
      parameters:
      - name: createdAtMin
        in: query
        description: Created date min timestamp
        schema:
          type: integer
          format: int64
      - name: createdAtMax
        in: query
        description: Created date max timestamp
        schema:
          type: integer
          format: int64
      - name: updatedAtMin
        in: query
        description: Updated date min timestamp
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: A list of recurring orders
  /selling-plan-groups:
    get:
      operationId: query-selling-plan-groups
      summary: Query Selling Plan Groups
      tags:
      - Selling Plans
      responses:
        '200':
          description: A list of selling plan groups
    post:
      operationId: create-selling-plan-group
      summary: Create Selling Plan Group
      tags:
      - Selling Plans
      responses:
        '200':
          description: Selling plan group created
  /selling-plan-groups/{sellingPlanGroupId}:
    get:
      operationId: query-selling-plan-group-by-id
      summary: Query Selling Plan Group by ID
      tags:
      - Selling Plans
      parameters:
      - name: sellingPlanGroupId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested selling plan group
    put:
      operationId: update-selling-plan-group
      summary: Update Selling Plan Group
      tags:
      - Selling Plans
      parameters:
      - name: sellingPlanGroupId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Selling plan group updated
  /products/catalog:
    get:
      operationId: get-catalog
      summary: Query Entire Catalog
      description: Retrieve the details for the products in your catalog.
      tags:
      - Catalog
      responses:
        '200':
          description: The product catalog
  /products/{productId}:
    get:
      operationId: get-catalog-product-by-id
      summary: Query Product in Catalog
      description: Retrieve details for a specific product and its variants from your catalog.
      tags:
      - Catalog
      parameters:
      - name: productId
        in: path
        required: true
        description: Shopify Product ID
        schema:
          type: string
      responses:
        '200':
          description: The requested product and its variants
  /settings:
    get:
      operationId: query-account-settings
      summary: Query Account Settings
      tags:
      - Account
      responses:
        '200':
          description: Merchant account settings
  /data/export:
    post:
      operationId: export-data
      summary: Export Data
      description: Trigger a bulk data export for subscriptions and orders.
      tags:
      - Data Export
      responses:
        '200':
          description: Export job accepted
  /webhooks:
    get:
      operationId: get-webhook-subscriptions
      summary: Get Webhook Subscriptions
      tags:
      - Webhooks
      responses:
        '200':
          description: A list of webhook subscriptions
    post:
      operationId: create-webhook-subscription
      summary: Create Webhook Subscription
      tags:
      - Webhooks
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - event
              - url
              properties:
                event:
                  type: string
                  description: >-
                    Event type to subscribe to, e.g. SUBSCRIPTION,
                    FAILED_PAYMENT, SUCCESSFUL_PAYMENT.
                url:
                  type: string
                  description: Destination URL for webhook delivery
      responses:
        '200':
          description: Webhook subscription created
  /webhooks/{webhookId}:
    delete:
      operationId: delete-webhook-subscription
      summary: Delete Webhook Subscription
      tags:
      - Webhooks
      parameters:
      - name: webhookId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Webhook subscription deleted