BigCommerce Consent API

openapi: 3.2.0
info:
  title: Bigcommerce Consent API
  version: '1.0'
  description: 'Operations tagged Consent across 2 of this provider''s published API definitions: customers-openapi-original.yml, storefront-cookie-consent-openapi-original.yml. Each path carries the servers of the definition it was published in.'
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
- url: https://{store_domain}/api/storefront
  variables:
    store_domain:
      default: your_store.example.com
      description: The [URL authority](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL#authority) of the storefront.
tags:
- name: Consent
paths:
  /customers/{customerId}/consent:
    parameters:
    - $ref: '#/components/parameters/customerId'
    get:
      description: Gets the status of a customerʼs consent to allow data collection by cookies and scripts while shopping on a storefront.
      summary: BigCommerce Get Customer Consent
      tags:
      - Consent
      operationId: getCustomerConsent
      deprecated: false
      responses:
        '200':
          $ref: '#/components/responses/consent_Resp'
        '401':
          description: Unauthorized - the v3 Auth client ID or token in the request are not a valid combination for this store.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Missing scope - the v3 Auth token is valid but does not have proper permissions to access this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid JSON request body - missing or invalid data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - X-Auth-Token: []
    put:
      description: Updates the status of a customerʼs consent to allow data collection by cookies and scripts while shopping on a storefront.
      summary: BigCommerce Update Customer Consent
      tags:
      - Consent
      operationId: updateCustomerConsent
      deprecated: false
      parameters:
      - name: Content-Type
        in: header
        required: false
        description: ''
        schema:
          type: string
          default: application/json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeclareCustomerConsentRequest'
        x-examples:
          application/json:
            allow:
            - essential
            deny: []
      responses:
        '200':
          $ref: '#/components/responses/consent_Resp'
        '401':
          description: Unauthorized - the v3 Auth client ID or token in the request are not a valid combination for this store.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Missing scope - the v3 Auth token is valid but does not have proper permissions to access this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid JSON request body - missing or invalid data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - X-Auth-Token: []
    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
  /consent:
    parameters: []
    post:
      summary: BigCommerce Set Cookie Consent Preferences
      tags:
      - Consent
      responses:
        '200':
          description: Consent Settings Saved
        '400':
          description: Invalid input
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentPreferences'
            examples:
              Example:
                value:
                  allow:
                  - 2
                  - 3
                  deny:
                  - 4
        description: Data sent to the [Update customer consent](/docs/rest-management/customers/customer-consent#update-customer-consent) endpoint when creating a customer during checkout.
        required: true
      description: "Sets the status of a customer's consent to allow data collection by cookies and scripts according to the following consent categories:\n\n\n  2. Analytics — These cookies provide statistical information on site usage so the store owner can improve the website over time.  \n  3. Functional — These cookies enable enhanced functionality, such as videos and live chat. If a shopper does not allow these, then some or all of these functions may not work properly. \n  4. Targeting; Advertising — These cookies allow merchants to create profiles or personalize content to enhance users' shopping experience.\n  \n  \nThis endpoint only works if the cookie consent feature is enabled. It is assumed the shopper has not consented to anything until a value is explicitly set. The request body must be populated with a complete set of allowed and denied categories.\n\nOnce set, consent preferences will be saved as a cookie for guest shoppers. Consent preferences will be persisted to a shopper's account to be used for future sessions once they have logged in. Consent preferences can also be managed using the [Update customer consent](/docs/rest-management/customers/customer-consent#update-customer-consent) endpoint.   \n\n> #### Note\n> * Substitute your storefront domain for `yourstore.example.com`. \n"
      operationId: postCookieConsent
    servers:
    - url: https://{store_domain}/api/storefront
      variables:
        store_domain:
          default: your_store.example.com
          description: The [URL authority](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL#authority) of the storefront.
components:
  schemas:
    consentAllow:
      title: consentAllow
      type: array
      uniqueItems: true
      minItems: 0
      example:
      - essential
      - targeting
      - functional
      items:
        type: string
        enum:
        - essential
        - functional
        - analytics
        - targeting
      x-internal: false
    DeclareCustomerConsentRequest:
      title: DeclareCustomerConsentRequest
      description: Request payload for the BigCommerce API.
      type: object
      properties:
        allow:
          $ref: '#/components/schemas/consentAllow'
        deny:
          $ref: '#/components/schemas/Deny'
      x-internal: false
    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
    Deny:
      title: Deny
      type: array
      uniqueItems: true
      minItems: 0
      example:
      - analytics
      items:
        type: string
        enum:
        - essential
        - functional
        - analytics
        - targeting
      x-internal: false
    consent_Full:
      title: consent_Full
      description: Response payload for the BigCommerce API.
      type: object
      properties:
        allow:
          $ref: '#/components/schemas/consentAllow'
        deny:
          $ref: '#/components/schemas/Deny'
        updated_at:
          description: The date of which the customer consent was last updated.
          type: string
          format: date-time
      x-internal: false
    ConsentPreferences:
      type: object
      title: ConsentPreferences
      description: 'List of allowed and denied consent categories. Must be populated with a complete set of allowed and denied categories.


        Configurable categories are:


        2 - Functional

        3 - Analytics

        4 - Targeting; Advertising


        For further definition of these categories, see [Scripts API](/docs/integrations/scripts).'
      properties:
        allow:
          type: array
          description: Explicitly allowed consent categories. Allowed values are 2, 3, 4.
          items:
            type: integer
            enum:
            - 2
            - 3
            - 4
            example: 3
        deny:
          type: array
          description: Denied consent categories. Allowed values are 2, 3, 4.
          items:
            type: integer
            enum:
            - 2
            - 3
            - 4
            example: 4
      required:
      - allow
      - deny
      x-internal: false
  responses:
    consent_Resp:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/consent_Full'
  parameters:
    customerId:
      name: customerId
      in: path
      required: true
      description: The ID of the customer.
      schema:
        type: integer
  securitySchemes:
    X-Auth-Token:
      name: X-Auth-Token
      description: '### OAuth scopes


        | UI Name | Permission | Parameter |

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

        | Customers | modify | `store_v2_customers` |

        | Customers | read-only | `store_v2_customers_read_only` |

        | Stored Payment Instruments | modify | `store_stored_payment_instruments` |

        | Stored Payment Instruments | read-only | `store_stored_payment_instruments_read_only` |


        ### 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
x-refined-from:
- customers-openapi-original.yml
- storefront-cookie-consent-openapi-original.yml