openapi: 3.0.3
info:
  title: Smartrr Vendor Bills Subscriptions API
  description: The Smartrr Vendor API is the programmatic surface behind Smartrr, a subscription and loyalty platform for Shopify DTC brands. It lets a merchant (vendor) read and manage the subscriptions ("purchase states") their customers hold, the customers (subscribers) themselves, the orders and bills those subscriptions generate, and the subscription programs / selling plans that products are sold on. All requests are made against https://api.smartrr.com and are authenticated with a per-organization API access token generated in the Smartrr admin under the Integrations tab and sent in the x-smartrr-access-token header. This description is authored by API Evangelist from Smartrr's public OpenAPI document served at https://api.smartrr.com/docs/spec.json (rendered at https://api.smartrr.com/docs/redoc/); it is a curated subset of the full 116-operation surface covering the core Subscriptions, Subscribers, Orders, Bills, Plans, and Webhooks resources. Endpoint paths and methods are taken directly from that live specification; request and response bodies are summarized.
  version: 1.0.0
  contact:
    name: Smartrr
    url: https://smartrr.com
servers:
- url: https://api.smartrr.com
  description: Smartrr production
security:
- smartrrAccessToken: []
tags:
- name: Subscriptions
  description: Customer subscriptions, modeled by Smartrr as "purchase states". Create, read, and manage the lifecycle (skip, pause, cancel, reschedule, swap line items) of a subscription.
paths:
  /vendor/purchase-state:
    get:
      tags:
      - Subscriptions
      summary: Get Purchase States
      description: List subscriptions (purchase states) for the organization, with pagination and filtering.
      operationId: getPurchaseStates
      parameters:
      - name: pageNumber
        in: query
        schema:
          type: integer
      - name: pageSize
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: A paginated list of purchase states.
    post:
      tags:
      - Subscriptions
      summary: Create Purchase State
      description: Create a new subscription (purchase state) for a customer.
      operationId: createPurchaseState
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Purchase state creation payload (customer, line items, selling plan, next billing date).
      responses:
        '201':
          description: The created purchase state.
  /vendor/purchase-state/{shopifySubscriptionId}:
    get:
      tags:
      - Subscriptions
      summary: Get Purchase State By Shopify Subscription ID
      operationId: getPurchaseStateByShopifyId
      parameters:
      - name: shopifySubscriptionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A single purchase state.
  /vendor/purchase-state/{shopifySubscriptionId}/orders:
    get:
      tags:
      - Subscriptions
      summary: Get Orders By Shopify Subscription ID
      operationId: getPurchaseStateOrders
      parameters:
      - name: shopifySubscriptionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Orders associated with the subscription.
  /vendor/purchase-state/{shopifySubscriptionId}/bills:
    get:
      tags:
      - Subscriptions
      summary: Get Bills By Shopify Subscription ID
      operationId: getPurchaseStateBills
      parameters:
      - name: shopifySubscriptionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Bills associated with the subscription.
  /vendor/purchase-state/{shopifySubscriptionId}/events:
    get:
      tags:
      - Subscriptions
      summary: Get Events by Shopify Subscription ID
      description: Returns up to 250 most recent events for the subscription.
      operationId: getPurchaseStateEvents
      parameters:
      - name: shopifySubscriptionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Recent subscription events.
  /vendor/customer/{customerRelationshipId}/purchase-state/:
    get:
      tags:
      - Subscriptions
      summary: Get Purchase States By Customer ID
      operationId: getPurchaseStatesByCustomer
      parameters:
      - name: customerRelationshipId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The customer's purchase states.
  /vendor/customer/{customerRelationshipId}/purchase-state/{customerPurchaseStateId}/skip:
    put:
      tags:
      - Subscriptions
      summary: Skip Purchase
      description: Skip the next order on a subscription.
      operationId: skipPurchase
      parameters:
      - name: customerRelationshipId
        in: path
        required: true
        schema:
          type: string
      - name: customerPurchaseStateId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The updated purchase state.
  /vendor/customer/{customerRelationshipId}/purchase-state/{customerPurchaseStateId}/unskip:
    put:
      tags:
      - Subscriptions
      summary: Unskip Purchase
      operationId: unskipPurchase
      parameters:
      - name: customerRelationshipId
        in: path
        required: true
        schema:
          type: string
      - name: customerPurchaseStateId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The updated purchase state.
  /vendor/customer/{customerRelationshipId}/purchase-state/{customerPurchaseStateId}/pause:
    put:
      tags:
      - Subscriptions
      summary: Pause Purchase
      operationId: pausePurchase
      parameters:
      - name: customerRelationshipId
        in: path
        required: true
        schema:
          type: string
      - name: customerPurchaseStateId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                unpauseDate:
                  type: string
                  description: Optional date to automatically resume the subscription.
      responses:
        '200':
          description: The updated purchase state.
  /vendor/customer/{customerRelationshipId}/purchase-state/{customerPurchaseStateId}/activate:
    put:
      tags:
      - Subscriptions
      summary: Activate Purchase
      description: Resume / activate a paused subscription.
      operationId: activatePurchase
      parameters:
      - name: customerRelationshipId
        in: path
        required: true
        schema:
          type: string
      - name: customerPurchaseStateId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The updated purchase state.
  /vendor/customer/{customerRelationshipId}/purchase-state/{customerPurchaseStateId}/cancel:
    put:
      tags:
      - Subscriptions
      summary: Cancel Purchase
      operationId: cancelPurchase
      parameters:
      - name: customerRelationshipId
        in: path
        required: true
        schema:
          type: string
      - name: customerPurchaseStateId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The cancelled purchase state.
  /vendor/customer/{customerRelationshipId}/purchase-state/{customerPurchaseStateId}/next-billing-date:
    put:
      tags:
      - Subscriptions
      summary: Set Next Billing Date on Purchase
      operationId: setNextBillingDate
      parameters:
      - name: customerRelationshipId
        in: path
        required: true
        schema:
          type: string
      - name: customerPurchaseStateId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The updated purchase state.
  /vendor/customer/{customerRelationshipId}/purchase-state/{customerPurchaseStateId}/selling-plan:
    put:
      tags:
      - Subscriptions
      summary: Set Selling Plan on Purchase
      description: Change the selling plan (cadence / terms) a subscription is on.
      operationId: setSellingPlanOnPurchase
      parameters:
      - name: customerRelationshipId
        in: path
        required: true
        schema:
          type: string
      - name: customerPurchaseStateId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The updated purchase state.
  /vendor/customer/{customerRelationshipId}/purchase-state/{customerPurchaseStateId}/line-item:
    post:
      tags:
      - Subscriptions
      summary: Add Line Item to Purchase
      operationId: addLineItem
      parameters:
      - name: customerRelationshipId
        in: path
        required: true
        schema:
          type: string
      - name: customerPurchaseStateId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The updated purchase state.
  /vendor/customer/purchase-state/bulk-cancel:
    put:
      tags:
      - Subscriptions
      summary: Bulk Cancel Purchases
      operationId: bulkCancelPurchases
      responses:
        '200':
          description: Bulk cancel result.
  /vendor/customer/purchase-state/bulk-pause:
    put:
      tags:
      - Subscriptions
      summary: Bulk Pause Purchases
      operationId: bulkPausePurchases
      responses:
        '200':
          description: Bulk pause result.
components:
  securitySchemes:
    smartrrAccessToken:
      type: apiKey
      in: header
      name: x-smartrr-access-token
      description: Per-organization API access token generated in the Smartrr admin under the Integrations tab (Add Key). Sent on every request in the x-smartrr-access-token header.