openapi: 3.2.0
info:
  title: ThriveCart Subscriptions API
  version: '1'
  description: 'The ThriveCart API lets you read and manage the products, bumps, upsells, downsells, transactions, customers, subscriptions, affiliates and Learn students in a ThriveCart account, and to create targeted event subscriptions (webhooks).


    This OpenAPI document is DERIVED by API Evangelist from ThriveCart''s own published Postman collection (https://apidocs.thrivecart.com/). Every path, method, parameter, request field, description and example response body is carried over from that first-party source. ThriveCart does not publish an OpenAPI definition of its own.'
  termsOfService: https://thrivecart.com/legal/thrivecart/
  contact:
    name: ThriveCart Developer Support
    url: https://developers.thrivecart.com/
    email: support@thrivecart.com
servers:
- url: https://thrivecart.com/api/external
  description: Production
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Subscriptions
paths:
  /cancelSubscription:
    post:
      operationId: cancelASubscription
      summary: Cancel a subscription
      description: Cancel a subscription using the order ID and subscription ID pulled from either a Transaction search or the full history of a customer.
      tags:
      - Subscriptions
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                order_id:
                  type: string
                  description: Order ID
                subscription_id:
                  type: string
                  description: Subscription ID
              required:
              - order_id
              - subscription_id
      responses:
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              examples:
                Invalid_parameters:
                  value:
                    error: You do not have permission to access this subscription.
          headers:
            X-ThriveCart-Account-Name:
              description: X-ThriveCart-Account-Name
              schema:
                type: string
              example: myaccount
            X-ThriveCart-Account-URL:
              description: X-ThriveCart-Account-URL
              schema:
                type: string
              example: https://myaccount.thrivecart.com/
        '200':
          description: Cancel a subscription
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
              examples:
                Cancel_a_subscription:
                  value:
                    success: true
                    message: This subscription has been successfully cancelled.
          headers:
            X-ThriveCart-Account-Name:
              description: X-ThriveCart-Account-Name
              schema:
                type: string
              example: myaccount
            X-ThriveCart-Account-URL:
              description: X-ThriveCart-Account-URL
              schema:
                type: string
              example: https://myaccount.thrivecart.com/
        '401':
          description: Unauthorized - the API key or access token is missing, invalid or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                auth_missing:
                  value:
                    error: auth.missing
                invalid_token:
                  value:
                    error: invalid_token
                    error_description: The access token provided is invalid
        '429':
          description: Too Many Requests - the account has exceeded 60 requests per minute.
      security:
      - bearerAuth: []
      - oauth2: []
  /refund:
    post:
      operationId: refundATransaction
      summary: Refund a transaction
      description: Refund a specific transaction using the order ID and purchase reference pulled from either a Transaction search or the full history of a customer.
      tags:
      - Subscriptions
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                order_id:
                  type: string
                  description: Order ID
                reference:
                  type: string
                  description: Item reference
              required:
              - order_id
              - reference
      responses:
        '200':
          description: Refund a transaction
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
              examples:
                Refund_a_transaction:
                  value:
                    success: true
                    message: This refund has been issued successfully.
          headers:
            X-ThriveCart-Account-Name:
              description: X-ThriveCart-Account-Name
              schema:
                type: string
              example: myaccount
            X-ThriveCart-Account-URL:
              description: X-ThriveCart-Account-URL
              schema:
                type: string
              example: https://myaccount.thrivecart.com/
        '404':
          description: Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              examples:
                Invalid_parameters:
                  value:
                    error: The requested charge could not be identified.
          headers:
            X-ThriveCart-Account-Name:
              description: X-ThriveCart-Account-Name
              schema:
                type: string
              example: myaccount
            X-ThriveCart-Account-URL:
              description: X-ThriveCart-Account-URL
              schema:
                type: string
              example: https://myaccount.thrivecart.com/
        '401':
          description: Unauthorized - the API key or access token is missing, invalid or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                auth_missing:
                  value:
                    error: auth.missing
                invalid_token:
                  value:
                    error: invalid_token
                    error_description: The access token provided is invalid
        '429':
          description: Too Many Requests - the account has exceeded 60 requests per minute.
      security:
      - bearerAuth: []
      - oauth2: []
  /pauseSubscription:
    post:
      operationId: pauseASubscription
      summary: Pause a subscription
      description: 'Pause a subscription using the order ID and subscription ID pulled from either a Transaction search or the full history of a customer.


        Note that you can provide an optional timestamp to automatically resume the subscription on that date, or leave this blank to pause indefinitely.'
      tags:
      - Subscriptions
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                order_id:
                  type: string
                  description: Order ID
                subscription_id:
                  type: string
                  description: Subscription ID
                auto_resume:
                  type: string
                  description: (Optional) Unix timestamp to automatically resume this subscription - must be 24 hours in the future
              required:
              - order_id
              - subscription_id
      responses:
        '200':
          description: Pause a subscription
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  customer_id:
                    type: string
                  frequency:
                    type: string
                  plan_id:
                    type: string
                  message:
                    type: string
              examples:
                Pause_a_subscription:
                  value:
                    success: true
                    customer_id: cus_I7ZKYD0DfM1vz0
                    frequency: month
                    plan_id: thrivecart-1-product-1-12500-month-usd
                    message: This subscription has been successfully paused.
          headers:
            X-ThriveCart-Account-Name:
              description: X-ThriveCart-Account-Name
              schema:
                type: string
              example: myaccount
            X-ThriveCart-Account-URL:
              description: X-ThriveCart-Account-URL
              schema:
                type: string
              example: https://myaccount.thrivecart.com/
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              examples:
                Invalid_parameters:
                  value:
                    error: You must provide a valid order ID.
          headers:
            X-ThriveCart-Account-Name:
              description: X-ThriveCart-Account-Name
              schema:
                type: string
              example: myaccount
            X-ThriveCart-Account-URL:
              description: X-ThriveCart-Account-URL
              schema:
                type: string
              example: https://myaccount.thrivecart.com/
        '401':
          description: Unauthorized - the API key or access token is missing, invalid or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                auth_missing:
                  value:
                    error: auth.missing
                invalid_token:
                  value:
                    error: invalid_token
                    error_description: The access token provided is invalid
        '429':
          description: Too Many Requests - the account has exceeded 60 requests per minute.
      security:
      - bearerAuth: []
      - oauth2: []
  /resumeSubscription:
    post:
      operationId: resumeASubscription
      summary: Resume a subscription
      description: Resume a subscription using the order ID and subscription ID pulled from either a Transaction search or the full history of a customer.
      tags:
      - Subscriptions
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                order_id:
                  type: string
                  description: Order ID
                subscription_id:
                  type: string
                  description: Subscription ID
              required:
              - order_id
              - subscription_id
      responses:
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              examples:
                Invalid_parameters:
                  value:
                    error: You must provide a valid order ID.
          headers:
            X-ThriveCart-Account-Name:
              description: X-ThriveCart-Account-Name
              schema:
                type: string
              example: myaccount
            X-ThriveCart-Account-URL:
              description: X-ThriveCart-Account-URL
              schema:
                type: string
              example: https://myaccount.thrivecart.com/
        '200':
          description: Resume a subscription
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  subscription_id:
                    type: string
                  message:
                    type: string
              examples:
                Resume_a_subscription:
                  value:
                    success: true
                    subscription_id: sub_IMaXasOaNCuHqo
                    message: This subscription has been successfully resumed.
          headers:
            X-ThriveCart-Account-Name:
              description: X-ThriveCart-Account-Name
              schema:
                type: string
              example: myaccount
            X-ThriveCart-Account-URL:
              description: X-ThriveCart-Account-URL
              schema:
                type: string
              example: https://myaccount.thrivecart.com/
        '401':
          description: Unauthorized - the API key or access token is missing, invalid or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                auth_missing:
                  value:
                    error: auth.missing
                invalid_token:
                  value:
                    error: invalid_token
                    error_description: The access token provided is invalid
        '429':
          description: Too Many Requests - the account has exceeded 60 requests per minute.
      security:
      - bearerAuth: []
      - oauth2: []
components:
  schemas:
    Error:
      type: object
      description: ThriveCart error envelope. Not RFC 9457 problem+json.
      properties:
        error:
          type: string
          description: Machine-readable error key.
        error_description:
          type: string
          description: Human-readable description, when present.
      required:
      - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Account-scoped API key created under Settings > API & webhooks > API tokens, or an OAuth access token, sent as `Authorization: Bearer <token>`.'
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization code grant for applications acting on behalf of another ThriveCart account. ThriveCart does not publish a scope reference; access is granted account-wide on consent.
      flows:
        authorizationCode:
          authorizationUrl: https://thrivecart.com/authorization/new
          tokenUrl: https://thrivecart.com/authorization/token
          scopes: {}
externalDocs:
  description: ThriveCart Developers
  url: https://developers.thrivecart.com/documentation/