BTCPay Server Stores API

openapi: 3.0.0
info:
  title: BTCPay Greenfield API Keys Stores 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: 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
      description: 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:
    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
            nullable: false
            description: The json path of the property which failed validation
          message:
            type: string
            nullable: false
            description: User friendly error message about the validation
    ApplicationUserData:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          description: The id of the user
          nullable: false
        email:
          type: string
          description: The email of the user
          nullable: false
        name:
          type: string
          description: The name of the user
          nullable: true
        imageUrl:
          type: string
          description: The profile picture URL of the user
          nullable: true
        invitationUrl:
          type: string
          description: The pending invitation URL of the user
          nullable: true
        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
          nullable: true
          description: Per-user override for the max number of stores this user can create. Null means the server default applies
        created:
          type: number
          nullable: true
          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
        roles:
          type: array
          nullable: false
          items:
            type: string
          description: The roles of the user
    UnixTimestamp:
      type: number
      format: int32
      example: 1592312018
      description: A unix timestamp in seconds
    TimeSpanSeconds:
      allOf:
      - $ref: '#/components/schemas/TimeSpan'
      format: seconds
      description: A span of times in seconds
    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
    TimeSpan:
      type: number
      format: int32
      example: 90
    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
          nullable: false
          example: Owner
        role:
          description: The role's name
          type: string
          nullable: false
          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
    StoreDataList:
      type: array
      items:
        $ref: '#/components/schemas/StoreData'
    PaymentMethodCriteriaData:
      type: object
      properties:
        paymentMethodId:
          type: string
          allOf:
          - $ref: '#/components/schemas/PaymentMethodId'
          nullable: false
        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
    StoreBaseData:
      type: object
      x-abstract: true
      additionalProperties: false
      properties:
        name:
          type: string
          description: The name of the store
        website:
          type: string
          nullable: true
          description: The absolute url of the store
          format: url
        supportUrl:
          type: string
          nullable: true
          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
          nullable: true
          description: Absolute URL to a logo file or a reference to an uploaded file id with `fileid:ID`
          format: uri
        cssUrl:
          type: string
          nullable: true
          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
          nullable: true
          description: Absolute URL to a sound file or a reference to an uploaded file id with `fileid:ID`
          format: uri
        brandColor:
          type: string
          description: The brand color of the store in HEX format
          nullable: true
          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:
          - JPY
          - EUR
        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
          nullable: true
          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
          nullable: true
          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.
        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
          nullable: true
          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
          nullable: true
          items:
            $ref: '#/components/schemas/PaymentMethodCriteriaData'
          description: The criteria required to activate specific payment methods.
    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:
      - MultiplePaymentsOnly
      - Always
      - Never
      enum:
      - MultiplePaymentsOnly
      - Always
      - Never
    TimeSpanDays:
      allOf:
      - $ref: '#/components/schemas/TimeSpan'
      format: days
      description: A span of times in days
    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
      - MediumSpeed
      - LowSpeed
      - LowMediumSpeed
      enum:
      - HighSpeed
      - MediumSpeed
      - LowSpeed
      - LowMediumSpeed
    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
    StoreData:
      allOf:
      - $ref: '#/components/schemas/StoreBaseData'
      - type: object
        properties:
          id:
            type: string
            description: The id of the store
            nullable: false
    ReceiptOptions:
      type: object
      additionalProperties: false
      properties:
        enabled:
          type: boolean
          nullable: true
          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
          nullable: true
          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
          nullable: true
          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)
  parameters:
    StoreId:
      name: storeId
      in: path
      required: true
      description: The store ID
      schema:
        $ref: '#/components/schemas/StoreId'
  securitySchemes:
    API_Key:
      type: apiKey
      in: header
      name: Authorization
      description: 'BTCPay Server API key. Format: ''token {apiKey}'''
    Basic:
      type: http
      scheme: basic
      description: HTTP Basic Authentication with email and password
externalDocs:
  description: Check out our examples on how to use the API
  url: https://docs.btcpayserver.org/Development/GreenFieldExample/