openapi: 3.0.3
info:
  title: Smartrr Vendor 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.
  - name: Subscribers
    description: >-
      Customer relationships (subscribers) - the Shopify customers who hold
      subscriptions, their payment methods, loyalty points, and referral links.
  - name: Orders
    description: Orders generated by subscriptions.
  - name: Bills
    description: Recurring bills (subscription transactions) and their retry / cancel lifecycle.
  - name: Plans
    description: >-
      Purchasables, selling plans, selling plan groups and subscription
      programs - the products and the terms they are sold on.
  - name: Webhooks
    description: Register endpoints to receive Smartrr event notifications.
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.
  /vendor/customer-relationship:
    get:
      tags: [Subscribers]
      summary: Get Customer Relationship
      description: List subscribers (customer relationships) for the organization.
      operationId: getCustomerRelationships
      responses:
        '200':
          description: A paginated list of customer relationships.
  /vendor/customer-relationship/{customerShopifyId}:
    get:
      tags: [Subscribers]
      summary: Get Customer Relationship by Shopify ID
      operationId: getCustomerRelationshipByShopifyId
      parameters:
        - name: customerShopifyId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: A single customer relationship.
  /vendor/customer-relationship/{customerRelationshipId}/payment-methods:
    get:
      tags: [Subscribers]
      summary: Get Payment methods
      operationId: getPaymentMethods
      parameters:
        - name: customerRelationshipId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The customer's payment methods.
  /vendor/customer-relationship/{customerShopifyId}/referral-link:
    get:
      tags: [Subscribers]
      summary: Get customer referral code and link
      operationId: getReferralLink
      parameters:
        - name: customerShopifyId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The customer's referral code and link.
  /vendor/customer-relationship/{customerRelationshipId}/orgPoints:
    put:
      tags: [Subscribers]
      summary: Add loyalty points to customer
      operationId: addLoyaltyPoints
      parameters:
        - name: customerRelationshipId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The updated loyalty points balance.
  /vendor/customer-relationship/import:
    post:
      tags: [Subscribers]
      summary: Import Customer Relationship from Shopify Customer
      operationId: importCustomerRelationship
      responses:
        '200':
          description: The imported customer relationship.
  /vendor/customer/{custRelId}/orders:
    get:
      tags: [Subscribers]
      summary: Get Orders by customer ID
      operationId: getOrdersByCustomer
      parameters:
        - name: custRelId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Orders for the customer.
  /vendor/order:
    get:
      tags: [Orders]
      summary: Get Orders
      operationId: getOrders
      parameters:
        - name: pageNumber
          in: query
          schema: { type: integer }
        - name: pageSize
          in: query
          schema: { type: integer }
      responses:
        '200':
          description: A paginated list of orders.
  /vendor/order/formatted:
    get:
      tags: [Orders]
      summary: Get Formatted Orders
      operationId: getFormattedOrders
      responses:
        '200':
          description: Formatted orders.
  /vendor/orders/{shopifyId}:
    get:
      tags: [Orders]
      summary: Get Order by Shopify order ID
      operationId: getOrderByShopifyId
      parameters:
        - name: shopifyId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: A single order.
  /vendor/order/{orderId}/open:
    post:
      tags: [Orders]
      summary: Open Order
      operationId: openOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The opened order.
  /vendor/order/{orderId}:
    delete:
      tags: [Orders]
      summary: Close Order
      operationId: closeOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The closed order.
  /vendor/bill:
    get:
      tags: [Bills]
      summary: Get Bills
      operationId: getBills
      responses:
        '200':
          description: A paginated list of bills (subscription transactions).
  /vendor/bill/{billId}/history:
    get:
      tags: [Bills]
      summary: Gets bill audit history
      operationId: getBillHistory
      parameters:
        - name: billId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The bill's audit history.
  /vendor/bill/{billId}/retry:
    post:
      tags: [Bills]
      summary: Retry a bill
      operationId: retryBill
      parameters:
        - name: billId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The retried bill.
  /vendor/bill/{billId}/cancel:
    post:
      tags: [Bills]
      summary: Cancels a bill
      operationId: cancelBill
      parameters:
        - name: billId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The cancelled bill.
  /vendor/purchasable:
    get:
      tags: [Plans]
      summary: Get Purchasables
      description: List purchasable products available for subscription.
      operationId: getPurchasables
      responses:
        '200':
          description: A list of purchasables.
    put:
      tags: [Plans]
      summary: Update Purchasable
      operationId: updatePurchasable
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                purchasable:
                  type: object
      responses:
        '200':
          description: The updated purchasable.
  /vendor/purchasable/{id}:
    get:
      tags: [Plans]
      summary: Get Purchasable by ID
      operationId: getPurchasableById
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: A single purchasable.
  /vendor/purchasable-collection:
    get:
      tags: [Plans]
      summary: Get Purchasable Collection
      operationId: getPurchasableCollection
      responses:
        '200':
          description: A list of purchasable collections.
  /vendor/selling-plan-group:
    get:
      tags: [Plans]
      summary: Get Selling Plan Groups
      operationId: getSellingPlanGroups
      responses:
        '200':
          description: The shop's selling plan groups.
  /vendor/selling-plan-configs:
    get:
      tags: [Plans]
      summary: Get all programs for a shop
      operationId: getSellingPlanConfigs
      responses:
        '200':
          description: The shop's subscription programs.
  /vendor/webhook:
    get:
      tags: [Webhooks]
      summary: Get webhooks for current organization
      operationId: getWebhooks
      responses:
        '200':
          description: The organization's webhooks.
    post:
      tags: [Webhooks]
      summary: Create a new webhook
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Webhook creation payload (topic, delivery URL).
      responses:
        '201':
          description: The created webhook.
  /vendor/webhook/{webhookId}:
    put:
      tags: [Webhooks]
      summary: Edit existing webhook
      operationId: editWebhook
      parameters:
        - name: webhookId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The updated webhook.
    delete:
      tags: [Webhooks]
      summary: Delete existing webhook
      operationId: deleteWebhook
      parameters:
        - name: webhookId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The webhook was deleted.
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.