BigCommerce Custom Fields API

openapi: 3.0.0
info:
  title: BigCommerce Abandoned Cart Emails Custom Fields 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 Fields
paths:
  /catalog/products/{product_id}/custom-fields:
    parameters:
    - $ref: '#/components/parameters/ProductIdParam'
    get:
      tags:
      - Custom Fields
      summary: BigCommerce Get Product Custom Fields
      description: 'Returns a list of product *Custom Fields*. You can pass in optional parameters.


        **Note:**

        The default rate limit for this endpoint is 40 concurrent requests.'
      operationId: getProductCustomFields
      parameters:
      - name: include_fields
        in: query
        description: Fields to include in a comma-separated list; returned fields are the ID and specified fields.
        schema:
          type: string
      - name: exclude_fields
        in: query
        description: Fields to exclude in a comma-separated list; responses do not include specified fields, and you can not exclude the ID.
        schema:
          type: string
      - name: page
        in: query
        description: Specifies the page number in a limited (paginated) list of products.
        schema:
          type: integer
      - name: limit
        in: query
        description: Controls the number of items per page in a limited (paginated) list of products.
        schema:
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/CustomFieldsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/GeneralErrorWithErrors'
        '404':
          $ref: '#/components/responses/GeneralError'
        '405':
          $ref: '#/components/responses/MethodNotAllowedError'
    post:
      tags:
      - Custom Fields
      summary: BigCommerce Create a Product Custom Field
      description: 'Creates a *Custom Field*.


        **Required Fields:**

        - name

        - value


        **Name-Value Pair Uniqueness**

        - Every name-value pair must be unique inside a product.


        **Read-Only:**

        - id


        **Limits**

        - 200 custom fields per product limit.

        - 250 characters per custom field limit.


        **Note:**

        The default rate limit for this endpoint is 40 concurrent requests.'
      operationId: createProductCustomField
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customFieldPost'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/CustomFieldResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/GeneralErrorWithErrors'
        '404':
          $ref: '#/components/responses/GeneralError'
        '405':
          $ref: '#/components/responses/MethodNotAllowedError'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeError'
        '422':
          $ref: '#/components/responses/GeneralError'
  /catalog/products/{product_id}/custom-fields/{custom_field_id}:
    parameters:
    - $ref: '#/components/parameters/ProductIdParam'
    - $ref: '#/components/parameters/CustomFieldIdParam'
    get:
      tags:
      - Custom Fields
      summary: BigCommerce Get a Product Custom Field
      description: 'Returns a *Custom Field*.


        **Note:**

        The default rate limit for this endpoint is 40 concurrent requests.

        '
      operationId: getProductCustomField
      parameters:
      - name: include_fields
        in: query
        description: Fields to include in a comma-separated list; returned fields are the ID and specified fields.
        schema:
          type: string
      - name: exclude_fields
        in: query
        description: Fields to exclude in a comma-separated list; responses do not include specified fields, and you can not exclude the ID.
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/CustomFieldResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/GeneralErrorWithErrors'
        '404':
          $ref: '#/components/responses/GeneralError'
        '405':
          $ref: '#/components/responses/MethodNotAllowedError'
    put:
      tags:
      - Custom Fields
      summary: BigCommerce Update a Product Custom Field
      description: "Updates a *Custom Field*.\n\n**Required Fields**\n- none\n\n**Name-Value Pair Uniqueness**\n- Every name-value pair must be unique inside a product.\n\n**Read-Only**\n- id\n\n **Limits**\n- 200 custom fields per product limit.\n- 250 characters per custom field limit.\n- 40 concurrent requests default rate limit."
      operationId: updateProductCustomField
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customFieldPut'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/CustomFieldResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/GeneralErrorWithErrors'
        '404':
          $ref: '#/components/responses/GeneralError'
        '405':
          $ref: '#/components/responses/MethodNotAllowedError'
        '415':
          $ref: '#/components/responses/UnsupportedMediaTypeError'
        '422':
          $ref: '#/components/responses/GeneralError'
    delete:
      tags:
      - Custom Fields
      summary: BigCommerce Delete a Product Custom Field
      description: 'Deletes a product *Custom Field*.


        **Note:**

        The default rate limit for this endpoint is 40 concurrent requests.'
      operationId: deleteProductCustomField
      responses:
        '204':
          description: 204 No Content
          content: {}
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/GeneralErrorWithErrors'
        '404':
          $ref: '#/components/responses/GeneralError'
        '405':
          $ref: '#/components/responses/MethodNotAllowedError'
components:
  responses:
    CustomFieldResponse:
      description: Gets Custom field.
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/customFieldData'
              meta:
                $ref: '#/components/schemas/metaEmptyFull'
    CustomFieldsResponse:
      description: Gets array of Custom fields.
      content:
        application/json:
          schema:
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/customFieldData'
              meta:
                $ref: '#/components/schemas/metaCollectionFull'
    GeneralErrorWithErrors:
      description: General Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralErrorWithErrors'
    GeneralError:
      description: General Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
    UnauthorizedError:
      description: 401 Unauthorized
      content:
        plain/text:
          schema:
            type: string
    MethodNotAllowedError:
      description: 405 Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MethodNotAllowedError'
    UnsupportedMediaTypeError:
      description: 415 Unsupported Media Type
      content:
        text/html:
          schema:
            type: string
  schemas:
    GeneralErrorWithErrors:
      required:
      - status
      - title
      - type
      - errors
      title: Error Response
      type: object
      properties:
        status:
          type: integer
          description: The HTTP status code.
        title:
          type: string
          description: The error title describes the particular error.
        type:
          type: string
        errors:
          title: Detailed Errors
          type: object
          properties: {}
          additionalProperties: true
    GeneralError:
      required:
      - status
      - title
      - type
      title: Error Response
      type: object
      properties:
        status:
          type: integer
          description: The HTTP status code.
        title:
          type: string
          description: The error title describes the particular error.
        type:
          type: string
        code:
          type: integer
          description: The custom code of the error.
    MethodNotAllowedError:
      required:
      - status
      - title
      - type
      - detail
      title: Error Response
      type: object
      properties:
        status:
          type: integer
          description: The HTTP status code.
          example: 405
        title:
          type: string
          description: The error title describes the particular error.
        type:
          type: string
        detail:
          title: Detailed Errors
          type: string
          description: The detailed title describes the particular error.
    metaCollectionFull:
      title: metaCollectionFull
      type: object
      properties:
        pagination:
          type: object
          properties:
            total:
              type: integer
              description: 'Total number of items in the result set.

                '
              example: 36
            count:
              type: integer
              description: 'Total number of items in the collection response.

                '
              example: 36
            per_page:
              type: integer
              description: 'The amount of items returned in the collection per page, controlled by the limit parameter.

                '
              example: 50
            current_page:
              type: integer
              description: 'The page you are currently on within the collection.

                '
              example: 2
            total_pages:
              type: integer
              description: 'The total number of pages in the collection.

                '
              example: 3
            links:
              type: object
              properties:
                previous:
                  type: string
                  description: 'Link to the previous page returned in the response.

                    '
                  example: ?page=1&limit=50
                current:
                  type: string
                  description: 'Link to the current page returned in the response.

                    '
                  example: ?page=2&limit=50
                next:
                  type: string
                  description: 'Link to the next page returned in the response.

                    '
                  example: ?page=3&limit=50
              description: 'Pagination links for the previous and next parts of the whole collection.

                '
          description: Data about the response, including pagination and collection totals.
      description: Data about the response, including pagination and collection totals.
    customFieldPut:
      title: Custom Field Put
      type: object
      properties:
        name:
          maxLength: 250
          minLength: 1
          type: string
          description: 'The value of the field, shown on the storefront, orders, etc. This field is a requirement for /POST requests.

            '
          example: ISBN
        value:
          maxLength: 250
          minLength: 1
          type: string
          description: 'The value of the field, shown on the storefront, orders, etc. This field is a requirement for /POST requests.

            '
          example: '1234567890123'
      description: Payload for PUT request to update custom fields associated with a product.
    customFieldData:
      title: Product Custom Field Data
      type: object
      properties:
        id:
          minimum: 1
          type: integer
          description: The unique numeric ID of the custom field increments sequentially. Read-Only.
          example: 6
        name:
          maxLength: 250
          minLength: 1
          type: string
          description: 'The name of the field, shown on the storefront, orders, etc. This field is a requirement for /POST requests.

            '
          example: ISBN
        value:
          maxLength: 250
          minLength: 1
          type: string
          description: 'The value of the field, shown on the storefront, orders, etc. This field is a requirement for /POST requests.

            '
          example: '1234567890123'
      description: Gets custom fields associated with a product. These allow you to specify additional information that will appear on the product’s page, such as a book’s ISBN or a DVD’s release date.
    metaEmptyFull:
      type: object
      title: Response meta
      properties: {}
      additionalProperties: true
      description: Response metadata.
    customFieldPost:
      title: Custom Field Post
      required:
      - name
      - value
      type: object
      properties:
        name:
          maxLength: 250
          minLength: 1
          type: string
          description: 'The name of the field, shown on the storefront, orders, etc. This field is a requirement for /POST requests.

            '
          example: ISBN
        value:
          maxLength: 250
          minLength: 1
          type: string
          description: 'The value of the field, shown on the storefront, orders, etc. This field is a requirement for /POST requests.

            '
          example: '1234567890123'
      description: Payload for POST request to create custom fields associated with a product.
  parameters:
    CustomFieldIdParam:
      name: custom_field_id
      description: 'The ID of the `CustomField`.

        '
      required: true
      in: path
      schema:
        type: integer
    ProductIdParam:
      name: product_id
      in: path
      description: 'The ID of the `Product` to which the resource belongs.

        '
      required: true
      schema:
        type: integer
  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