openapi: 3.1.0
info:
  title: 'Admin Content: Custom Template Associations'
  version: 1.0.0
paths:
  /stores/{store_hash}/v3/storefront/custom-template-associations:
    get:
      operationId: getCustomTemplateAssociations
      summary: List Custom Template Associations
      description: Get a collection of the storeʼs custom template associations across all storefronts.
      tags:
        - customTemplateAssociations
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: channel_id
          in: query
          description: Return results or act upon only template associations in the specified channel.
          required: false
          schema:
            type: integer
        - name: entity_id:in
          in: query
          description: >-
            A comma-separated list of entity IDs to return or act upon. Must be used together with the `type` filter.
            Currently, all supported entities have integer-type IDs. 
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: type
          in: query
          description: Filter associations by type.
          required: false
          schema:
            $ref: '#/components/schemas/StorefrontCustomTemplateAssociationsGetParametersType'
        - name: limit
          in: query
          description: Number of results to return per page.
          required: false
          schema:
            type: integer
        - name: page
          in: query
          description: Which page number to return, based on the limit value. Used to paginate large collections.
          required: false
          schema:
            type: integer
        - name: is_valid
          in: query
          description: >-
            Optional toggle to filter for exclusively valid or invalid associations entries. An invalid entry is one
            where its file name does not match up to an existing custom layout file in the currently active theme for
            the channel.
          required: false
          schema:
            type: boolean
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

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

            | Themes |Read-only|`store_themes_read_only`|

            | Themes |Manage|`store_themes_manage`|


            ### 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: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Custom Template Associations_getCustomTemplateAssociations_Response_200'
    put:
      operationId: upsertCustomTemplateAssociations
      summary: Upsert Custom Template Associations
      description: >-
        Upsert new custom template associations data across all storefronts. If an existing record is found for the
        combination of channel ID, entity ID, and type, the existing record will be overwritten with the new template.
      tags:
        - customTemplateAssociations
      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 |

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

            | Themes |Read-only|`store_themes_read_only`|

            | Themes |Manage|`store_themes_manage`|


            ### 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: Success response for batch upsert of custom template associations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Custom Template Associations_upsertCustomTemplateAssociations_Response_200'
        '422':
          description: Error response for batch PUT of Custom template associations. Includes the errors for each reference ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CustomTemplateAssociationUpsert'
    delete:
      operationId: deleteCustomTemplateAssociations
      summary: Delete Custom Template Associations
      description: Delete custom template associations. At least one query parameter must be used.
      tags:
        - customTemplateAssociations
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: id:in
          in: query
          description: A comma-separated string that specifies a list of association IDs to delete.
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: channel_id
          in: query
          description: Return results or act upon only template associations in the specified channel.
          required: false
          schema:
            type: integer
        - name: type
          in: query
          description: Filter associations by type.
          required: false
          schema:
            $ref: '#/components/schemas/StorefrontCustomTemplateAssociationsDeleteParametersType'
        - name: entity_id:in
          in: query
          description: >-
            A comma-separated list of entity IDs to return or act upon. Must be used together with the `type` filter.
            Currently, all supported entities have integer-type IDs. 
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

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

            | Themes |Read-only|`store_themes_read_only`|

            | Themes |Manage|`store_themes_manage`|


            ### 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: No Content
          content:
            application/json:
              schema:
                type: object
                properties: {}
servers:
  - url: https://api.bigcommerce.com
    description: https://api.bigcommerce.com
components:
  schemas:
    StorefrontCustomTemplateAssociationsGetParametersType:
      type: string
      enum:
        - product
        - category
        - brand
        - page
      title: StorefrontCustomTemplateAssociationsGetParametersType
    CustomTemplateAssociationEntityType:
      type: string
      enum:
        - product
        - category
        - brand
        - page
      title: CustomTemplateAssociationEntityType
    CustomTemplateAssociation:
      type: object
      properties:
        id:
          type: integer
        channel_id:
          type: integer
        entity_type:
          $ref: '#/components/schemas/CustomTemplateAssociationEntityType'
        entity_id:
          type: integer
        file_name:
          type: string
        is_valid:
          type: boolean
          description: >-
            An invalid file name does not match with an existing custom layout file in the currently active theme for
            the channel. When an association is invalid the store will fallback to using the default for that entity
            type.
        date_created:
          type: string
        date_modified:
          type: string
      title: CustomTemplateAssociation
    MetaPaginationObjectPaginationLinks:
      type: object
      properties:
        next:
          type: string
        current:
          type: string
      title: MetaPaginationObjectPaginationLinks
    MetaPaginationObjectPagination:
      type: object
      properties:
        total:
          type: integer
        count:
          type: integer
        per_page:
          type: integer
        current_page:
          type: integer
        total_pages:
          type: integer
        links:
          $ref: '#/components/schemas/MetaPaginationObjectPaginationLinks'
      title: MetaPaginationObjectPagination
    MetaPaginationObject:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/MetaPaginationObjectPagination'
      title: MetaPaginationObject
    Custom Template Associations_getCustomTemplateAssociations_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CustomTemplateAssociation'
        meta:
          $ref: '#/components/schemas/MetaPaginationObject'
      title: Custom Template Associations_getCustomTemplateAssociations_Response_200
    CustomTemplateAssociationUpsertEntityType:
      type: string
      enum:
        - product
        - category
        - brand
        - page
      title: CustomTemplateAssociationUpsertEntityType
    CustomTemplateAssociationUpsert:
      type: object
      properties:
        channel_id:
          type: integer
        entity_type:
          $ref: '#/components/schemas/CustomTemplateAssociationUpsertEntityType'
        entity_id:
          type: integer
        file_name:
          type: string
      required:
        - channel_id
        - entity_type
        - entity_id
        - file_name
      title: CustomTemplateAssociationUpsert
    Custom Template Associations_upsertCustomTemplateAssociations_Response_200:
      type: object
      properties: {}
      title: Custom Template Associations_upsertCustomTemplateAssociations_Response_200
    DetailedErrors:
      type: object
      properties: {}
      title: DetailedErrors
    ErrorResponse:
      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/DetailedErrors'
      title: ErrorResponse
    StorefrontCustomTemplateAssociationsDeleteParametersType:
      type: string
      enum:
        - product
        - category
        - brand
        - page
      title: StorefrontCustomTemplateAssociationsDeleteParametersType
  securitySchemes:
    X-Auth-Token:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: >-
        ### OAuth scopes


        | UI Name | Permission | Parameter |

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

        | Themes |Read-only|`store_themes_read_only`|

        | Themes |Manage|`store_themes_manage`|


        ### 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).
