BTCPay Server Subscriptions API

openapi: 3.2.0
info:
  title: BTCPay Greenfield API Keys Subscriptions API
  version: v1
  description: "# Introduction\n\nThe BTCPay Server Greenfield API is a REST API. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\n# Authentication\n\nYou can authenticate either via Basic Auth or an API key. It's recommended to use an API key for better security. You can create an API key in the BTCPay Server UI under `Account` -> `Manage Account` -> `API keys`. You can restrict the API key for one or multiple stores and for specific permissions. For testing purposes, you can give it the 'Unrestricted access' permission. On production you should limit the permissions to the actual endpoints you use, you can see the required permission on the API docs at the top of each endpoint under `AUTHORIZATIONS`.\n\nIf you want to simplify the process of creating API keys for your users, you can use the [Authorization endpoint](https://docs.btcpayserver.org/API/Greenfield/v1/#tag/Authorization) to predefine permissions and redirect your users to the BTCPay Server Authorization UI. You can find more information about this on the [API Authorization Flow docs](https://docs.btcpayserver.org/BTCPayServer/greenfield-authorization/) page.\n\n# Usage examples\n\nUse **Basic Auth** to read store information with cURL:\n```bash\nBTCPAY_INSTANCE=\"https://mainnet.demo.btcpayserver.org\"\nUSER=\"MyTestUser@gmail.com\"\nPASSWORD=\"notverysecurepassword\"\nPERMISSION=\"btcpay.store.canmodifystoresettings\"\nBODY=\"$(echo \"{}\" | jq --arg \"a\" \"$PERMISSION\" '. + {permissions:[$a]}')\"\n\nAPI_KEY=\"$(curl -s \\\n     -H \"Content-Type: application/json\" \\\n     --user \"$USER:$PASSWORD\" \\\n     -X POST \\\n     -d \"$BODY\" \\\n     \"$BTCPAY_INSTANCE/api/v1/api-keys\" | jq -r .apiKey)\"\n```\n\n\nUse an **API key** to read store information with cURL:\n```bash\nSTORE_ID=\"yourStoreId\"\n\ncurl -s \\\n     -H \"Content-Type: application/json\" \\\n     -H \"Authorization: token $API_KEY\" \\\n     -X GET \\\n     \"$BTCPAY_INSTANCE/api/v1/stores/$STORE_ID\"\n```\n\nYou can find more examples on our docs for different programming languages:\n- [cURL](https://docs.btcpayserver.org/Development/GreenFieldExample/)\n- [Javascript/Node.Js](https://docs.btcpayserver.org/Development/GreenFieldExample-NodeJS/)\n- [PHP](https://docs.btcpayserver.org/Development/GreenFieldExample-PHP/)\n\n"
  contact:
    name: BTCPay Server
    url: https://btcpayserver.org
  license:
    name: MIT
    url: https://github.com/btcpayserver/btcpayserver/blob/master/LICENSE
servers:
- url: https://{btcpay-host}
  description: Your BTCPay Server instance
  variables:
    btcpay-host:
      default: mainnet.demo.btcpayserver.org
      description: The hostname of your BTCPay Server instance
security:
- API_Key: []
  Basic: []
tags:
- name: Subscriptions
  description: Subscription operations
paths:
  /api/v1/stores/{storeId}/offerings/{offeringId}:
    get:
      summary: Get an offering
      description: Returns a specific offering for a store.
      operationId: GetOffering
      tags:
      - Subscriptions
      security:
      - API_Key:
        - btcpay.store.canviewofferings
        Basic: []
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/OfferingId'
      responses:
        '200':
          description: Offering retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferingModel'
        '404':
          description: Offering not found.
    put:
      summary: Update an offering
      description: Updates an existing offering for the specified store.
      operationId: UpdateOffering
      tags:
      - Subscriptions
      security:
      - API_Key:
        - btcpay.store.canmodifyofferings
        Basic: []
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/OfferingId'
      requestBody:
        required: true
        description: Offering data to update.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOfferingModel'
      responses:
        '200':
          description: Offering updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferingModel'
        '400':
          description: Invalid request data.
        '404':
          description: Offering not found.
  /api/v1/stores/{storeId}/offerings:
    get:
      summary: List offerings for a store
      description: Retrieves all offerings associated with the specified store.
      operationId: GetOfferings
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/StoreId'
      security:
      - API_Key:
        - btcpay.store.canviewofferings
        Basic: []
      responses:
        '200':
          description: List of offerings retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OfferingModel'
    post:
      summary: Create an offering
      description: Creates a new offering for the specified store.
      operationId: CreateOffering
      tags:
      - Subscriptions
      security:
      - API_Key:
        - btcpay.store.canmodifyofferings
        Basic: []
      parameters:
      - $ref: '#/components/parameters/StoreId'
      requestBody:
        required: true
        description: Offering data to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOfferingModel'
      responses:
        '201':
          description: Offering created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferingModel'
        '400':
          description: Invalid request data.
  /api/v1/stores/{storeId}/offerings/{offeringId}/plans:
    post:
      summary: Create an offering plan
      description: Creates a new plan for a specific offering.
      operationId: CreateOfferingPlan
      tags:
      - Subscriptions
      security:
      - API_Key:
        - btcpay.store.canmodifyofferings
        Basic: []
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/OfferingId'
      requestBody:
        required: true
        description: Plan data to create for the offering.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePlanRequest'
      responses:
        '201':
          description: Plan created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferingPlanModel'
        '400':
          description: Invalid request data.
  /api/v1/stores/{storeId}/offerings/{offeringId}/plans/{planId}:
    get:
      summary: Get an offering plan
      description: Returns a specific plan for a given offering.
      operationId: GetOfferingPlan
      tags:
      - Subscriptions
      security:
      - API_Key:
        - btcpay.store.canviewofferings
        Basic: []
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/OfferingId'
      - $ref: '#/components/parameters/PlanId'
      responses:
        '200':
          description: Plan retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferingPlanModel'
        '404':
          description: Plan not found.
    put:
      summary: Update an offering plan
      description: Updates an existing plan for a specific offering.
      operationId: UpdateOfferingPlan
      tags:
      - Subscriptions
      security:
      - API_Key:
        - btcpay.store.canmodifyofferings
        Basic: []
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/OfferingId'
      - $ref: '#/components/parameters/PlanId'
      requestBody:
        required: true
        description: Plan data to update for the offering.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePlanRequest'
      responses:
        '200':
          description: Plan updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferingPlanModel'
        '400':
          description: Invalid request data.
        '404':
          description: Plan not found.
  /api/v1/stores/{storeId}/offerings/{offeringId}/subscribers/{customerSelector}:
    get:
      summary: Get a subscriber
      description: Retrieves a subscriber for a specific offering by customer selector.
      operationId: GetSubscriber
      tags:
      - Subscriptions
      security:
      - API_Key:
        - btcpay.store.canviewofferings
        Basic: []
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/OfferingId'
      - $ref: '#/components/parameters/CustomerSelector'
      responses:
        '200':
          description: Subscriber retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriberModel'
        '404':
          description: Subscriber not found.
    delete:
      summary: Delete a subscriber
      description: Deletes a subscriber for a specific offering by customer selector.
      operationId: DeleteSubscriber
      tags:
      - Subscriptions
      security:
      - API_Key:
        - btcpay.store.canmanagesubscribers
        Basic: []
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/OfferingId'
      - $ref: '#/components/parameters/CustomerSelector'
      responses:
        '204':
          description: Subscriber deleted successfully.
        '404':
          description: Subscriber not found.
  /api/v1/stores/{storeId}/offerings/{offeringId}/subscribers/{customerSelector}/credits/{currency}:
    get:
      summary: Get subscriber credit balance
      description: Retrieves the credit balance for a subscriber in the specified currency.
      operationId: GetCredit
      tags:
      - Subscriptions
      security:
      - API_Key:
        - btcpay.store.canmanagesubscribers
        Basic: []
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/OfferingId'
      - $ref: '#/components/parameters/CustomerSelector'
      - $ref: '#/components/parameters/Subscriptions/Currency'
      responses:
        '200':
          description: Credit retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditModel'
        '404':
          description: Credit record not found.
    post:
      summary: Update subscriber credit balance
      description: Adds credit or charges credit for a subscriber in a given currency.
      operationId: UpdateCredit
      tags:
      - Subscriptions
      security:
      - API_Key:
        - btcpay.store.cancreditsubscribers
        Basic: []
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/OfferingId'
      - $ref: '#/components/parameters/CustomerSelector'
      - $ref: '#/components/parameters/Subscriptions/Currency'
      requestBody:
        required: true
        description: Details for modifying subscriber credit.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCreditRequest'
      responses:
        '200':
          description: Credit updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditModel'
        '400':
          description: 'Error code: `overdraft`. The subscriber''s balance would be overdrawn. Use `allowOverdraft` to allow this.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/stores/{storeId}/offerings/{offeringId}/subscribers/{customerSelector}/suspend:
    post:
      summary: Suspend a subscriber
      description: Suspends a subscriber for the specified offering.
      operationId: SuspendSubscriber
      tags:
      - Subscriptions
      security:
      - API_Key:
        - btcpay.store.canmanagesubscribers
        Basic: []
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/OfferingId'
      - $ref: '#/components/parameters/CustomerSelector'
      requestBody:
        required: true
        description: Details about why the subscriber is being suspended.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuspendSubscriberRequest'
      responses:
        '200':
          description: Subscriber suspended successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriberModel'
        '400':
          description: Invalid request data.
  /api/v1/stores/{storeId}/offerings/{offeringId}/subscribers/{customerSelector}/unsuspend:
    post:
      summary: Unsuspend a subscriber
      description: Removes suspension from a subscriber for the specified offering.
      operationId: UnsuspendSubscriber
      tags:
      - Subscriptions
      security:
      - API_Key:
        - btcpay.store.canmanagesubscribers
        Basic: []
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/OfferingId'
      - $ref: '#/components/parameters/CustomerSelector'
      responses:
        '200':
          description: Subscriber unsuspended successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriberModel'
        '400':
          description: Invalid request data.
  /api/v1/stores/{storeId}/offerings/{offeringId}/subscribers/{customerSelector}/dates:
    put:
      summary: Update subscriber dates
      description: 'Manually overrides the subscription start date and/or expiration date for a subscriber.


        Omitting a field leaves the corresponding date unchanged. An empty body `{}` is a no-op and returns the subscriber unchanged.


        When `expirationDate` is provided, the grace period end and reminder date are recalculated automatically from the plan settings.'
      operationId: UpdateSubscriberDates
      tags:
      - Subscriptions
      security:
      - API_Key:
        - btcpay.store.canmanagesubscribers
        Basic: []
      parameters:
      - $ref: '#/components/parameters/StoreId'
      - $ref: '#/components/parameters/OfferingId'
      - $ref: '#/components/parameters/CustomerSelector'
      requestBody:
        required: true
        description: Dates to update. All fields are optional — omitting a field leaves it unchanged.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSubscriberDatesRequest'
      responses:
        '200':
          description: Subscriber dates updated (or unchanged if no fields were provided).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriberModel'
        '400':
          description: 'Error code: `invalid-dates`. The expiration date must be after the start date.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Subscriber not found.
  /api/v1/plan-checkout/{checkoutId}:
    get:
      summary: Get a plan checkout
      description: Retrieves the details of a plan checkout session.
      operationId: GetPlanCheckout
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/PlanCheckoutId'
      responses:
        '200':
          description: Checkout retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanCheckoutModel'
        '404':
          description: Checkout session not found.
    post:
      summary: Proceed with a plan checkout
      description: 'Continues a plan checkout session.


        **Behavior:**

        - If payment is required, the checkout assigns a BTCPay Server invoice and `invoiceId` will be set.

        - If no payment is required (for example, the subscriber already has enough credit or no credit purchase is needed), the plan will start immediately and `planStarted` will be `true`.'
      operationId: ProceedPlanCheckout
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/PlanCheckoutId'
      - name: email
        in: query
        required: false
        description: Optional customer email used when proceeding with the checkout.
        schema:
          type: string
        example: user@example.com
      responses:
        '200':
          description: 'Checkout processed successfully.


            **Behavior:**

            - If payment is required, `invoiceId` contains the BTCPay Server invoice the user must pay.

            - If no payment is required, the subscription is activated immediately and `planStarted` will be `true`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanCheckoutModel'
        '400':
          description: 'Error code: `invoice-creation-error`. Error during the creation of the invoice.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Checkout session not found.
  /api/v1/plan-checkout:
    post:
      summary: Create a plan checkout session
      description: Creates a checkout session for purchasing or activating a plan.
      operationId: CreatePlanCheckout
      tags:
      - Subscriptions
      security:
      - API_Key:
        - btcpay.store.canmanagesubscribers
        Basic: []
      requestBody:
        required: true
        description: Details required to create a checkout session.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePlanCheckoutRequest'
      responses:
        '200':
          description: Checkout created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanCheckoutModel'
        '400':
          description: Invalid request data.
  /api/v1/subscriber-portal:
    post:
      summary: Create a subscriber portal session
      description: Creates a portal session that allows a subscriber to manage their subscriptions, view billing details, or update account information.
      operationId: CreatePortalSession
      tags:
      - Subscriptions
      security:
      - API_Key:
        - btcpay.store.canmanagesubscribers
        Basic: []
      requestBody:
        required: true
        description: Information required to create a subscriber portal session.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePortalSessionRequest'
      responses:
        '200':
          description: Portal session created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalSessionModel'
        '400':
          description: Invalid request data.
  /api/v1/subscriber-portal/{portalSessionId}:
    get:
      summary: Get a subscriber portal session
      description: Retrieves the details of an existing subscriber portal session.
      operationId: GetPortalSession
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/PortalSessionId'
      responses:
        '200':
          description: Portal session retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalSessionModel'
        '404':
          description: Portal session not found.
components:
  schemas:
    SubscriptionPhase:
      type: string
      description: Lifecycle phase of the subscription.
      enum:
      - Trial
      - Normal
      - Grace
      - Expired
      example: Normal
    PortalSessionModel:
      type: object
      description: Represents a subscriber portal session used for managing subscriptions, billing, and account details.
      properties:
        baseUrl:
          $ref: '#/components/schemas/BaseUrl'
        id:
          $ref: '#/components/schemas/PortalSessionId'
        subscriber:
          $ref: '#/components/schemas/SubscriberModel'
          description: The subscriber associated with this portal session.
        expiration:
          type:
          - integer
          - 'null'
          format: unix-time
          description: Expiration timestamp for the portal session.
          example: 1710602000
        isExpired:
          type: boolean
          description: Indicates whether the portal session is expired.
          example: false
        url:
          type: string
          description: Public URL where the subscriber can access the portal session.
          example: https://btcpay.example.com/subscriber-portal/ps_665afQ23ExGouiY4EZ
    OfferingPlanModel:
      type: object
      description: Represents a pricing plan for an offering.
      properties:
        id:
          $ref: '#/components/schemas/PlanId'
        name:
          type: string
          description: Display name of the plan.
          example: Starter Plan
        status:
          type: string
          description: Current status of the plan.
          enum:
          - Active
          - Retired
          example: Active
        price:
          type: string
          description: Price of the plan as a numeric string.
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '19.99'
        currency:
          type: string
          description: Currency code for the price.
          example: USD
        recurringType:
          type: string
          description: Recurring interval for billing.
          enum:
          - Monthly
          - Quarterly
          - Yearly
          - Lifetime
          example: Monthly
        gracePeriodDays:
          type: integer
          description: Number of grace period days after expiry.
          example: 7
        trialDays:
          type: integer
          description: Number of trial days before billing.
          example: 14
        description:
          type: string
          description: Short description of the plan.
          example: Standard monthly subscription.
        memberCount:
          type: integer
          description: Maximum number of members allowed under this plan.
          example: 10
        optimisticActivation:
          type: boolean
          description: Indicates if the plan is activated before payment confirmation.
          example: true
        features:
          type: array
          description: List of feature identifiers included in this plan.
          items:
            type: string
          example:
          - feature-analytics
        renewable:
          type: boolean
          description: Indicates if the plan can be renewed.
          example: true
        metadata:
          type: object
          description: Custom metadata for the plan.
          additionalProperties: true
          example:
            tier: standard
    SubscriberModel:
      type: object
      description: Represents a subscriber of an offering.
      properties:
        created:
          type: integer
          format: unix-time
          description: Timestamp when the subscription was created.
          example: 1710598234
        customer:
          $ref: '#/components/schemas/CustomerModel'
          description: Customer associated with the subscription.
        offering:
          $ref: '#/components/schemas/OfferingModel'
          description: Offering associated with the subscription.
        plan:
          $ref: '#/components/schemas/OfferingPlanModel'
          description: Current active plan of the subscriber.
        periodEnd:
          type:
          - integer
          - 'null'
          format: unix-time
          description: End of the current billing period.
          example: 1713200000
        trialEnd:
          type:
          - integer
          - 'null'
          format: unix-time
          description: End of the subscriber's trial period.
          example: 1711000000
        gracePeriodEnd:
          type:
          - integer
          - 'null'
          format: unix-time
          description: End of the grace period.
          example: 1711500000
        isActive:
          type: boolean
          description: Indicates if the subscription is active. (Phase is not `Expired`, and not suspended)
          example: true
        isSuspended:
          type: boolean
          description: Indicates if the subscription is suspended.
          example: false
        suspensionReason:
          type:
          - string
          - 'null'
          description: Reason for suspension, if applicable.
          example: Suspicious activity detected
        autoRenew:
          type: boolean
          description: Indicates if the subscription renews automatically.
          example: true
        metadata:
          type: object
          description: Custom metadata for the subscription.
          additionalProperties: true
          example:
            segment: beta
        processingInvoiceId:
          type:
          - string
          - 'null'
          description: ID of the invoice being processed.
          example: inv_88443
        nextPlan:
          $ref: '#/components/schemas/OfferingPlanModel'
          description: Plan scheduled for next billing cycle.
        scheduledPlan:
          $ref: '#/components/schemas/OfferingPlanModel'
          description: Plan scheduled to activate at the end of the current billing period.
        scheduledPlanActivatesAt:
          type:
          - integer
          - 'null'
          format: unix-time
          description: Timestamp when the scheduled plan change will activate.
          example: 1713200000
        phase:
          $ref: '#/components/schemas/SubscriptionPhase'
    CustomerModel:
      type: object
      description: Represents a customer associated with a store.
      properties:
        storeId:
          $ref: '#/components/schemas/StoreId'
        id:
          $ref: '#/components/schemas/CustomerId'
        externalId:
          type: string
          description: External system identifier for the customer.
          example: ext_4455
        identities:
          type: object
          description: Identity attributes for matching and lookup (e.g., email, username).
          additionalProperties: true
          example:
            Email: subscriber@example.com
        metadata:
          type: object
          description: Custom metadata associated with the customer.
          additionalProperties: true
          example:
            segment: premium
            locale: en-US
    PlanCheckoutId:
      type: string
      description: Unique identifier of the plan checkout session.
      example: plancheckout_Hpm59L1NPCMUj477Q5
    CustomerId:
      type: string
      description: Unique identifier of the customer.
      example: cust_GUGnpx3311fkaqGk7f
    CreatePlanRequest:
      type: object
      description: Request payload for creating a new offering plan.
      properties:
        name:
          type: string
          description: Display name of the plan.
          example: Monthly Plan
        description:
          type: string
          description: Short description of the plan.
          example: Standard monthly subscription.
        currency:
          type: string
          description: Currency code for the plan price.
          example: USD
        gracePeriodDays:
          type:
          - integer
          - 'null'
          description: Number of grace period days after expiry.
          example: 7
        optimisticActivation:
          type:
          - boolean
          - 'null'
          description: Indicates if the plan is activated before payment confirmation.
          example: true
        price:
          type:
          - string
          - 'null'
          description: Price of the plan as a numeric string.
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '19.99'
        renewable:
          type:
          - boolean
          - 'null'
          description: Indicates if the plan can be renewed.
          example: true
        trialDays:
          type:
          - integer
          - 'null'
          description: Number of trial days before billing.
          example: 14
        metadata:
          type: object
          description: Custom metadata for the plan.
          additionalProperties: true
          example:
            tier: standard
        recurringType:
          type:
          - string
          - 'null'
          description: Recurring interval for billing.
          enum:
          - Monthly
          - Quarterly
          - Yearly
          - Lifetime
          example: Monthly
        features:
          type:
          - array
          - 'null'
          description: List of features from the offering included in this plan.
          items:
            type: string
          example:
          - feature-analytics
    SuspendSubscriberRequest:
      type: object
      description: Request payload for suspending a subscriber.
      properties:
        reason:
          type: string
          description: Reason for the suspension.
          example: Suspicious behavior detected
    InvoiceId:
      type: string
      description: The invoice ID
      example: HMprBnL9BTXWuPvpoKBS6e
    CreatePlanCheckoutRequest:
      type: object
      description: Request payload for initiating a plan checkout session.
      properties:
        storeId:
          $ref: '#/components/schemas/StoreId'
        offeringId:
          $ref: '#/components/schemas/OfferingId'
        planId:
          $ref: '#/components/schemas/PlanId'
        customerSelector:
          $ref: '#/components/schemas/CustomerSelector'
        durationMinutes:
          type:
          - integer
          - 'null'
          description: How long the checkout session is valid, in minutes.
          example: 30
        onPayBehavior:
          $ref: '#/components/schemas/OnPayBehavior'
          default: SoftMigration
        newSubscriberMetadata:
          type: object
          description: Metadata used when creating a new subscriber.
          additionalProperties: true
          example:
            locale: en-US
        invoiceMetadata:
          type: object
          description: Metadata attached to the created invoice.
          additionalProperties: true
          example:
            campaign: winter-sale
        metadata:
          type: object
          description: Custom metadata for the checkout session.
          additionalProperties: true
          example:
            flow: upgrade
        isTrial:
          type:
          - boolean
          - 'null'
          description: Indicates if the checkout starts a trial.
          example: false
        creditPurchase:
          type:
          - string
          - 'null'
          description: Amount of credit to purchase.
          example: '20.00'
        successRedirectLink:
          type: string
          description: URL to redirect the user after checkout success. (This default to offering's successRedirectLink, also, the `checkoutPlanId` query parameter will be added to the URL.)
          example: https://example.com/thank-you
        newSubscriberEmail:
          type:
          - string
          - 'null'
          description: Email address for creating a new subscriber. Keep `null` to let the user choose an email address in the checkout page.
    

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/btcpay/refs/heads/main/openapi/btcpay-subscriptions-api-openapi.yml