BigCommerce Form Field Values API

openapi: 3.0.0
info:
  title: BigCommerce Abandoned Cart Emails Form Field Values 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: Form Field Values
paths:
  /customers/form-field-values:
    get:
      responses:
        '200':
          $ref: '#/components/responses/FormFieldValueCollectionResponse'
        '422':
          description: The form field value was not valid. 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/ErrorResponse'
      summary: BigCommerce Get Customer Form Field Values
      description: 'Returns a list of form field values for the Customer or Customer Address object.


        To learn about adding and managing form fields, see [Adding and Editing Fields in the Account Signup Form](https://support.bigcommerce.com/s/article/Editing-Form-Fields).'
      operationId: getCustomersFormFieldValues
      tags:
      - Form Field Values
      parameters:
      - name: Accept
        in: header
        schema:
          type: string
          default: application/json
      - name: Content-Type
        in: header
        schema:
          type: string
          default: application/json
      - name: page
        in: query
        description: Page number. `page=1`
        schema:
          type: integer
      - in: query
        name: limit
        description: Items count per page. `limit=50`
        schema:
          type: number
      - in: query
        name: customer_id
        description: Filter by the customer ID.
        schema:
          type: integer
      - name: address_id
        in: query
        description: Filter by the ID of the customer address.
        schema:
          type: integer
      - name: field_name
        in: query
        description: Filter by the field name.
        schema:
          type: string
      - name: field_type
        in: query
        description: "Filter by the field type.\n * `checkboxes` - checkboxes field\n * `date` - date field\n * `multiline` - multiline text field\n * `numbers` - numbers only field\n * `password` - password field\n * `radiobuttons` - radio buttons field\n * `text` - text field\n * `picklist` - pick list field"
        schema:
          type: string
          enum:
          - checkboxes
          - date
          - multiline
          - numbers
          - password
          - radiobuttons
          - text
          - picklist
    put:
      responses:
        '200':
          $ref: '#/components/responses/FormFieldValuesResponse'
        '422':
          description: The form field value was not valid. 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/ErrorResponse'
      summary: BigCommerce Upsert Customer Form Field Values
      description: 'Updates form field values on the Customer or Customer Address objects. Multiple form field values can be updated in one call.


        Upsert checks for an existing record, if there is none it creates the record, if there is a matching record it updates that record.


        To learn more about editing form fields, see [Adding and Editing Fields in the Account Signup Form](https://support.bigcommerce.com/s/article/Editing-Form-Fields).


        **Limits**

        * Limit of 10 concurrent requests.'
      operationId: updateCustomerFormFieldValues
      tags:
      - Form Field Values
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/formFieldValue_Full'
            examples:
              Example:
                value:
                - customer_id: 12
                  name: Sales Rep
                  value: Miss Moneypenny
                - customer_id: 12
                  name: How did you hear about us?
                  value: Other
                - customer_id: 12
                  name: What is your favorite pizza topping?
                  value: Mushrooms
components:
  responses:
    FormFieldValuesResponse:
      description: ''
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  oneOf:
                  - allOf:
                    - type: object
                      title: Form Field Value Base
                      required:
                      - name
                      - value
                      properties:
                        name:
                          type: string
                          description: The form field name.
                          example: color
                        value:
                          oneOf:
                          - type: string
                            example: blue
                          - type: number
                            format: double
                            example: 12.345
                          - type: array
                            example:
                            - red
                            - green
                            - black
                            items:
                              type: string
                    - type: object
                      properties:
                        customer_id:
                          type: integer
                      required:
                      - customer_id
                    title: Customer Form Field Value
                  - allOf:
                    - type: object
                      title: Form Field Value Base
                      required:
                      - name
                      - value
                      properties:
                        name:
                          type: string
                          description: The form field name.
                          example: color
                        value:
                          oneOf:
                          - type: string
                            example: blue
                          - type: number
                            format: double
                            example: 12.345
                          - type: array
                            example:
                            - red
                            - green
                            - black
                            items:
                              type: string
                    - type: object
                      properties:
                        address_id:
                          type: integer
                          description: The Customer Address ID.
                      required:
                      - address_id
                    title: Customer Address Form Field Value
                  title: Form Field Value
              meta:
                $ref: '#/components/schemas/MetaOpen'
          examples:
            response:
              value:
                data:
                - customer_id: 12
                  name: Sales Rep
                  value: Miss Moneypenny
                - customer_id: 12
                  name: How did you hear about us?
                  value: Other
                - customer_id: 12
                  name: What is your favorite pizza topping?
                  value: Mushrooms
                meta: {}
    FormFieldValueCollectionResponse:
      description: ''
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  oneOf:
                  - allOf:
                    - type: object
                      title: Form Field Value Base
                      required:
                      - name
                      - value
                      properties:
                        name:
                          type: string
                          description: The form field name.
                          example: color
                        value:
                          oneOf:
                          - type: string
                            example: blue
                          - type: number
                            format: double
                            example: 12.345
                          - type: array
                            example:
                            - red
                            - green
                            - black
                            items:
                              type: string
                    - type: object
                      properties:
                        customer_id:
                          type: integer
                      required:
                      - customer_id
                    title: Customer Form Field Value
                  - allOf:
                    - type: object
                      title: Form Field Value Base
                      required:
                      - name
                      - value
                      properties:
                        name:
                          type: string
                          description: The form field name.
                          example: color
                        value:
                          oneOf:
                          - type: string
                            example: blue
                          - type: number
                            format: double
                            example: 12.345
                          - type: array
                            example:
                            - red
                            - green
                            - black
                            items:
                              type: string
                    - type: object
                      properties:
                        address_id:
                          type: integer
                          description: The Customer Address ID.
                      required:
                      - address_id
                    title: Customer Address Form Field Value
                  title: 'Form Field Value '
              meta:
                title: Collection Meta
                description: Data about the response, including pagination and collection totals.
                type: object
                properties:
                  pagination:
                    title: Pagination
                    description: Data about the response, including pagination and collection totals.
                    type: object
                    properties:
                      total:
                        description: Total number of items in the result set.
                        type: integer
                        format: int32
                      count:
                        description: Total number of items in the collection response.
                        type: integer
                        format: int32
                      per_page:
                        description: The amount of items returned in the collection per page, controlled by the limit parameter.
                        type: integer
                        format: int32
                      current_page:
                        description: The page you are currently on within the collection.
                        type: integer
                        format: int32
                      total_pages:
                        description: The total number of pages in the collection.
                        type: integer
                        format: int32
                      links:
                        title: Links
                        description: Pagination links for the previous and next parts of the whole collection.
                        type: object
                        properties:
                          previous:
                            description: Link to the previous page returned in the response.
                            type: string
                          current:
                            description: Link to the current page returned in the response.
                            type: string
                          next:
                            description: Link to the next page returned in the response.
                            type: string
          examples:
            Customer and Customer Address Form Fields example:
              value:
                data:
                - customer_id: 11
                  name: Sales Rep
                  value: James Bond
                - customer_id: 11
                  name: How did you hear about us?
                  value: Friend
                - customer_id: 11
                  name: What is your favorite pizza topping?
                  value: Black olives
                - customer_id: 12
                  name: Sales Rep
                  value: None
                - customer_id: 12
                  name: How did you hear about us?
                  value: Friend
                - customer_id: 12
                  name: What is your favorite pizza topping?
                  value: Mushrooms
                - customer_id: 13
                  name: Sales Rep
                  value: Felix Leiter
                - customer_id: 13
                  name: How did you hear about us?
                  value: Email
                - customer_id: 13
                  name: What is your favorite pizza topping?
                  value: Green pepper
                - customer_id: 13
                  name: Occupation
                  value: Housekeeper
                - address_id: 12
                  name: Special Delivery Instructions
                  value: Leave the package at the front door
                - customer_id: 14
                  name: Sales Rep
                  value: General Gogol
                - customer_id: 14
                  name: How did you hear about us?
                  value: Friend
                - customer_id: 14
                  name: What is your favorite pizza topping?
                  value: Extra cheese
                - address_id: 13
                  name: Special Delivery Instructions
                  value: Put the package in the mailbox
                meta:
                  pagination:
                    count: 15
                    current_page: 1
                    per_page: 50
                    total: 15
                    total_pages: 1
            Customer Form Fields example:
              value:
                data:
                - customer_id: 11
                  name: Sales Rep
                  value: James Bond
                - customer_id: 11
                  name: How did you hear about us?
                  value: Friend
                - customer_id: 11
                  name: What is your favorite pizza topping?
                  value: Black olives
                meta:
                  pagination:
                    count: 3
                    current_page: 1
                    per_page: 50
                    total: 3
                    total_pages: 1
            Customer Address Form Fields example:
              value:
                data:
                - address_id: 12
                  name: Special Delivery Instructions
                  value: Leave the package at the front door
                meta:
                  pagination:
                    count: 1
                    current_page: 1
                    per_page: 50
                    total: 1
                    total_pages: 1
  schemas:
    formFieldValue_Full:
      oneOf:
      - $ref: '#/components/schemas/formFieldValue_Customer'
      - $ref: '#/components/schemas/formFieldValue_Address'
      title: formFieldValue_Full
      x-internal: false
    MetaOpen:
      title: Response meta
      type: object
      properties: {}
      additionalProperties: true
      description: Response metadata.
    ErrorResponse:
      title: Error Response
      type: object
      properties:
        status:
          description: The HTTP status code.
          type: integer
          format: int32
        title:
          description: The error title describing the particular error.
          type: string
        type:
          description: A link to a list of BigCommerce API status codes.
          type: string
        instance:
          type: string
        errors:
          type: object
          additionalProperties:
            type: string
      x-internal: false
    formFieldValue_Address:
      title: Customer Address Form Field Value
      type: object
      required:
      - address_id
      - name
      - value
      properties:
        name:
          type: string
          description: The form field name.
          example: color
        value:
          oneOf:
          - type: string
            example: blue
          - type: number
            format: double
            example: 12.345
          - type: array
            example:
            - red
            - green
            - black
            items:
              type: string
        address_id:
          type: integer
          description: The Customer Address ID.
          example: 1
      x-internal: false
    formFieldValue_Customer:
      title: Customer Form Field Value
      type: object
      required:
      - customer_id
      - name
      - value
      properties:
        name:
          type: string
          description: The form field name.
          example: color
        value:
          oneOf:
          - type: string
            example: blue
          - type: number
            format: double
            example: 12.345
          - type: array
            example:
            - red
            - green
            - black
            items:
              type: string
        customer_id:
          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