BTCPay Server Subscriptions API

openapi: 3.0.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:
    FeatureModel:
      type: object
      description: Represents a feature that can be included in an offering or plan.
      required:
      - id
      - description
      properties:
        id:
          type: string
          description: Unique identifier of the feature.
          example: feature-analytics
        description:
          type: string
          description: Short description of the feature.
          example: Access to analytics dashboard.
    CreateOfferingModel:
      type: object
      description: New offering data to create.
      required:
      - appName
      properties:
        appName:
          type: string
          nullable: true
          description: Display name of the related [application](#tag/Apps).
          example: Example App
        successRedirectUrl:
          type: string
          nullable: true
          description: The default URL to redirect to after a plan checkout is successful.
          example: https://example.com/success
        metadata:
          type: object
          description: Custom metadata for the offering.
          additionalProperties: true
          example:
            category: saas
            region: us
        features:
          type: array
          nullable: true
          description: List of features included in this offering.
          items:
            $ref: '#/components/schemas/FeatureModel'
    CustomerSelector:
      type: string
      description: 'Flexible identifier for selecting a customer. Supports: customer ID (e.g., `cust_abc123`), an email (e.g., `user@example.com`), or a key/value identity (e.g., `Email:user@example.com`).'
      example: cust_GUGnpx3311fkaqGk7f
    CustomerId:
      type: string
      description: Unique identifier of the customer.
      example: cust_GUGnpx3311fkaqGk7f
    CreatePortalSessionRequest:
      type: object
      description: Request payload for creating a subscriber portal session.
      properties:
        storeId:
          $ref: '#/components/schemas/StoreId'
        offeringId:
          $ref: '#/components/schemas/OfferingId'
        customerSelector:
          $ref: '#/components/schemas/CustomerSelector'
        durationMinutes:
          type: integer
          nullable: true
          description: Duration in minutes before the portal session expires.
          example: 30
    InvoiceId:
      type: string
      description: The invoice ID
      example: HMprBnL9BTXWuPvpoKBS6e
    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
          format: unix-time
          nullable: true
          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
    OfferingId:
      type: string
      description: Offering's ID
      example: offering_DKWhZGB6PZsgTcPwpf
    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
          nullable: true
          description: Number of grace period days after expiry.
          example: 7
        optimisticActivation:
          type: boolean
          nullable: true
          description: Indicates if the plan is activated before payment confirmation.
          example: true
        price:
          type: string
          nullable: true
          description: Price of the plan as a numeric string.
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '19.99'
        renewable:
          type: boolean
          nullable: true
          description: Indicates if the plan can be renewed.
          example: true
        trialDays:
          type: integer
          nullable: true
          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
          nullable: true
          description: Recurring interval for billing.
          enum:
          - Monthly
          - Quarterly
          - Yearly
          - Lifetime
          example: Monthly
        features:
          type: array
          nullable: true
          description: List of features from the offering included in this plan.
          items:
            type: string
          example:
          - feature-analytics
    PortalSessionId:
      type: string
      example: ps_665afQ23ExGouiY4EZ
      description: Identifier of the portal session.
    PlanId:
      type: string
      description: Plan's ID
      example: plan_KZMVyuQp3v2vFWnEUM
    PlanCheckoutId:
      type: string
      description: Unique identifier of the plan checkout session.
      example: plancheckout_Hpm59L1NPCMUj477Q5
    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
          format: unix-time
          nullable: true
          description: End of the current billing period.
          example: 1713200000
        trialEnd:
          type: integer
          format: unix-time
          nullable: true
          description: End of the subscriber's trial period.
          example: 1711000000
        gracePeriodEnd:
          type: integer
          format: unix-time
          nullable: true
          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
          nullable: true
          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
          nullable: true
          description: ID of the invoice being processed.
          example: inv_88443
        nextPlan:
          $ref: '#/components/schemas/OfferingPlanModel'
          nullable: true
          description: Plan scheduled for next billing cycle.
        scheduledPlan:
          $ref: '#/components/schemas/OfferingPlanModel'
          nullable: true
          description: Plan scheduled to activate at the end of the current billing period.
        scheduledPlanActivatesAt:
          type: integer
          format: unix-time
          nullable: true
          description: Timestamp when the scheduled plan change will activate.
          example: 1713200000
        phase:
          $ref: '#/components/schemas/SubscriptionPhase'
    OnPayBehavior:
      type: string
      description: 'Defines how the system should behave when payment is processed during a plan checkout or migration.

        * `SoftMigration`: Starts the plan only if payment is due. If no payment is due yet, the amount is added as credit instead of starting the plan.

        * `HardMigration`: Starts the plan immediately, even if payment is not due. If the user already paid for unused time, the unused portion is refunded before starting the plan.'
      enum:
      - SoftMigration
      - HardMigration
      example: SoftMigration
      x-enumDescriptions:
        SoftMigration: Starts the plan only if payment is due. If no payment is due yet, the amount is added as credit instead of starting the plan.
        HardMigration: Starts the plan immediately, even if payment is not due. If the user already paid for unused time, the unused portion is refunded before starting the plan.
    BaseUrl:
      type: string
      description: Base URL of the BTCPay Server instance.
      example: https://btcpay.example.com/
    CreditModel:
      type: object
      description: Represents a subscriber's credit balance in a specific currency.
      properties:
        currency:
          type: string
          description: Currency code of the credit balance.
          example: USD
        value:
          type: string
          description: Current credit value as a numeric string.
          example: '150.00'
    ProblemDetails:
      type: object
      description: Description of an error happening during processing of the request
      properties:
        code:
          type: string
          nullable: false
          description: An error code describing the error
        message:
          type: string
          nullable: false
          description: User friendly error message about the error
    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
    PlanCheckoutModel:
      type: object
      description: Represents a checkout session for activating or purchasing a subscription plan.
      properties:
        subscriber:
          $ref: '#/components/schemas/SubscriberModel'
          description: Subscriber associated with the checkout. (It can be null if the checkout is for a new subscriber, and the users didn't [proceed with the checkout](#operat

# --- 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