openapi: 3.1.0
info:
  title: 'Admin Content: Widgets'
  version: 1.0.0
paths:
  /stores/{store_hash}/v3/content/placements:
    get:
      operationId: getPlacements
      summary: List Placements
      description: Returns a list of **Placements**.
      tags:
        - placement
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: page
          in: query
          description: |
            Specifies the page number in a limited (paginated) list of products.
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: |
            Controls the number of items per page in a limited (paginated) list of products.
          required: false
          schema:
            type: integer
        - name: widget_template_kind
          in: query
          description: The kind of widget template.
          required: false
          schema:
            type: string
        - name: template_file
          in: query
          description: 'The template file, for example: `pages/home`.'
          required: false
          schema:
            type: string
        - name: widget_uuid
          in: query
          description: The identifier for a specific widget.
          required: false
          schema:
            type: string
            format: uuid
        - name: widget_template_uuid
          in: query
          description: The identifier for a specific widget template.
          required: false
          schema:
            type: string
            format: uuid
        - name: channel_id:in
          in: query
          description: A comma-separated list of channel ids to filter the results by.
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: site_id:in
          in: query
          description: A comma-separated list of site IDs to filter the results by.
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

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

            |  Content | modify | `store_v2_content` |

            |  Content | read-only | `store_v2_content_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](/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#x-auth-token-header-example-requests).


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


            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: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Placement_getPlacements_Response_200'
        '422':
          description: |
            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/error_Base'
    post:
      operationId: createPlacement
      summary: Create Placement
      description: >-
        Creates a **Placement**.


        **Template Files**


        To view the list of values accepted by the `template_file` property, including **custom** templates, see
        [Placements](/developer/docs/admin/widgets-and-scripts#placements).
      tags:
        - placement
      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 |

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

            |  Content | modify | `store_v2_content` |

            |  Content | read-only | `store_v2_content_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](/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#x-auth-token-header-example-requests).


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


            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: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Placement_createPlacement_Response_200'
        '422':
          description: |
            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/error_Base'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/placement_Post'
  /stores/{store_hash}/v3/content/placements/{uuid}:
    get:
      operationId: getPlacement
      summary: Get Placement
      description: Returns a single **Placement**.
      tags:
        - placement
      parameters:
        - name: uuid
          in: path
          description: The identifier for a specific placement.
          required: true
          schema:
            type: string
            format: uuid
        - 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 |

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

            |  Content | modify | `store_v2_content` |

            |  Content | read-only | `store_v2_content_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](/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#x-auth-token-header-example-requests).


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


            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: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Placement_getPlacement_Response_200'
        '404':
          description: The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_Base'
        '422':
          description: |
            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/error_Base'
    put:
      operationId: updatePlacement
      summary: Update Placement
      description: Updates a **Placement**.
      tags:
        - placement
      parameters:
        - name: uuid
          in: path
          description: The identifier for a specific placement.
          required: true
          schema:
            type: string
            format: uuid
        - 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 |

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

            |  Content | modify | `store_v2_content` |

            |  Content | read-only | `store_v2_content_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](/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#x-auth-token-header-example-requests).


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


            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: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Placement_updatePlacement_Response_200'
        '404':
          description: The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_Base'
        '422':
          description: |
            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/error_Base'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/placement_Put'
    delete:
      operationId: deletePlacement
      summary: Delete Placement
      description: Deletes a **Placement**.
      tags:
        - placement
      parameters:
        - name: uuid
          in: path
          description: The identifier for a specific placement.
          required: true
          schema:
            type: string
            format: uuid
        - 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 |

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

            |  Content | modify | `store_v2_content` |

            |  Content | read-only | `store_v2_content_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](/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#x-auth-token-header-example-requests).


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


            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:
        '204':
          description: An empty response.
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '404':
          description: The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_Base'
        '422':
          description: |
            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/error_Base'
  /stores/{store_hash}/v3/content/regions:
    get:
      operationId: getContentRegions
      summary: List Theme Regions
      description: Returns a list of unique **Theme Regions** in a file.
      tags:
        - regions
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: template_file
          in: query
          description: 'The template file, for example: `templateFile=pages/home`.'
          required: true
          schema:
            type: string
        - name: channel_id
          in: query
          description: The channel ID.
          required: false
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

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

            |  Content | modify | `store_v2_content` |

            |  Content | read-only | `store_v2_content_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](/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#x-auth-token-header-example-requests).


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


            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: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Regions_getContentRegions_Response_200'
        '404':
          description: The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_Base'
        '422':
          description: |
            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/error_Base'
  /stores/{store_hash}/v3/content/widgets:
    get:
      operationId: getWidgets
      summary: List Widgets
      description: Returns a list of **Widgets**. Optional parameters can be passed in.
      tags:
        - widget
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: page
          in: query
          description: |
            Specifies the page number in a limited (paginated) list of products.
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: |
            Controls the number of items per page in a limited (paginated) list of products.
          required: false
          schema:
            type: integer
        - name: widget_template_kind
          in: query
          description: The kind of widget template.
          required: false
          schema:
            type: string
        - name: widget_template_uuid
          in: query
          description: The identifier for a specific widget template.
          required: false
          schema:
            type: string
            format: uuid
        - name: name
          in: query
          description: The URL-encoded name of the widget.
          required: false
          schema:
            type: string
        - name: name:in
          in: query
          description: >-
            Use to pass in comma-separated list of widget names. Example:
            `/widgets?name:in=test-widget-name,header%20images`
          required: false
          schema:
            type: array
            items:
              type: string
        - name: channel_id:in
          in: query
          description: A comma-separated list of channel ids to filter the results by.
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: site_id:in
          in: query
          description: A comma-separated list of site IDs to filter the results by.
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

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

            |  Content | modify | `store_v2_content` |

            |  Content | read-only | `store_v2_content_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](/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#x-auth-token-header-example-requests).


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


            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: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Widget_getWidgets_Response_200'
        '422':
          description: |
            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/error_Base'
    post:
      operationId: createWidget
      summary: Create Widget
      description: >-
        Creates a **Widget**.


        **Note:** There is a limit of 100,000 widgets per store and 150 widgets per page. For more information, see
        [Store Limits](https://support.bigcommerce.com/s/article/Platform-Limits#storelimits).
      tags:
        - widget
      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 |

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

            |  Content | modify | `store_v2_content` |

            |  Content | read-only | `store_v2_content_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](/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#x-auth-token-header-example-requests).


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


            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: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Widget_createWidget_Response_200'
        '422':
          description: |
            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/error_Base'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/widget_Post'
  /stores/{store_hash}/v3/content/widgets/{uuid}:
    get:
      operationId: getWidget
      summary: Get Widget
      description: Returns a single **Widget**.
      tags:
        - widget
      parameters:
        - name: uuid
          in: path
          description: The identifier for a specific widget.
          required: true
          schema:
            type: string
            format: uuid
        - 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 |

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

            |  Content | modify | `store_v2_content` |

            |  Content | read-only | `store_v2_content_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](/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#x-auth-token-header-example-requests).


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


            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: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Widget_getWidget_Response_200'
        '404':
          description: The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_Base'
        '422':
          description: |
            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/error_Base'
    put:
      operationId: updateWidget
      summary: Update Widget
      description: Updates a **Widget**.
      tags:
        - widget
      parameters:
        - name: uuid
          in: path
          description: The identifier for a specific widget.
          required: true
          schema:
            type: string
            format: uuid
        - 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 |

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

            |  Content | modify | `store_v2_content` |

            |  Content | read-only | `store_v2_content_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](/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#x-auth-token-header-example-requests).


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


            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: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Widget_updateWidget_Response_200'
        '404':
          description: The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_Base'
        '422':
          description: |
            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/error_Base'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/widget_Put'
    delete:
      operationId: deleteWidget
      summary: Delete Widget
      description: Deletes a **Widget**.
      tags:
        - widget
      parameters:
        - name: uuid
          in: path
          description: The identifier for a specific widget.
          required: true
          schema:
            type: string
            format: uuid
        - 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 |

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

            |  Content | modify | `store_v2_content` |

            |  Content | read-only | `store_v2_content_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](/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#x-auth-token-header-example-requests).


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


            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:
        '204':
          description: An empty response.
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '404':
          description: The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_Base'
        '422':
          description: |
            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/error_Base'
  /stores/{store_hash}/v3/content/widget-templates:
    get:
      operationId: getWidgetTemplates
      summary: List Widget Templates
      description: Returns a list of **Widget Templates**.
      tags:
        - widgetTemplate
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: page
          in: query
          description: |
            Specifies the page number in a limited (paginated) list of products.
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: |
            Controls the number of items per page in a limited (paginated) list of products.
          required: false
          schema:
            type: integer
        - name: widget_template_kind
          in: query
          description: The kind of widget template.
          required: false
          schema:
            type: string
        - name: channel_id:in
          in: query
          description: A comma-separated list of channel ids to filter the results by.
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

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

            |  Content | modify | `store_v2_content` |

            |  Content | read-only | `store_v2_content_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](/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#x-auth-token-header-example-requests).


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


            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: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Widget Template_getWidgetTemplates_Response_200'
        '422':
          description: |
            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/error_Base'
    post:
      operationId: createWidgetTemplate
      summary: Create Widget Template
      description: >-
        Creates a **Widget Template**.


        ***Note:*** *There is a limit of 1000 custom widget templates per channel, and a limit of 5000 across all
        channels.*


        **Required Fields**

        * name

        * template
      tags:
        - widgetTemplate
      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 |

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

            |  Content | modify | `store_v2_content` |

            |  Content | read-only | `store_v2_content_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](/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#x-auth-token-header-example-requests).


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


            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: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Widget Template_createWidgetTemplate_Response_200'
        '422':
          description: |
            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/error_Base'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/widgetTemplate_Post'
  /stores/{store_hash}/v3/content/widget-templates/{uuid}/preview:
    post:
      operationId: previewWidget
      summary: Render Widget Template
      description: Render a widget template and return the widget html.
      tags:
        - widgetTemplate
      parameters:
        - name: uuid
          in: path
          description: The identifier for a specific template.
          required: true
          schema:
            type: string
            format: uuid
        - 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 |

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

            |  Content | modify | `store_v2_content` |

            |  Content | read-only | `store_v2_content_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](/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#x-auth-token-header-example-requests).


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


            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
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WidgetTemplatePreviewResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WidgetTemplatePreview'
  /stores/{store_hash}/v3/content/widget-templates/{uuid}:
    get:
      operationId: getWidgetTemplate
      summary: Get Widget Template
      description: Returns a single **Widget Template**.
      tags:
        - widgetTemplate
      parameters:
        - name: uuid
          in: path
          description: The identifier for a specific template.
          required: true
          schema:
            type: string
            format: uuid
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: version_uuid
          in: query
          description: This is an optional query parameter used to fetch a specific widget template version.
          required: false
          schema:
            type: string
            format: uuid
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

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

            |  Content | modify | `store_v2_content` |

            |  Content | read-only | `store_v2_content_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](/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#x-auth-token-header-example-requests).


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


            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: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Widget Template_getWidgetTemplate_Response_200'
        '404':
          description: The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_Base'
        '422':
          description: |
            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/error_Base'
    put:
      operationId: updateWidgetTemplate
      summary: Update Widget Template
      description: Updates a **Widget Template**.
      tags:
        - widgetTemplate
      parameters:
        - name: uuid
          in: path
          description: The identifier for a specific template.
          required: true
          schema:
            type: string
            format: uuid
        - 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 |

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

            |  Content | modify | `store_v2_content` |

            |  Content | read-only | `store_v2_content_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](/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#x-auth-token-header-example-requests).


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


            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: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Widget Template_updateWidgetTemplate_Response_200'
        '404':
          description: The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_Base'
        '422':
          description: |
            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/error_Base'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/widgetTemplate_Put'
    delete:
      operationId: deleteWidgetTemplate
      summary: Delete Widget Template
      description: Deletes a **Widget Template**.
      tags:
        - widgetTemplate
      parameters:
        - name: uuid
          in: path
          description: The identifier for a specific template.
          required: true
          schema:
            type: string
            format: uuid
        - 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 |

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

            |  Content | modify | `store_v2_content` |

            |  Content | read-only | `store_v2_content_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](/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#x-auth-token-header-example-requests).


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


            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:
        '204':
          description: An empty response.
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '404':
          description: The resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_Base'
        '422':
          description: |
            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/error_Base'
servers:
  - url: https://api.bigcommerce.com
    description: https://api.bigcommerce.com
components:
  schemas:
    PlacementBaseStatus:
      type: string
      enum:
        - inactive
        - active
      default: inactive
      description: Sets the placement as either inactive or active.
      title: PlacementBaseStatus
    WidgetBaseWidgetConfiguration:
      type: object
      properties: {}
      description: The JSON data that populates the template.
      title: WidgetBaseWidgetConfiguration
    WidgetSchemaTabType:
      type: string
      enum:
        - tab
      description: The type of setting component to display.
      title: WidgetSchemaTabType
    WidgetSchemaTabSectionsItemsSettingsItemsType:
      type: string
      enum:
        - alignment
        - boolean
        - boxModel
        - code
        - color
        - imageManager
        - input
        - number
        - productId
        - productImage
        - range
        - regexInput
        - select
        - text
        - toggle
      description: >-
        The type of setting component to display. You can view the list of elements below to discover which are
        available to use.


        For examples of each type of setting, see [Page Builder > Schema
        Settings](/developer/docs/admin/widgets-and-scripts/input-reference/schema#alignment) in Theme Docs.
      title: WidgetSchemaTabSectionsItemsSettingsItemsType
    WidgetSchemaTabSectionsItemsSettingsItemsTypeMetaSelectOptionsItems:
      type: object
      properties:
        label:
          type: string
        value:
          type: string
      title: WidgetSchemaTabSectionsItemsSettingsItemsTypeMetaSelectOptionsItems
    WidgetSchemaTabSectionsItemsSettingsItemsTypeMeta:
      type: object
      properties:
        selectOptions:
          type: array
          items:
            $ref: '#/components/schemas/WidgetSchemaTabSectionsItemsSettingsItemsTypeMetaSelectOptionsItems'
      description: Additional information needed based on the selected setting type.
      title: WidgetSchemaTabSectionsItemsSettingsItemsTypeMeta
    WidgetSchemaTabSectionsItemsSettingsItemsConditional:
      type: object
      properties:
        key:
          type: string
          description: >-
            The ID of the `settings` object the conditional attribute is related to. The key must be defined within the
            same settings array as the conditional property. This ensures the conditional logic is scoped to the
            relevant settings group.
        operator:
          type: string
          description: >-
            Specifies the operation used to determine whether to display the setting. The `IN` operator is currently the
            only supported operator. The setting will be displayed if the conditional’s `value` property is equal to the
            selected value of the `selectOptions`. 
        value:
          type: array
          items:
            description: Any type
          description: A single-object array containing a value from the `typeMeta`'s `selectOptions`.
      description: >-
        An optional property that can be added to each setting to control whether it should be displayed to the user
        while editing in Page Builder. This does not clear the value in the setting, just controls the display of the
        setting.
      title: WidgetSchemaTabSectionsItemsSettingsItemsConditional
    WidgetSchemaTabSectionsItemsSettingsItems:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/WidgetSchemaTabSectionsItemsSettingsItemsType'
          description: >-
            The type of setting component to display. You can view the list of elements below to discover which are
            available to use.


            For examples of each type of setting, see [Page Builder > Schema
            Settings](/developer/docs/admin/widgets-and-scripts/input-reference/schema#alignment) in Theme Docs.
        label:
          type: string
          description: The user friendly message to inform the user how this setting will be used.
        id:
          type: string
          description: The variable name where the setting value will be available in the widget template.
        default:
          type: string
          description: >-
            The default value to use when rendering the widget for the first time. Make sure to set sensible defaults to
            make your widget easier to use.
        typeMeta:
          $ref: '#/components/schemas/WidgetSchemaTabSectionsItemsSettingsItemsTypeMeta'
          description: Additional information needed based on the selected setting type.
        conditional:
          $ref: '#/components/schemas/WidgetSchemaTabSectionsItemsSettingsItemsConditional'
          description: >-
            An optional property that can be added to each setting to control whether it should be displayed to the user
            while editing in Page Builder. This does not clear the value in the setting, just controls the display of
            the setting.
      description: >-
        For examples of each type of setting, see [Page Builder > Schema
        Settings](/developer/docs/admin/widgets-and-scripts/input-reference/schema#alignment) in Theme Docs.
      title: WidgetSchemaTabSectionsItemsSettingsItems
    WidgetSchemaTabSectionsItems:
      type: object
      properties:
        label:
          type: string
          description: The user-friendly message to inform the user how this setting will be used.
        settings:
          type: array
          items:
            $ref: '#/components/schemas/WidgetSchemaTabSectionsItemsSettingsItems'
          description: >-
            For examples of schema settings, see [Widget UI Input
            Types](/developer/docs/admin/widgets-and-scripts/input-reference/schema).
      title: WidgetSchemaTabSectionsItems
    widgetSchemaTab:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/WidgetSchemaTabType'
          description: The type of setting component to display.
        label:
          type: string
          description: The user-friendly message to inform the user how this setting will be used.
        sections:
          type: array
          items:
            $ref: '#/components/schemas/WidgetSchemaTabSectionsItems'
          description: Groups of related settings.
      description: '**Tab.** Use the **tab** settings type to create settings visible in Page Builder.'
      title: widgetSchemaTab
    WidgetSchemaArrayType:
      type: string
      enum:
        - array
      title: WidgetSchemaArrayType
    WidgetSchemaArrayThumbnail:
      type: object
      properties:
        type:
          type: string
        valueKey:
          type: string
      description: used to display an image stored at the specified attribute name
      title: WidgetSchemaArrayThumbnail
    WidgetSchemaHiddenType:
      type: string
      enum:
        - hidden
      title: WidgetSchemaHiddenType
    WidgetSchemaHiddenSettingsItemsType:
      type: string
      enum:
        - alignment
        - boolean
        - boxModel
        - code
        - color
        - imageManager
        - input
        - number
        - productId
        - productImage
        - range
        - regexInput
        - select
        - text
        - toggle
      description: >-
        The type of setting component to display. You can view the list of elements below to discover which are
        available to use.


        For examples of each type of setting, see [Page Builder > Schema
        Settings](/developer/docs/admin/widgets-and-scripts/input-reference/schema#alignment) in Theme Docs.
      title: WidgetSchemaHiddenSettingsItemsType
    WidgetSchemaHiddenSettingsItemsTypeMetaSelectOptionsItems:
      type: object
      properties:
        label:
          type: string
        value:
          type: string
      title: WidgetSchemaHiddenSettingsItemsTypeMetaSelectOptionsItems
    WidgetSchemaHiddenSettingsItemsTypeMeta:
      type: object
      properties:
        selectOptions:
          type: array
          items:
            $ref: '#/components/schemas/WidgetSchemaHiddenSettingsItemsTypeMetaSelectOptionsItems'
      description: Additional information needed based on the selected setting type.
      title: WidgetSchemaHiddenSettingsItemsTypeMeta
    WidgetSchemaHiddenSettingsItemsConditional:
      type: object
      properties:
        key:
          type: string
          description: >-
            The ID of the `settings` object the conditional attribute is related to. You must define the key within the
            same settings array as the conditional property to scope the conditional logic to the relevant settings
            group.
        operator:
          type: string
          description: >-
            Specifies the operation used to determine whether to display the setting. The `IN` operator is currently the
            only supported operator. The setting will be displayed if the conditional’s `value` property is equal to the
            selected value of the `selectOptions`. 
        value:
          type: array
          items:
            description: Any type
          description: A single-object array containing a value from the `typeMeta`'s `selectOptions`.
      description: >-
        An optional property that can be added to each setting to control whether it should be displayed to the user
        while editing in Page Builder. This does not clear the value in the setting, just controls the display of the
        setting.
      title: WidgetSchemaHiddenSettingsItemsConditional
    WidgetSchemaHiddenSettingsItems:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/WidgetSchemaHiddenSettingsItemsType'
          description: >-
            The type of setting component to display. You can view the list of elements below to discover which are
            available to use.


            For examples of each type of setting, see [Page Builder > Schema
            Settings](/developer/docs/admin/widgets-and-scripts/input-reference/schema#alignment) in Theme Docs.
        label:
          type: string
          description: The user friendly message to inform the user how this setting will be used.
        id:
          type: string
          description: The variable name where the setting value will be available in the widget template.
        default:
          type: string
          description: >-
            The default value to use when rendering the widget for the first time. Make sure to set sensible defaults to
            make your widget easier to use.
        typeMeta:
          $ref: '#/components/schemas/WidgetSchemaHiddenSettingsItemsTypeMeta'
          description: Additional information needed based on the selected setting type.
        conditional:
          $ref: '#/components/schemas/WidgetSchemaHiddenSettingsItemsConditional'
          description: >-
            An optional property that can be added to each setting to control whether it should be displayed to the user
            while editing in Page Builder. This does not clear the value in the setting, just controls the display of
            the setting.
      description: >-
        For examples of each type of setting, see [Page Builder > Schema
        Settings](/developer/docs/admin/widgets-and-scripts/input-reference/schema#alignment) in Theme Docs.
      title: WidgetSchemaHiddenSettingsItems
    widgetSchemaHidden:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/WidgetSchemaHiddenType'
        settings:
          type: array
          items:
            $ref: '#/components/schemas/WidgetSchemaHiddenSettingsItems'
      description: >-
        **Hidden.** Use the **hidden** settings type to create controls that have no user interface drawn in Page
        Builder. Hidden settings are not grouped into any other tabs or arrays.
      title: widgetSchemaHidden
    WidgetSchemaArraySchemaItems:
      oneOf:
        - $ref: '#/components/schemas/widgetSchemaHidden'
        - $ref: '#/components/schemas/widgetSchemaTab'
      title: WidgetSchemaArraySchemaItems
    widgetSchemaArray:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/WidgetSchemaArrayType'
        label:
          type: string
        id:
          type: string
        defaultCount:
          type: integer
          description: number of elements in the list to display by default.
        entryLabel:
          type: string
          description: name for each element in the list
        thumbnail:
          $ref: '#/components/schemas/WidgetSchemaArrayThumbnail'
          description: used to display an image stored at the specified attribute name
        schema:
          type: array
          items:
            $ref: '#/components/schemas/WidgetSchemaArraySchemaItems'
          description: The schema used for each element in the array.
      description: >-
        **Array.** Use the **array** settings type to build collections of elements within the widget. Each element in
        the array can contain tabs, sections, and an entire schema.
      title: widgetSchemaArray
    WidgetSchemaItems:
      oneOf:
        - $ref: '#/components/schemas/widgetSchemaTab'
        - $ref: '#/components/schemas/widgetSchemaArray'
        - $ref: '#/components/schemas/widgetSchemaHidden'
      title: WidgetSchemaItems
    widgetSchema:
      type: array
      items:
        $ref: '#/components/schemas/WidgetSchemaItems'
      description: >-
        The schema for the widget’s merchant-facing UI. For more information on the available schema settings, see
        [Widget UI Schema](/developer/docs/admin/widgets-and-scripts/input-reference/schema). 
      title: widgetSchema
    widgetTemplate_Full:
      type: object
      properties:
        name:
          type: string
          description: The user-friendly name.
        schema:
          $ref: '#/components/schemas/widgetSchema'
        template:
          type: string
          format: html
          description: The widget template HTML. Supports Handlebars and Paper helpers.
        storefront_api_query:
          type: string
          description: The GraphQL Storefront API query that provides widget data.
        uuid:
          type: string
          format: uuid
          description: The primary identifier.
        kind:
          type: string
          description: The kind of widget template.
        date_created:
          type: string
          format: date-time
          description: The date on which this object was initially created.
        date_modified:
          type: string
          format: date-time
          description: The date on which this object was last updated.
        current_version_uuid:
          type: string
          description: The identifier to the current version of this widget template.
        icon_name:
          type: string
          default: default
          description: A read-only value. Do not attempt to set or modify this value in a POST or PUT operation.
      title: widgetTemplate_Full
    widget_Full:
      type: object
      properties:
        name:
          type: string
          description: The user-friendly name.
        description:
          type: string
          description: The user-friendly description.
        widget_configuration:
          $ref: '#/components/schemas/WidgetBaseWidgetConfiguration'
          description: The JSON data that populates the template.
        uuid:
          type: string
          format: uuid
          description: The primary identifier.
        widget_template:
          $ref: '#/components/schemas/widgetTemplate_Full'
        date_created:
          type: string
          format: date-time
          description: The date on which this object was initially created.
        date_modified:
          type: string
          format: date-time
          description: The date on which this object was last updated.
        version_uuid:
          type: string
          description: The identifier of the widget template version associated with this widget.
        channel_id:
          type: integer
          description: The ID of the channel on which this widget exists.
      title: widget_Full
    placement_Full:
      type: object
      properties:
        entity_id:
          type: string
          description: >-
            The identifier of a page you would like to target. For product pages, choose product ID. For category pages,
            choose category ID. Home page does not support `entity_id`.
        sort_order:
          type: integer
          description: The sort order to control the position of a content widget in a region.
        region:
          type: string
          description: The name of the region in which to insert content widgets.
        status:
          $ref: '#/components/schemas/PlacementBaseStatus'
          default: inactive
          description: Sets the placement as either inactive or active.
        uuid:
          type: string
          format: uuid
          description: The primary identifier.
        template_file:
          type: string
          description: The template file that you would like to target.
        date_created:
          type: string
          format: date-time
          description: The date on which this object was initially created.
        date_modified:
          type: string
          format: date-time
          description: The date on which this object was last updated.
        channel_id:
          type: integer
          description: The ID of the channel on which this placement exists.
        widget:
          $ref: '#/components/schemas/widget_Full'
      title: placement_Full
    PaginationLinks:
      type: object
      properties:
        previous:
          type: string
          description: |
            Link to the previous page returned in the response.
        current:
          type: string
          description: |
            Link to the current page returned in the response.
        next:
          type: string
          description: |
            Link to the next page returned in the response.
      description: |
        Pagination links for the previous and next parts of the whole collection.
      title: PaginationLinks
    pagination:
      type: object
      properties:
        total:
          type: integer
          description: |
            Total number of items in the result set.
        count:
          type: integer
          description: |
            Total number of items in the collection response.
        per_page:
          type: integer
          description: |
            The amount of items returned in the collection per page, controlled by the limit parameter.
        current_page:
          type: integer
          description: |
            The page you are currently on within the collection.
        total_pages:
          type: integer
          description: |
            The total number of pages in the collection.
        links:
          $ref: '#/components/schemas/PaginationLinks'
          description: |
            Pagination links for the previous and next parts of the whole collection.
      description: |
        Data about the response, including pagination and collection totals.
      title: pagination
    metaCollection:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/pagination'
      description: Data about the response, including pagination and collection totals.
      title: metaCollection
    Placement_getPlacements_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/placement_Full'
        meta:
          $ref: '#/components/schemas/metaCollection'
      title: Placement_getPlacements_Response_200
    ErrorBaseErrors:
      type: object
      properties: {}
      title: ErrorBaseErrors
    error_Base:
      type: object
      properties:
        status:
          type: integer
          description: The HTTP status code.
        title:
          type: string
          description: The error title describing the particular error.
        type:
          type: string
        instance:
          type: string
        errors:
          $ref: '#/components/schemas/ErrorBaseErrors'
      description: Error payload for the BigCommerce API.
      title: error_Base
    placement_Post:
      type: object
      properties:
        entity_id:
          type: string
          description: >-
            The identifier of a page you would like to target. For product pages, choose product ID. For category pages,
            choose category ID. Home page does not support `entity_id`.
        sort_order:
          type: integer
          description: The sort order to control the position of a content widget in a region.
        region:
          type: string
          description: The name of the region in which to insert content widgets.
        status:
          $ref: '#/components/schemas/PlacementBaseStatus'
          default: inactive
          description: Sets the placement as either inactive or active.
        widget_uuid:
          type: string
          description: A widget identifier.
        template_file:
          type: string
          description: The template file that you would like to target.
        channel_id:
          type: integer
          description: The id of the channel on which to create this placement. Defaults to the first channel created on the store.
      required:
        - widget_uuid
        - template_file
      title: placement_Post
    Meta:
      type: object
      properties: {}
      description: Response metadata.
      title: Meta
    Placement_createPlacement_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/placement_Full'
        meta:
          $ref: '#/components/schemas/Meta'
      title: Placement_createPlacement_Response_200
    Placement_getPlacement_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/placement_Full'
        meta:
          $ref: '#/components/schemas/Meta'
      title: Placement_getPlacement_Response_200
    placement_Put:
      type: object
      properties:
        entity_id:
          type: string
          description: >-
            The identifier of a page you would like to target. For product pages, choose product ID. For category pages,
            choose category ID. Home page does not support `entity_id`.
        sort_order:
          type: integer
          description: The sort order to control the position of a content widget in a region.
        region:
          type: string
          description: The name of the region in which to insert content widgets.
        status:
          $ref: '#/components/schemas/PlacementBaseStatus'
          default: inactive
          description: Sets the placement as either inactive or active.
        template_file:
          type: string
          description: The template file that you would like to target.
        widget_uuid:
          type: string
          description: A widget identifier.
        channel_id:
          type: integer
          description: The ID of the channel on which this placement exists.
      title: placement_Put
    Placement_updatePlacement_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/placement_Full'
        meta:
          $ref: '#/components/schemas/Meta'
      title: Placement_updatePlacement_Response_200
    themeRegion:
      type: object
      properties:
        name:
          type: string
          description: The region name.
      title: themeRegion
    Regions_getContentRegions_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/themeRegion'
        meta:
          $ref: '#/components/schemas/Meta'
      title: Regions_getContentRegions_Response_200
    Widget_getWidgets_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/widget_Full'
        meta:
          $ref: '#/components/schemas/metaCollection'
      title: Widget_getWidgets_Response_200
    WidgetPostWidgetConfiguration:
      type: object
      properties: {}
      description: The JSON data that populates the template.
      title: WidgetPostWidgetConfiguration
    widget_Post:
      type: object
      properties:
        name:
          type: string
          description: User friendly name.
        description:
          type: string
          description: The user-friendly description.
        widget_configuration:
          $ref: '#/components/schemas/WidgetPostWidgetConfiguration'
          description: The JSON data that populates the template.
        widget_template_uuid:
          type: string
          description: The widget template UUID.
        channel_id:
          type: integer
          description: The ID of the channel on which to create this widget. Defaults to the first channel created on the store.
      required:
        - name
        - widget_template_uuid
      title: widget_Post
    Widget_createWidget_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/widget_Full'
        meta:
          $ref: '#/components/schemas/Meta'
      title: Widget_createWidget_Response_200
    Widget_getWidget_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/widget_Full'
        meta:
          $ref: '#/components/schemas/Meta'
      title: Widget_getWidget_Response_200
    widget_Put:
      type: object
      properties:
        name:
          type: string
          description: The user-friendly name.
        description:
          type: string
          description: The user-friendly description.
        widget_configuration:
          $ref: '#/components/schemas/WidgetBaseWidgetConfiguration'
          description: The JSON data that populates the template.
        widget_template_uuid:
          type: string
          description: The widget template UUID.
        channel_id:
          type: integer
        upgrade:
          type: boolean
          description: Upgrade the Widget to latest version of the WidgetTemplate.
      title: widget_Put
    Widget_updateWidget_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/widget_Full'
        meta:
          $ref: '#/components/schemas/Meta'
      title: Widget_updateWidget_Response_200
    Widget Template_getWidgetTemplates_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/widgetTemplate_Full'
        meta:
          $ref: '#/components/schemas/metaCollection'
      title: Widget Template_getWidgetTemplates_Response_200
    widgetTemplate_Post:
      type: object
      properties:
        name:
          type: string
          description: User-friendly name.
        schema:
          $ref: '#/components/schemas/widgetSchema'
        template:
          type: string
          format: html
          description: Handlebars HTML content. Also has access to Stencil Paper helpers.
        storefront_api_query:
          type: string
          description: The GraphQL Storefront API query that provides widget data.
        channel_id:
          type: integer
          description: The id of the channel on which to create this template. Defaults to the first channel created on the store.
      required:
        - name
        - template
      title: widgetTemplate_Post
    Widget Template_createWidgetTemplate_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/widgetTemplate_Full'
        meta:
          $ref: '#/components/schemas/Meta'
      title: Widget Template_createWidgetTemplate_Response_200
    WidgetTemplatePreviewWidgetConfiguration:
      type: object
      properties: {}
      description: The JSON data that populates the template.
      title: WidgetTemplatePreviewWidgetConfiguration
    WidgetTemplatePreview:
      type: object
      properties:
        widget_configuration:
          $ref: '#/components/schemas/WidgetTemplatePreviewWidgetConfiguration'
          description: The JSON data that populates the template.
      title: WidgetTemplatePreview
    WidgetTemplatePreviewResponseData:
      type: object
      properties:
        html:
          type: string
          format: html
          description: The HTML render of the widget template.
      title: WidgetTemplatePreviewResponseData
    WidgetTemplatePreviewResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/WidgetTemplatePreviewResponseData'
      title: WidgetTemplatePreviewResponse
    Widget Template_getWidgetTemplate_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/widgetTemplate_Full'
        meta:
          $ref: '#/components/schemas/Meta'
      title: Widget Template_getWidgetTemplate_Response_200
    widgetTemplate_Put:
      type: object
      properties:
        name:
          type: string
          description: The user-friendly name.
        schema:
          $ref: '#/components/schemas/widgetSchema'
        template:
          type: string
          format: html
          description: The widget template HTML. Supports Handlebars and Paper helpers.
        storefront_api_query:
          type: string
          description: The GraphQL Storefront API query that provides widget data.
        create_new_version:
          type: boolean
          description: Can be added to create a new widget template version instead of updating the current one.
        channel_id:
          type: integer
          description: The id of the channel on which to place this template.
      title: widgetTemplate_Put
    Widget Template_updateWidgetTemplate_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/widgetTemplate_Full'
        meta:
          $ref: '#/components/schemas/Meta'
      title: Widget Template_updateWidgetTemplate_Response_200
  securitySchemes:
    X-Auth-Token:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: >-
        ### OAuth scopes


        | UI Name | Permission | Parameter |

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

        |  Content | modify | `store_v2_content` |

        |  Content | read-only | `store_v2_content_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](/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#x-auth-token-header-example-requests).


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


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