BigCommerce Custom Template Associations API

openapi: 3.0.0
info:
  title: BigCommerce Abandoned Cart Emails Custom Template Associations API
  version: 3.0.0
  termsOfService: https://www.bigcommerce.com/terms
  description: Abandoned Cart Emails V3 API managing Handlebars-based emails.
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
  variables:
    store_hash:
      default: store_hash
      description: Permanent ID of the BigCommerce store.
  description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Custom Template Associations
paths:
  /storefront/custom-template-associations:
    parameters:
    - $ref: '#/components/parameters/Accept'
    get:
      summary: BigCommerce Get Custom Template Associations
      tags:
      - Custom Template Associations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomTemplateAssociation'
                  meta:
                    $ref: '#/components/schemas/MetaPaginationObject'
              examples:
                example-1:
                  value:
                    data:
                    - id: 1
                      channel_id: 1
                      entity_type: product
                      entity_id: 123
                      file_name: custom-product-1.html
                    - id: 2
                      channel_id: 12345
                      entity_type: page
                      entity_id: 123
                      file_name: custom-page.html
                    meta:
                      pagination:
                        total: 246
                        count: 5
                        per_page: 5
                        current_page: 1
                        total_pages: 50
                        links:
                          next: ?limit=5&page=2
                          current: ?limit=5&page=1
      parameters:
      - schema:
          type: integer
        in: query
        name: channel_id
        description: Channel ID to return only custom template associations for a given Channel
      - schema:
          type: string
        in: query
        name: entity_id:in
        description: Filter by a list of entity IDs. Must be used together with "type" filter.
      - schema:
          type: integer
        in: query
        name: limit
        description: Number of results to return per page
      - schema:
          type: integer
        in: query
        name: page
        description: Which page number to return, based on the page size. Used to paginate large collections.
      - schema:
          type: string
          enum:
          - product
          - category
          - brand
          - page
        in: query
        name: type
        description: Filter associations by type
      - schema:
          type: boolean
        in: query
        name: is_valid
        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.
      description: Get a collection of the storeʼs custom template associations across all storefronts
      operationId: getCustomTemplateAssociations
    put:
      summary: BigCommerce Upsert Custom Template Associations
      tags:
      - Custom Template Associations
      responses:
        '200':
          description: Success response for batch upsert of custom template associations
          content:
            application/json:
              schema:
                type: object
        '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'
      parameters:
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              uniqueItems: true
              maxItems: 100
              minItems: 1
              items:
                $ref: '#/components/schemas/CustomTemplateAssociationUpsert'
            examples:
              example-1:
                value:
                - id: 1
                  channel_id: 1
                  entity_type: product
                  entity_id: 123
                  file_name: custom-product-1.html
                - id: 2
                  channel_id: 12345
                  entity_type: page
                  entity_id: 123
                  file_name: custom-page.html
        description: ''
      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.
      operationId: upsertCustomTemplateAssociations
    delete:
      summary: BigCommerce Delete Custom Template Associations
      tags:
      - Custom Template Associations
      responses:
        '204':
          description: No Content
      parameters:
      - schema:
          type: integer
        in: query
        name: id:in
        description: List of Association IDs to delete explicitly.
      - schema:
          type: integer
        in: query
        name: entity_id:in
        description: List of Entity IDs to delete explicitly. Must be used together with "type"
      - schema:
          type: integer
        in: query
        name: channel_id
        description: Channel ID provided to delete all custom template associations for a given Channel
      - schema:
          type: string
          enum:
          - product
          - category
          - brand
          - page
        in: query
        name: type
        description: Filter associations by type
      description: Delete custom template associations. At least one query parameter must be used.
      operationId: deleteCustomTemplateAssociations
components:
  parameters:
    Accept:
      name: Accept
      in: header
      required: true
      description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.
      schema:
        type: string
        default: application/json
    ContentType:
      name: Content-Type
      in: header
      required: true
      description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.
      schema:
        type: string
        default: application/json
  schemas:
    BaseError:
      type: object
      description: 'Error payload for the BigCommerce API.

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

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

            '
          type: string
        type:
          type: string
        instance:
          type: string
      x-internal: false
    MetaPaginationObject:
      type: object
      properties:
        pagination:
          type: object
          properties:
            total:
              type: integer
              example: 246
              minimum: 0
            count:
              type: integer
              example: 5
              minimum: 0
            per_page:
              type: integer
              example: 5
              minimum: 0
            current_page:
              type: integer
              example: 1
              minimum: 1
            total_pages:
              type: integer
              example: 50
              minimum: 0
            links:
              type: object
              properties:
                next:
                  type: string
                  example: ?limit=5&page=2
                current:
                  type: string
                  example: ?limit=5&page=1
      x-internal: false
    CustomTemplateAssociationUpsert:
      title: CustomTemplateAssociation
      type: object
      properties:
        channel_id:
          type: integer
        entity_type:
          type: string
          enum:
          - product
          - category
          - brand
          - page
        entity_id:
          type: integer
        file_name:
          type: string
          example: custom-product-1.html
      required:
      - channel_id
      - entity_type
      - entity_id
      - file_name
      x-internal: false
    CustomTemplateAssociation:
      title: CustomTemplateAssociation
      type: object
      properties:
        id:
          type: integer
        channel_id:
          type: integer
        entity_type:
          type: string
          enum:
          - product
          - category
          - brand
          - page
        entity_id:
          type: integer
        file_name:
          type: string
          example: custom-product-1.html
        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
      x-internal: false
    DetailedErrors:
      type: object
      additionalProperties:
        type: string
      x-internal: false
    ErrorResponse:
      allOf:
      - $ref: '#/components/schemas/BaseError'
      - type: object
        properties:
          errors:
            $ref: '#/components/schemas/DetailedErrors'
      x-internal: false
  securitySchemes:
    X-Auth-Token:
      name: X-Auth-Token
      description: '### OAuth scopes


        | UI Name | Permission | Parameter |

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

        | Information & Settings  | read-only  | `store_v2_information_read_only`|

        | Information & Settings  | modify     | `store_v2_information`          |


        ### Authentication header


        | Header | Argument | Description |

        |:-|:|:|

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


        ### Further reading


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


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


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