BigCommerce Order Settings API

openapi: 3.2.0
info:
  title: BigCommerce Orders V3 Order Settings API
  version: ''
  description: Manage order settings of BigCommerce stores.
  termsOfService: https://www.bigcommerce.com/terms
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
  license:
    name: ''
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
  variables:
    store_hash:
      default: store_hash
      description: Permanent ID of the BigCommerce store.
  description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Order Settings
paths:
  /orders/settings:
    parameters:
    - $ref: '#/components/parameters/Accept'
    get:
      summary: BigCommerce Get Global Order Settings
      description: Returns global order settings.
      operationId: getGlobalOrderSettings
      tags:
      - Order Settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/GlobalOrderSettings'
                - type: object
                  properties:
                    meta:
                      $ref: '#/components/schemas/metaEmpty_Full'
              examples: {}
        '400':
          description: Bad request. Authentication Required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
    put:
      summary: BigCommerce Update Global Order Settings
      description: Updates global order settings.
      operationId: updateGlobalOrderSettings
      parameters:
      - $ref: '#/components/parameters/ContentType'
      tags:
      - Order Settings
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GlobalOrderSettings'
            examples:
              EnableMultipleOrderNotifications:
                $ref: '#/components/examples/EnableMultipleOrderNotifications'
              DisableOrderPlacedNotificatons:
                $ref: '#/components/examples/GlobalOrderSettingsDisableOrderPlacedNotificatons'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - type: object
                - $ref: '#/components/schemas/GlobalOrderSettings'
                - properties:
                    meta:
                      $ref: '#/components/schemas/metaEmpty_Full'
        '400':
          description: Bad request. Authentication Required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
        '422':
          description: Order 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'
  /orders/settings/channels/{channel_id}:
    parameters:
    - $ref: '#/components/parameters/Accept'
    - name: channel_id
      in: path
      schema:
        type: string
      description: Channel ID
      required: true
    get:
      summary: BigCommerce Get Channel Order Settings
      description: Returns order settings for a specific channel.
      operationId: getChannelOrderSettings
      tags:
      - Order Settings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ChannelOrderSettings'
                - type: object
                  properties:
                    meta:
                      $ref: '#/components/schemas/metaEmpty_Full'
              examples: {}
        '400':
          description: Bad request. Authentication Required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
    put:
      summary: BigCommerce Update Channel Order Settings
      description: "Updates order settings for a specific channel.\n\n **Note:** You must override both notifications `email_addresses` or neither, i.e. either both notification `email_addresses` are an array of valid email addresses, or both `email_addresses` must be null. You may not have one set to an array of addresses and the other set to `null`."
      operationId: updateChannelOrderSettings
      parameters:
      - $ref: '#/components/parameters/ContentType'
      tags:
      - Order Settings
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChannelOrderSettings'
            examples:
              OverrideOrderPlacedEmailAddressesAndDisableForwardEmailAddresses:
                $ref: '#/components/examples/ChannelOrderSettingsOverrideOrderPlacedEmailAddressesAndDisableForwardEmail'
              ResetChannelSettings:
                $ref: '#/components/examples/ChannelOrderSettingsReset'
              DisableMultipleNotificatonsForChannels:
                $ref: '#/components/examples/ChannelOrderSettingsDisableBothNotifications'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ChannelOrderSettings'
                - type: object
                  properties:
                    meta:
                      $ref: '#/components/schemas/metaEmpty_Full'
        '400':
          description: Bad request. Authentication Required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
        '422':
          description: Order 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'
components:
  examples:
    GlobalOrderSettingsDisableOrderPlacedNotificatons:
      summary: Disable order placed notifications at global level
      value:
        notifications:
          order_placed:
            email_addresses: []
    EnableMultipleOrderNotifications:
      summary: Enable order placed and forward invoice notifications
      value:
        notifications:
          order_placed:
            email_addresses:
            - admin@example.com
            - another-email@example.com
          forward_invoice:
            email_addresses:
            - admin@example.com
            - another-email@example.com
    ChannelOrderSettingsOverrideOrderPlacedEmailAddressesAndDisableForwardEmail:
      summary: Override order placed email addresses and forward email addresses global value for channel
      value:
        notifications:
          order_placed:
            email_addresses:
            - admin@example.com
            - another-email@example.com
          forward_invoice:
            email_addresses: []
    ChannelOrderSettingsDisableBothNotifications:
      summary: Disable order placed notifications for channel
      value:
        notifications:
          order_placed:
            email_addresses: []
          forward_invoice:
            email_addresses: []
    ChannelOrderSettingsReset:
      summary: Reset order placed email addresses to global value for channel
      value:
        notifications:
          order_placed:
            email_addresses: null
          forward_invoice:
            email_addresses: null
  parameters:
    Accept:
      name: Accept
      in: header
      required: true
      description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.
      schema:
        type: string
        default: application/json
    ContentType:
      name: Content-Type
      in: header
      required: true
      description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.
      schema:
        type: string
        default: application/json
  schemas:
    GlobalOrderSettings:
      type: object
      properties:
        notifications:
          type: object
          description: Global notification settings.
          properties:
            order_placed:
              description: Global order notification settings.
              type: object
              properties:
                email_addresses:
                  description: Email addresses order notifications will be sent to. Empty array disables order notifications. Not nullable.
                  type: array
                  items:
                    type: string
            forward_invoice:
              description: Global order invoice forward settings.
              type: object
              properties:
                email_addresses:
                  description: Email addresses order invoices will be forwarded to. Empty array disables forwarding order invoices. Not nullable.
                  type: array
                  items:
                    type: string
      example:
        $ref: '#/components/examples/EnableMultipleOrderNotifications/value'
      x-tags:
      - Models
      title: GlobalOrderSettings
      x-examples:
        example-1:
          $ref: '#/components/examples/EnableMultipleOrderNotifications/value'
    betaErrorResponse:
      allOf:
      - $ref: '#/components/schemas/BaseError'
      - type: object
        properties:
          errors:
            type: object
      x-tags:
      - Models
    ChannelOrderSettings:
      type: object
      properties:
        notifications:
          type: object
          description: Channel notification settings.
          properties:
            order_placed:
              description: Channel order notification settings.
              type: object
              properties:
                email_addresses:
                  description: Email addresses channel order notifications will be sent to. If null will fall back to global value. Empty array disables order notifications for channel.
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
            forward_invoice:
              description: Channel order invoice forward settings.
              type: object
              properties:
                email_addresses:
                  description: Email addresses channel order invoices will be forwarded to. If null will fall back to global value. Empty array disables forwarding order invoices for channel.
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
      x-tags:
      - Models
      title: ChannelOrderSettings
    ErrorResponse400:
      type: object
      properties:
        schema:
          $ref: '#/components/schemas/betaErrorResponse'
      x-tags:
      - Models
    BaseError:
      type: object
      description: 'Error payload for the BigCommerce API.

        '
      properties:
        status:
          description: 'The HTTP status code.

            '
          type: integer
        title:
          description: 'The error title describing the particular error.

            '
          type: string
        type:
          type: string
      x-tags:
      - Models
    ErrorResponse422:
      type: object
      properties:
        schema:
          $ref: '#/components/schemas/betaErrorResponse'
      x-tags:
      - Models
    metaEmpty_Full:
      type: object
      title: Response meta
      properties: {}
      additionalProperties: true
      description: Response metadata.
  securitySchemes:
    X-Auth-Token:
      name: X-Auth-Token
      description: '### OAuth scopes


        | UI Name | Permission | Parameter |

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

        |  Order Transactions | read and modify `transactions` and `payment_methods` | `store_v2_transactions` |

        |  Order Transactions | read `transactions` and `payment_methods`  | `store_v2_transactions_read_only` |

        |  Orders | read and modify `payment_methods` |`store_v2_orders`|

        |  Orders | read `payment_methods` |`store_v2_orders_read_only`|


        ### Authentication header


        | Header | Argument | Description |

        |:-|:|:|

        | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). |


        ### Further reading


        For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests).


        For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes).


        For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).'
      type: apiKey
      in: header