BigCommerce Customer Batch Metafields API

openapi: 3.0.0
info:
  title: BigCommerce Abandoned Cart Emails Customer Batch Metafields 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: Customer Batch Metafields
paths:
  /customers/metafields:
    get:
      summary: BigCommerce Get All Customer Metafields
      tags:
      - Customer Batch Metafields
      description: Get all customer metafields.
      operationId: getallCustomersMetafields
      responses:
        '200':
          description: 'List of `Metafield` objects.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaFieldCollectionResponse'
        '500':
          description: Internal Server Error
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/MetafieldKeyParam'
      - $ref: '#/components/parameters/MetafieldKeyInParam'
      - $ref: '#/components/parameters/MetafieldNamespaceParam'
      - $ref: '#/components/parameters/MetafieldNamespaceInParam'
      - $ref: '#/components/parameters/DirectionParam'
    post:
      summary: BigCommerce Create Multiple Metafields
      tags:
      - Customer Batch Metafields
      description: Create multiple metafields.
      operationId: createCustomersMetafields
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                - $ref: '#/components/schemas/MetafieldBase_Post'
                - type: object
                  properties:
                    resource_id:
                      type: integer
                      example: 42
                      description: 'The ID for the resource with which the metafield is associated.

                        '
                  required:
                  - resource_id
        description: ''
      responses:
        '200':
          description: Response payload for the BigCommerce API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaFieldCollectionPostPutResponses'
        '422':
          description: 'Response object for metafields creation with partial success.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT'
        '500':
          description: Internal Server Error
    put:
      summary: BigCommerce Update Multiple Metafields
      tags:
      - Customer Batch Metafields
      description: Create multiple metafields.
      operationId: updateCustomersMetafields
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                - $ref: '#/components/schemas/MetafieldBase_Put'
                - type: object
                  properties:
                    id:
                      type: integer
                      example: 42
                      description: 'The ID of metafield to update.

                        '
                  required:
                  - id
        description: ''
      responses:
        '200':
          description: Response payload for the BigCommerce API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaFieldCollectionPostPutResponses'
        '422':
          description: 'Response object for metafields creation with partial success.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT'
        '500':
          description: Internal Server Error
    delete:
      summary: BigCommerce Delete All Metafields
      tags:
      - Customer Batch Metafields
      description: Delete all customer metafields.
      operationId: deleteCustomersMetafields
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: integer
        description: Metafields ID list.
      responses:
        '200':
          description: 'Response object for metafields deletion with success.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaFieldCollectionDeleteResponseSuccess'
        '422':
          description: 'Response object for metafields deletion with partial success.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_DELETE'
components:
  schemas:
    ErrorDetail:
      type: object
      description: 'Error detail response payload for the BigCommerce API.

        '
      example:
        '1': Unauthorized to delete
        '2': Metafield does not exist
    Error:
      type: object
      description: 'Error response payload for the BigCommerce API.

        '
      properties:
        status:
          type: integer
          description: 'The HTTP status code for the error.

            '
          example: 422
        title:
          type: string
          description: 'The error title.

            '
          example: Bulk operation has failed
        type:
          type: string
          description: 'The error type.

            '
          example: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes
        errors:
          $ref: '#/components/schemas/ErrorDetail'
    Metafield:
      type: object
      description: 'Common metafield properties.

        '
      properties:
        permission_set:
          type: string
          description: 'Determines the visibility and writeability of the field by other API consumers.

            | Value | Description |

            | : | : |

            | `app_only` | Private to the app that owns the field. |

            | `read` | Visible to other API consumers. |

            | `write` | Open for reading and writing by other API consumers. |

            | `read_and_sf_access` | Visible to other API consumers, including on storefront. |

            | `write_and_sf_access` | Open for reading and writing by other API consumers, including on storefront. |

            '
          enum:
          - app_only
          - read
          - write
          - read_and_sf_access
          - write_and_sf_access
        namespace:
          type: string
          description: 'Namespace for the metafield, for organizational purposes.

            '
          example: Sales Department
          minLength: 1
          maxLength: 64
        key:
          type: string
          description: 'The name of the field, for example: `location_id`, `color`.

            '
          minLength: 1
          maxLength: 64
          example: Staff Name
        value:
          type: string
          description: 'The value of the field, for example: `1`, `blue`.

            '
          minLength: 1
          maxLength: 65535
          example: Ronaldo
        description:
          type: string
          description: 'Description for the metafields.

            '
          example: order
          minLength: 0
          maxLength: 255
        resource_type:
          type: string
          description: 'The type of resource with which the metafield is associated.

            '
          enum:
          - brand
          - product
          - variant
          - category
          - cart
          - channel
          - location
          - order
          - customer
          example: cart
        resource_id:
          type: integer
          description: 'The unique identifier for the resource with which the metafield is associated.

            '
          example: 424242
          readOnly: true
        id:
          type: integer
          description: The unique identifier for the metafield.
        date_created:
          type: string
          format: date-time
          description: Date and time of the metafieldʼs creation.
          example: '2022-06-16T18:39:00+00:00'
        date_modified:
          type: string
          format: date-time
          description: Date and time when the metafield was last updated.
          example: '2022-06-16T18:39:00+00:00'
        owner_client_id:
          type: string
          description: Client ID for the metafieldʼs creator.
          example: ramciw4fnoz87it3ynjfif2zrkil5p
          readOnly: true
      required:
      - namespace
      - key
      - value
      - permission_set
      - resource_type
      - resource_id
      - description
      - id
      - date_created
      - date_modified
      x-interal: false
    MetafieldBase_Put:
      type: object
      description: 'Common Metafield properties.

        '
      x-internal: false
      properties:
        permission_set:
          type: string
          description: 'Determines the visibility and writeability of the field by other API consumers.

            | Value | Description |

            | : | : |

            | `app_only` | Private to the app that owns the field. |

            | `read` | Visible to other API consumers. |

            | `write` | Open for reading and writing by other API consumers. |

            | `read_and_sf_access` | Visible to other API consumers, including on the storefront. |

            | `write_and_sf_access` | Open for reading and writing by other API consumers, including on the storefront. |

            '
          enum:
          - app_only
          - read
          - write
          - read_and_sf_access
          - write_and_sf_access
        namespace:
          type: string
          description: 'Namespace for the metafield, for organizational purposes.

            '
          example: Sales Department
          minLength: 1
          maxLength: 64
        key:
          type: string
          description: 'The name of the field, for example: `location_id`, `color`.

            '
          minLength: 1
          maxLength: 64
          example: Staff Name
        value:
          type: string
          description: 'The value of the field, for example: `1`, `blue`.

            '
          minLength: 1
          maxLength: 65535
          example: Ronaldo
        description:
          type: string
          description: 'Description for the metafields.

            '
          minLength: 0
          maxLength: 255
          example: Name of Staff Member
    MetaFieldCollectionResponsePartialSuccess_POST_PUT:
      type: object
      description: 'Response payload for the BigCommerce API.

        '
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Metafield'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
        meta:
          $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta'
    WriteCollectionPartialSuccessMeta:
      type: object
      description: Additional data about the response.
      properties:
        total:
          type: integer
          description: 'Total number of items in the result set.

            '
          example: 3
        success:
          type: integer
          description: 'Total number of items that were successfully deleted.

            '
          example: 1
        failed:
          type: integer
          description: 'Total number of items that failed to be deleted.

            '
          example: 2
      title: Collection Meta
      x-internal: false
    MetafieldBase_Post:
      type: object
      description: 'Common Metafield properties.

        '
      x-internal: false
      properties:
        permission_set:
          type: string
          description: 'Determines the visibility and writeability of the field by other API consumers.

            | Value | Description |

            | : | : |

            | `app_only` | Private to the app that owns the field. |

            | `read` | Visible to other API consumers. |

            | `write` | Open for reading and writing by other API consumers. |

            | `read_and_sf_access` | Visible to other API consumers, including on the storefront. |

            | `write_and_sf_access` | Open for reading and writing by other API consumers, including on the storefront. |

            '
          enum:
          - app_only
          - read
          - write
          - read_and_sf_access
          - write_and_sf_access
        namespace:
          type: string
          description: 'Namespace for the metafield, for organizational purposes.

            '
          example: Sales Department
          minLength: 1
          maxLength: 64
        key:
          type: string
          description: 'The name of the field, for example: `location_id`, `color`.

            '
          minLength: 1
          maxLength: 64
          example: Staff Name
        value:
          type: string
          description: 'The value of the field, for example: `1`, `blue`.

            '
          minLength: 1
          maxLength: 65535
          example: Ronaldo
        description:
          type: string
          description: 'Description for the metafields.

            '
          minLength: 0
          maxLength: 255
          example: Name of Staff Member
      required:
      - permission_set
      - namespace
      - key
      - value
    CollectionMeta:
      type: object
      description: Data about the response, including pagination and collection totals.
      properties:
        pagination:
          type: object
          description: Data about the response, including pagination and collection totals.
          title: Pagination
          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: 1
            total_pages:
              type: integer
              description: 'The total number of pages in the collection.

                '
              example: 1
            links:
              type: object
              description: 'Pagination links for the previous and next parts of the whole collection.

                '
              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.

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

                    '
      additionalProperties: true
      title: Collection Meta
      x-internal: false
    MetaFieldCollectionResponsePartialSuccess_DELETE:
      type: object
      description: 'Response payload for the BigCommerce API.

        '
      properties:
        data:
          type: array
          items:
            type: integer
            description: 'The unique identifier for the metafield.

              '
          example:
          - 123
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
        meta:
          $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta'
      x-internal: false
    MetaFieldCollectionPostPutResponses:
      type: object
      description: Response payload for the BigCommerce API.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Metafield'
        errors:
          type: array
          description: Empty for 200 responses.
          example: []
        meta:
          $ref: '#/components/schemas/CollectionMeta'
    WriteCollectionSuccessMeta:
      type: object
      description: Additional data about the response.
      properties:
        total:
          type: integer
          description: 'Total number of items in the result set.

            '
          example: 3
        success:
          type: integer
          description: 'Total number of items that were successfully deleted.

            '
          example: 3
        failed:
          type: integer
          description: 'Total number of items that failed to be deleted.

            '
          example: 0
      title: Collection Meta
      x-internal: false
    MetaFieldCollectionDeleteResponseSuccess:
      type: object
      description: 'Response payload for the BigCommerce API.

        '
      properties:
        data:
          type: array
          items:
            type: integer
            description: 'The unique identifier for the metafield.

              '
          example:
          - 123
          - 124
          - 125
        errors:
          type: array
          description: Empty for 200 responses.
          example: []
        meta:
          $ref: '#/components/schemas/WriteCollectionSuccessMeta'
      x-internal: false
    MetaFieldCollectionResponse:
      type: object
      description: 'Response payload for the BigCommerce API.

        '
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Metafield'
      x-internal: false
  parameters:
    MetafieldNamespaceInParam:
      name: namespace:in
      in: query
      description: Filter based on comma-separated metafieldʼs namespaces. Could be used with vanilla `namespace` query parameter.
      required: false
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
    MetafieldNamespaceParam:
      name: namespace
      in: query
      description: Filter based on a metafieldʼs namespaces.
      required: false
      schema:
        type: string
    DirectionParam:
      name: direction
      description: 'Sort direction. Acceptable values are: `asc`, `desc`.

        '
      required: false
      in: query
      schema:
        type: string
        enum:
        - asc
        - desc
    MetafieldKeyInParam:
      name: key:in
      in: query
      description: Filter based on comma-separated metafieldʼs keys. Could be used with vanilla 'key' query parameter.
      required: false
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
    MetafieldKeyParam:
      name: key
      in: query
      description: Filter based on a metafieldʼs key.
      required: false
      schema:
        type: string
    PageParam:
      name: page
      description: 'Specifies the page number in a limited (paginated) list of products.

        '
      required: false
      in: query
      schema:
        type: integer
    LimitParam:
      name: limit
      description: 'Controls the number of items per page in a limited (paginated) list of products.

        '
      required: false
      in: query
      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