BTCPay Server Stores API

openapi: 3.2.0
info:
  title: BTCPay Greenfield Stores API
  version: v1
  description: '# Introduction


    The 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.


    # Authentication


    You 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`.


    If you want to simplify the process of creating API keys for your users, you can use the Authorization endpoint 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 page.


    # Usage examples


    Use **Basic Auth** to read store information with cURL:

    ```bash

    BTCPAY_INSTANCE="https://mainnet.demo.btcpayserver.org"

    USER="MyTestUser@gmail.com"

    PASSWORD="notverysecurepassword"

    PERMISSION="btcpay.store.canmodifystoresettings"

    BODY="$(echo "{}" | jq --arg "a" "$PERMISSION" ''. + {permissions:[$a]}'')"


    API_KEY="$(curl -s \

    -H "Content-Type: application/json" \

    --user "$USER:$PASSWORD" \

    -X POST \

    -d "$BODY" \

    "$BTCPAY_INSTANCE/api/v1/api-keys" | jq -r .apiKey)"

    ```


    Use an **API key** to read store information with cURL:

    ```bash

    STORE_ID="yourStoreId"


    curl -s \

    -H "Content-Type: application/json" \

    -H "Authorization: token $API_KEY" \

    -X GET \

    "$BTCPAY_INSTANCE/api/v1/stores/$STORE_ID"

    ```


    You can find more examples on our docs for different programming languages:

    - cURL

    - Javascript/Node.Js

    - PHP'
  contact:
    name: BTCPay Server
    url: https://btcpayserver.org
  license:
    name: MIT
    url: https://github.com/btcpayserver/btcpayserver/blob/master/LICENSE
servers:
- url: /
  description: BTCPay Server Greenfield API
security:
- API_Key: []
  Basic: []
tags:
- name: Stores
  description: Store operations
paths:
  /api/v1/stores:
    get:
      tags:
      - Stores
      summary: Get stores
      description: View information about the available stores
      operationId: Stores_GetStores
      responses:
        '200':
          description: list of stores
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreDataList'
        '401':
          description: Missing authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
      - API_Key:
        - btcpay.store.canviewstoresettings
        Basic: []
    post:
      operationId: Stores_CreateStore
      tags:
      - Stores
      summary: Create a new store
      description: Create a new store (default values can be different if the server settings use a default store template)
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreBaseData'
        required: true
        x-position: 1
      responses:
        '200':
          description: Information about the new store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreData'
        '400':
          description: A list of errors that occurred when creating the store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: If you are authenticated but forbidden to add new stores
      security:
      - API_Key:
        - btcpay.store.canmodifystoresettings
        Basic: []
  /api/v1/stores/{storeId}:
    get:
      tags:
      - Stores
      summary: Get store
      parameters:
      - $ref: '#/components/parameters/StoreId'
      description: View information about the specified store
      operationId: Stores_GetStore
      responses:
        '200':
          description: specified store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreData'
        '403':
          description: If you are authenticated but forbidden to view the specified store
        '404':
          description: The key is not found for this store
      security:
      - API_Key:
        - btcpay.store.canviewstoresettings
        Basic: []
    put:
      tags:
      - Stores
      summary: Update store
      parameters:
      - $ref: '#/components/parameters/StoreId'
      description: Update the specified store (default values can be different if the server settings use a default store template)
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreData'
        required: true
        x-position: 1
      operationId: Stores_UpdateStore
      responses:
        '200':
          description: updated specified store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreData'
        '400':
          description: A list of errors that occurred when updating the store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: If you are authenticated but forbidden to update the specified store
        '404':
          description: The key is not found for this store
      security:
      - API_Key:
        - btcpay.store.canmodifystoresettings
        Basic: []
    delete:
      operationId: Stores_DeleteStore
      tags:
      - Stores
      summary: Remove Store
      description: Removes the specified store. If there is another user with access, only your access will be removed.
      parameters:
      - $ref: '#/components/parameters/StoreId'
      responses:
        '200':
          description: The store has been removed
        '400':
          description: A list of errors that occurred when removing the store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '403':
          description: If you are authenticated but forbidden to remove the specified store
        '404':
          description: The key is not found for this store
      security:
      - API_Key:
        - btcpay.store.canmodifystoresettings
        Basic: []
  /api/v1/stores/{storeId}/logo:
    post:
      tags:
      - Stores
      summary: Uploads a logo for the store
      parameters:
      - $ref: '#/components/parameters/StoreId'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              additionalProperties: false
              properties:
                file:
                  type: string
                  description: The logo
                  format: binary
      operationId: Stores_UploadStoreLogo
      responses:
        '200':
          description: Uploads a logo for the store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationUserData'
        '404':
          description: The store could not be found
      security:
      - API_Key:
        - btcpay.store.canmodifystoresettings
        Basic: []
    delete:
      tags:
      - Stores
      summary: Deletes the store logo
      description: Delete the store's logo
      operationId: Stores_DeleteStoreLogo
      parameters:
      - $ref: '#/components/parameters/StoreId'
      responses:
        '200':
          description: Store logo deleted successfuly
        '404':
          description: The store could not be found
      security:
      - API_Key:
        - btcpay.store.canmodifystoresettings
        Basic: []
  /api/v1/stores/{storeId}/roles:
    get:
      tags:
      - Stores
      summary: Get store's roles
      parameters:
      - $ref: '#/components/parameters/StoreId'
      description: View information about the specified store's roles
      operationId: Stores_GetStoreRoles
      responses:
        '200':
          description: The user roles available for this store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleData'
        '403':
          description: If you are authenticated but forbidden to get the store's roles
        '404':
          description: Store not found
      security:
      - API_Key:
        - btcpay.store.canmodifystoresettings
        Basic: []
components:
  schemas:
    StoreId:
      type: string
      description: Store ID of the item
      example: 9CiNzKoANXxmk5ayZngSXrHTiVvvgCrwrpFQd4m2K776
    PaymentMethodId:
      type: string
      description: "Payment method IDs. Available payment method IDs for Bitcoin are:  \n- `\"BTC-CHAIN\"`: Onchain   \n-`\"BTC-LN\"`: Lightning   \n- `\"BTC-LNURL\"`: LNURL"
      example: BTC-CHAIN
    SpeedPolicy:
      type: string
      description: "This is a risk mitigation parameter for the merchant to configure how they want to fulfill orders depending on the number of block confirmations for the transaction made by the consumer on the selected cryptocurrency.\n`\"HighSpeed\"`: 0 confirmations (1 confirmation if RBF enabled in transaction)   \n`\"MediumSpeed\"`: 1 confirmation   \n`\"LowMediumSpeed\"`: 2 confirmations   \n`\"LowSpeed\"`: 6 confirmations\n"
      x-enumNames:
      - HighSpeed
      - LowMediumSpeed
      - LowSpeed
      - MediumSpeed
      enum:
      - HighSpeed
      - LowMediumSpeed
      - LowSpeed
      - MediumSpeed
    StoreDataList:
      type: array
      items:
        $ref: '#/components/schemas/StoreData'
    NetworkFeeMode:
      type: string
      description: Check whether network fee should be added to the invoice if on-chain payment is used. ([More information](https://docs.btcpayserver.org/FAQ/Stores/#add-network-fee-to-invoice-vary-with-mining-fees))
      x-enumNames:
      - Always
      - MultiplePaymentsOnly
      - Never
      enum:
      - Always
      - MultiplePaymentsOnly
      - Never
    TimeSpan:
      type: number
      format: int32
      example: 90
    TimeSpanSeconds:
      allOf:
      - $ref: '#/components/schemas/TimeSpan'
      format: seconds
      description: A span of times in seconds
    PaymentMethodCriteriaData:
      type: object
      properties:
        paymentMethodId:
          type: string
          allOf:
          - $ref: '#/components/schemas/PaymentMethodId'
        currencyCode:
          type: string
          description: The currency
          default: USD
          example: USD
        amount:
          type: string
          format: decimal
          minimum: 0
          description: The amount
        above:
          type: boolean
          default: false
          description: If the criterion is for above or below the amount
    UnixTimestamp:
      type: number
      format: int32
      example: 1592312018
      description: A unix timestamp in seconds
    ValidationProblemDetails:
      type: array
      description: An array of validation errors of the request
      items:
        type: object
        description: A specific validation error on a json property
        properties:
          path:
            type: string
            description: The json path of the property which failed validation
          message:
            type: string
            description: User friendly error message about the validation
    ProblemDetails:
      type: object
      description: Description of an error happening during processing of the request
      properties:
        code:
          type: string
          description: An error code describing the error
        message:
          type: string
          description: User friendly error message about the error
    RoleData:
      type: object
      properties:
        id:
          description: The role's Id (Same as role if the role is created at server level, if the role is created at the store level the format is `STOREID::ROLE`)
          type: string
          example: Owner
        role:
          description: The role's name
          type: string
          example: Owner
        permissions:
          description: The permissions attached to this role
          type: array
          items:
            type: string
          example:
          - btcpay.store.canmodifystoresettings
        isServerRole:
          description: Whether this role is at the scope of the store or scope of the server
          type: boolean
          example: true
    TimeSpanDays:
      allOf:
      - $ref: '#/components/schemas/TimeSpan'
      format: days
      description: A span of times in days
    ApplicationUserData:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          description: The id of the user
        email:
          type: string
          description: The email of the user
        name:
          type:
          - string
          - 'null'
          description: The name of the user
        imageUrl:
          type:
          - string
          - 'null'
          description: The profile picture URL of the user
        invitationUrl:
          type:
          - string
          - 'null'
          description: The pending invitation URL of the user
        emailConfirmed:
          type: boolean
          description: True if the email has been confirmed by the user
        requiresEmailConfirmation:
          type: boolean
          description: True if the email requires confirmation to log in
        approved:
          type: boolean
          description: True if an admin has approved the user
        requiresApproval:
          type: boolean
          description: True if the instance requires approval to log in
        storeQuota:
          type:
          - number
          - 'null'
          description: Per-user override for the max number of stores this user can create. Null means the server default applies
        created:
          type:
          - number
          - 'null'
          description: The creation date of the user as a unix timestamp. Null if created before v1.0.5.6
          allOf:
          - $ref: '#/components/schemas/UnixTimestamp'
        disabled:
          type: boolean
          description: True if an admin has disabled the user
        allowGreenfieldBasicAuth:
          type: boolean
          description: Whether Basic authentication is allowed for the Greenfield API
        roles:
          type: array
          items:
            type: string
          description: The roles of the user
    ReceiptOptions:
      type: object
      additionalProperties: false
      properties:
        enabled:
          type:
          - boolean
          - 'null'
          description: A public page will be accessible once the invoice is settled. If null or unspecified, it will fallback to the store's settings. (The default store settings is true)
        showQR:
          type:
          - boolean
          - 'null'
          default: null
          description: Show the QR code of the receipt in the public receipt page. If null or unspecified, it will fallback to the store's settings. (The default store setting is true)
        showPayments:
          type:
          - boolean
          - 'null'
          default: null
          description: Show the payment list in the public receipt page. If null or unspecified, it will fallback to the store's settings. (The default store setting is true)
    StoreBaseData:
      type: object
      x-abstract: true
      additionalProperties: false
      properties:
        name:
          type: string
          description: The name of the store
        website:
          type:
          - string
          - 'null'
          description: The absolute HTTP or HTTPS URL of the store
          format: url
        supportUrl:
          type:
          - string
          - 'null'
          description: The support URI of the store, can contain the placeholders `{OrderId}` and `{InvoiceId}`. Can be any valid URI, such as a website, email, and nostr.
          format: uri
        logoUrl:
          type:
          - string
          - 'null'
          description: Absolute URL to a logo file or a reference to an uploaded file id with `fileid:ID`
          format: uri
        cssUrl:
          type:
          - string
          - 'null'
          description: Absolute URL to CSS file to customize the public/customer-facing pages of the store. (Invoice, Payment Request, Pull Payment, etc.) or a reference to an uploaded file id with `fileid:ID`
          format: uri
        paymentSoundUrl:
          type:
          - string
          - 'null'
          description: Absolute URL to a sound file or a reference to an uploaded file id with `fileid:ID`
          format: uri
        brandColor:
          type:
          - string
          - 'null'
          description: The brand color of the store in HEX format
          example: '#F7931A'
        applyBrandColorToBackend:
          type: boolean
          default: false
          description: Apply the brand color to the store's backend as well
        defaultCurrency:
          type: string
          description: The default currency of the store
          default: USD
          example: USD
        additionalTrackedRates:
          type: array
          items:
            type: string
          description: 'Additional rates to track.

            The rates of those currencies, in addition to the default currency, will be recorded when a new invoice is created. The rates will then be accessible through reports.'
          default: []
          example:
          - EUR
          - JPY
        invoiceExpiration:
          default: 900
          minimum: 60
          maximum: 2073600
          description: The time after which an invoice is considered expired if not paid. The value will be rounded down to a minute.
          allOf:
          - $ref: '#/components/schemas/TimeSpanSeconds'
        refundBOLT11Expiration:
          default: 30
          minimum: 0
          maximum: 3650
          description: The minimum expiry of BOLT11 invoices accepted for refunds by default. (in days)
          allOf:
          - $ref: '#/components/schemas/TimeSpanDays'
        displayExpirationTimer:
          default: 300
          minimum: 60
          maximum: 2073600
          description: The time left that will trigger the countdown timer on the checkout page to be shown. The value will be rounded down to a minute.
          allOf:
          - $ref: '#/components/schemas/TimeSpanSeconds'
        monitoringExpiration:
          default: 86400
          minimum: 600
          maximum: 2073600
          description: The time after which an invoice which has been paid but not confirmed will be considered invalid. The value will be rounded down to a minute.
          allOf:
          - $ref: '#/components/schemas/TimeSpanSeconds'
        speedPolicy:
          $ref: '#/components/schemas/SpeedPolicy'
        lightningDescriptionTemplate:
          type:
          - string
          - 'null'
          description: The BOLT11 description of the lightning invoice in the checkout. You can use placeholders '{StoreName}', '{ItemDescription}' and '{OrderId}'.
        paymentTolerance:
          type: number
          format: double
          minimum: 0.0
          maximum: 100.0
          default: 0.0
          description: Consider an invoice fully paid, even if the payment is missing 'x' % of the full amount.
        archived:
          type: boolean
          default: false
          description: If true, the store does not appear in the stores list by default.
        anyoneCanCreateInvoice:
          type: boolean
          default: false
          description: If true, then no authentication is needed to create invoices on this store.
        receipt:
          type:
          - object
          - 'null'
          description: Additional settings to customize the public receipt
          allOf:
          - $ref: '#/components/schemas/ReceiptOptions'
        lightningAmountInSatoshi:
          type: boolean
          default: false
          description: If true, lightning payment methods show amount in satoshi in the checkout page.
        lightningPrivateRouteHints:
          type: boolean
          default: false
          description: Should private route hints be included in the lightning payment of the checkout page.
        onChainWithLnInvoiceFallback:
          type: boolean
          default: false
          description: Unify on-chain and lightning payment URL.
        allowZeroAmountInvoices:
          type: boolean
          default: false
          description: If true, fixed-amount invoices with an amount of 0 can be created.
        redirectAutomatically:
          type: boolean
          default: false
          description: After successful payment, should the checkout page redirect the user automatically to the redirect URL of the invoice?
        showRecommendedFee:
          type: boolean
          default: true
        recommendedFeeBlockTarget:
          type: integer
          format: int32
          default: 1
          description: The fee rate recommendation in the checkout page for the on-chain payment to be confirmed after 'x' blocks.
        defaultLang:
          type: string
          default: en
          description: The default language to use in the checkout page. (The different translations available are listed [here](https://github.com/btcpayserver/btcpayserver/tree/master/BTCPayServer/wwwroot/locales)
        htmlTitle:
          type:
          - string
          - 'null'
          description: The HTML title of the checkout page (when you over the tab in your browser)
        networkFeeMode:
          $ref: '#/components/schemas/NetworkFeeMode'
        payJoinEnabled:
          type: boolean
          default: false
          description: If true, payjoin will be proposed in the checkout page if possible. ([More information](https://docs.btcpayserver.org/Payjoin/))
        autoDetectLanguage:
          type: boolean
          default: false
          description: If true, the language on the checkout page will adapt to the language defined by the user's browser settings
        showPayInWalletButton:
          type: boolean
          default: true
          description: If true, the "Pay in wallet" button will be shown on the checkout page (Checkout V2)
        showStoreHeader:
          type: boolean
          default: true
          description: If true, the store header will be shown on the checkout page (Checkout V2)
        celebratePayment:
          type: boolean
          default: true
          description: If true, payments on the checkout page will be celebrated with confetti (Checkout V2)
        playSoundOnPayment:
          type: boolean
          default: false
          description: If true, sounds on the checkout page will be enabled (Checkout V2)
        lazyPaymentMethods:
          type: boolean
          default: false
          description: If true, payment methods are enabled individually upon user interaction in the invoice
        defaultPaymentMethod:
          $ref: '#/components/schemas/PaymentMethodId'
        paymentMethodCriteria:
          type:
          - object
          - 'null'
          items:
            $ref: '#/components/schemas/PaymentMethodCriteriaData'
          description: The criteria required to activate specific payment methods.
    StoreData:
      allOf:
      - $ref: '#/components/schemas/StoreBaseData'
      - type: object
        properties:
          id:
            type: string
            description: The id of the store
  parameters:
    StoreId:
      name: storeId
      in: path
      required: true
      description: The store ID
      schema:
        $ref: '#/components/schemas/StoreId'
  securitySchemes:
    API_Key:
      type: apiKey
      description: "BTCPay Server supports authenticating and authorizing users through an API Key that is generated by them. Send the API Key as a header value to Authorization with the format: `token {token}`. For a smoother experience, you can generate a url that redirects users to an API key creation screen.\n\n The following permissions are available to the context of the user creating the API Key:\n\n* `btcpay.impersonation.canimpersonate`: Can impersonate users\n* `btcpay.user.candeleteuser`: Delete user\n* `btcpay.user.canmanagenotificationsforuser`: Manage your notifications\n* `btcpay.user.canmodifyprofile`: Manage your profile\n* `btcpay.user.canviewnotificationsforuser`: View your notifications\n* `btcpay.user.canviewprofile`: View your profile\n* `unrestricted`: Unrestricted access\n\nThe following permissions are available if the user is an administrator:\n\n* `btcpay.server.cancreatelightninginvoiceinternalnode`: Create invoices with internal lightning node\n* `btcpay.server.cancreateuser`: Create new users\n* `btcpay.server.canmanageusers`: Manage users\n* `btcpay.server.canmodifyserversettings`: Manage your server\n* `btcpay.server.canuseinternallightningnode`: Use the internal lightning node\n* `btcpay.server.canviewlightninginvoiceinternalnode`: View invoices from internal lightning node\n* `btcpay.server.canviewusers`: View users\n\nThe following permissions applies to all stores of the user, you can limit to a specific store with the following format: `btcpay.store.cancreateinvoice:6HSHAEU4iYWtjxtyRs9KyPjM9GAQp8kw2T9VWbGG1FnZ`:\n\n* `btcpay.store.canarchivepullpayments`: Archive your pull payments\n* `btcpay.store.canbroadcasttransactions`: Broadcast wallet transactions\n* `btcpay.store.cancanceltransactions`: Cancel wallet transactions\n* `btcpay.store.cancreateinvoice`: Create an invoice\n* `btcpay.store.cancreatelightninginvoice`: Create invoices from the lightning nodes associated with your stores\n* `btcpay.store.cancreatenonapprovedpullpayments`: Create non-approved pull payments\n* `btcpay.store.cancreatepullpayments`: Create pull payments\n* `btcpay.store.cancreatetransactions`: Create wallet transactions\n* `btcpay.store.cancreditsubscribers`: Credit your subscribers\n* `btcpay.store.canmanageinvoicestatus`: Manage invoice status\n* `btcpay.store.canmanagelegacyaccesstokens`: Manage legacy access tokens\n* `btcpay.store.canmanagepayouts`: Manage payouts\n* `btcpay.store.canmanagepullpayments`: Manage your pull payments\n* `btcpay.store.canmanagesubscribers`: Manage your subscribers\n* `btcpay.store.canmanagewallets`: Manage wallets\n* `btcpay.store.canmanagewalletsettings`: Manage wallet settings\n* `btcpay.store.canmanagewallettransactions`: Manage wallet transactions\n* `btcpay.store.canmodifyinvoices`: Modify invoices\n* `btcpay.store.canmodifyofferings`: Modify your offerings\n* `btcpay.store.canmodifypaymentrequests`: Modify your payment requests\n* `btcpay.store.canmodifystoresettings`: Modify your stores\n* `btcpay.store.cansendstoreemails`: Send store emails\n* `btcpay.store.cansigntransactions`: Sign wallet transactions\n* `btcpay.store.canuselightningnode`: Use the lightning nodes associated with your stores\n* `btcpay.store.canviewinvoices`: View invoices\n* `btcpay.store.canviewlightninginvoice`: View the lightning invoices associated with your stores\n* `btcpay.store.canviewofferings`: View your offerings\n* `btcpay.store.canviewpaymentrequests`: View your payment requests\n* `btcpay.store.canviewpayouts`: View payouts\n* `btcpay.store.canviewpullpayments`: View your pull payments\n* `btcpay.store.canviewreports`: View your reports\n* `btcpay.store.canviewstoresettings`: View your stores\n* `btcpay.store.canviewwallet`: View wallets\n* `btcpay.store.webhooks.canmodifywebhooks`: Modify stores webhooks\n\nNote that API Keys only limits permission of a user and can never expand it. If an API Key has the permission `btcpay.server.canmodifyserversettings` but that the user account creating this API Key is not administrator, the API Key will not be able to modify the server settings.\nSome permissions may include other permissions, see [this operation](#operation/permissionsMetadata).\n"
      name: Authorization
      in: header
    Basic:
      type: http
      description: BTCPay Server supports authenticating and authorizing users through the Basic HTTP authentication scheme during the first five minutes after account creation or when the user explicitly enables it. Send the user and password encoded in base64 with the format `Basic {base64(username:password)}`. Using this authentication method implicitly provides you with the `unrestricted` permission
      scheme: Basic
externalDocs:
  description: BTCPay Greenfield Plugins API
  url: https://docs.btcpayserver.org/API/Greenfield/Plugins/
x-provenance:
  method: harvested
  publisher: BTCPay Server
  source: https://docs.btcpayserver.org/API/Greenfield/v1/swagger.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)