openapi: 3.1.0
info:
  title: 'Admin Management: Promotion Settings'
  version: 1.0.0
paths:
  /stores/{store_hash}/v3/promotions/settings:
    get:
      operationId: getGlobalPromotionSettings
      summary: Get Global Promotion Settings
      description: Returns global promotion settings.
      tags:
        - promotionSettings
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            | Marketing | modify | `store_v2_marketing` |

            | Marketing | read-only | `store_v2_marketing_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see [API
            Accounts and OAuth Scopes](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example Requests](/developer/docs/overview/api-fundamentals/api-accounts).


            For more about BigCommerce OAuth scopes, see [API Accounts and OAuth
            Scopes](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalPromotionSettings'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
    put:
      operationId: updateGlobalPromotionSettings
      summary: Update Global Promotion Settings
      description: >-
        - Updates global promotion settings.

        - Note: *promotions_apply_on_products_with_custom_product_price*, *number_of_coupons_allowed_at_checkout* and
        *promotions_triggered_by_products_with_zero_product_price* can only be modified by enterprise accounts.
      tags:
        - promotionSettings
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

            |:--------|:-----------|:----------|

            | Marketing | modify | `store_v2_marketing` |

            | Marketing | read-only | `store_v2_marketing_read_only` |


            ### Authentication header


            | Header | Argument | Description |

            |:-------|:---------|:------------|

            | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see [API
            Accounts and OAuth Scopes](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example Requests](/developer/docs/overview/api-fundamentals/api-accounts).


            For more about BigCommerce OAuth scopes, see [API Accounts and OAuth
            Scopes](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalPromotionSettings'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
        '422':
          description: >-
            Promotion settings data is not valid. This is the result of missing required fields, or of invalid data. See
            the response for more details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse422'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GlobalPromotionSettings'
servers:
  - url: https://api.bigcommerce.com
    description: https://api.bigcommerce.com
components:
  schemas:
    GlobalPromotionSettings:
      type: object
      properties:
        promotions_apply_on_products_with_custom_product_price:
          type: boolean
          default: false
          description: |-
            - When the property is set to "true", promotions will apply for products with custom pricing.
            - When the property is set to "false", promotions will not apply for products with custom pricing.
            - Note: This field can only be edited for Enterprise Accounts.
        promotions_triggered_by_products_with_zero_product_price:
          type: boolean
          default: false
          description: |-
            - When the property is set to "true", promotions will be triggered by zero price products.
            - When the property is set to "false", promotions will not be triggered by zero price products.
            - Note: This field can only be edited for Enterprise Accounts.
        number_of_coupons_allowed_at_checkout:
          type: integer
          default: 1
          description: |-
            Specifies the number of coupons allowed at checkout on a single order.
            - Note: This field can only be edited for Enterprise Accounts.
        promotions_applied_on_original_product_price:
          type: boolean
          default: true
          description: >-
            - When the property is set to "true", promotions in a cart are calculated independently, each applied to the
            original price of the included products.

            - When the property is set to "false", promotions in a cart are calculated cumulatively, applied to the
            order sub-total based on your promotion order.
      required:
        - promotions_apply_on_products_with_custom_product_price
        - promotions_triggered_by_products_with_zero_product_price
        - number_of_coupons_allowed_at_checkout
        - promotions_applied_on_original_product_price
      title: GlobalPromotionSettings
    BetaErrorResponse400Error:
      type: object
      properties:
        message:
          type: string
      title: BetaErrorResponse400Error
    betaErrorResponse400:
      type: object
      properties:
        status:
          type: integer
          description: |
            The HTTP status code.
        title:
          type: string
          description: |
            The error title describing the particular error.
        error:
          $ref: '#/components/schemas/BetaErrorResponse400Error'
      description: |
        Error payload for the BigCommerce API.
      title: betaErrorResponse400
    ErrorResponse400:
      type: object
      properties:
        schema:
          $ref: '#/components/schemas/betaErrorResponse400'
      title: ErrorResponse400
    BetaErrorResponse422ErrorsItems:
      type: object
      properties:
        field:
          type: string
          description: The field that caused the validation error.
        message:
          type: string
          description: A specific error message describing the issue.
      title: BetaErrorResponse422ErrorsItems
    betaErrorResponse422:
      type: object
      properties:
        status:
          type: integer
          description: |
            The HTTP status code.
        title:
          type: string
          description: |
            The error title describing the particular error.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/BetaErrorResponse422ErrorsItems'
      description: |
        Error payload for the BigCommerce API.
      title: betaErrorResponse422
    ErrorResponse422:
      type: object
      properties:
        schema:
          $ref: '#/components/schemas/betaErrorResponse422'
      title: ErrorResponse422
  securitySchemes:
    X-Auth-Token:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: >-
        ### OAuth scopes


        | UI Name | Permission | Parameter |

        |:--------|:-----------|:----------|

        | Marketing | modify | `store_v2_marketing` |

        | Marketing | read-only | `store_v2_marketing_read_only` |


        ### Authentication header


        | Header | Argument | Description |

        |:-------|:---------|:------------|

        | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see [API Accounts
        and OAuth Scopes](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


        ### Further reading


        For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example
        Requests](/developer/docs/overview/api-fundamentals/api-accounts).


        For more about BigCommerce OAuth scopes, see [API Accounts and OAuth
        Scopes](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts).


        For a list of API status codes, see [API Status
        Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
