> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masivo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update customers in bulk

> Update customers in bulk. You can update multiple customers at once, each with its own subset of fields (partial update): only the fields included for each customer are written, the rest keep their current values. Available fields are the same as the single customer update endpoint, except devices. Notes: date of birth and gender cannot be changed once set, and anonymous customers must use the identity endpoint.



## OpenAPI

````yaml PATCH /customers/bulk
openapi: 3.0.1
info:
  title: Masivo's REST API
  description: Learn how to use Masivo's REST API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://app.masivo.ai/api/storefront/v1
security:
  - bearerAuth: []
paths:
  /customers/bulk:
    patch:
      description: >-
        Update customers in bulk. You can update multiple customers at once,
        each with its own subset of fields (partial update): only the fields
        included for each customer are written, the rest keep their current
        values. Available fields are the same as the single customer update
        endpoint, except devices. Notes: date of birth and gender cannot be
        changed once set, and anonymous customers must use the identity
        endpoint.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - customers
              properties:
                customers:
                  type: array
                  minimum: 1
                  maximum: 1000
                  items:
                    $ref: '#/components/schemas/CustomerBulkUpdate'
            example:
              customers:
                - id: customer_123
                  name: John Doe
                  phone: +593 99 123 4567
                  tags:
                    segment: premium
                    loyalty_level: gold
                  metadata:
                    favorite_store: store_01
                - id: customer_456
                  country: Ecuador
                  document_type: EC_CC
                  document_number: '0102030405'
                  consent:
                    consent_timestamp: '2026-07-10T12:00:00Z'
                    customer_id: customer_456
                    purposes:
                      email_marketing: true
                      push_notifications: false
                    consent_string: COvFyGBOvFyGBAbAAAENAPCAAOAAAAAAAAAAAEEUACCKBBB
        required: true
      responses:
        '200':
          description: Customers updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Customers updated successfully
        '422':
          description: Invalid customer entry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CustomerBulkUpdate:
      type: object
      required:
        - id
      description: >-
        Partial update: only the fields included are written; at least one field
        besides id is required.
      properties:
        id:
          type: string
          description: Your customer unique identifier
          example: customer_123
        name:
          type: string
          description: Customer full name
          example: John Doe
        dob:
          type: string
          format: date-time
          nullable: true
          description: Date of birth. Cannot be changed once set.
          example: '1990-01-15T00:00:00Z'
        gender:
          type: string
          enum:
            - MALE
            - FEMALE
            - OTHER
          nullable: true
          description: Customer gender. Cannot be changed once set.
          example: MALE
        document_type:
          type: string
          nullable: true
          description: >-
            Identity document type (e.g. EC_CC, CO_CC, MX_CURP). Must be
            provided together with document_number.
          example: EC_CC
        document_number:
          type: string
          nullable: true
          description: >-
            Identity document number. Must be provided together with
            document_type.
          example: '0102030405'
        country:
          type: string
          nullable: true
          description: Customer country
          example: Ecuador
        phone:
          type: string
          nullable: true
          description: Phone number starting with + and country code, 10 to 15 digits
          example: +593 99 123 4567
        metadata:
          type: object
          description: Custom metadata as key-value pairs
          additionalProperties: true
          example:
            favorite_store: store_01
            acquisition_channel: instagram_ads
        tags:
          type: object
          description: Customer tags as key-value pairs (string, number or boolean values)
          additionalProperties: true
          example:
            segment: premium
            loyalty_level: gold
            visited_stores: 5
            newsletter_opt_in: true
        email_status:
          type: string
          enum:
            - VALID
            - BOUNCED
            - UNSUBSCRIBED
            - COMPLAINED
          description: Email deliverability status
          example: VALID
        consent:
          $ref: '#/components/schemas/Consent'
        platforms:
          type: array
          items:
            type: string
          description: Platforms the customer belongs to
          example:
            - mobile_app
            - web
    Error:
      required:
        - error
        - details
      type: object
      properties:
        error:
          type: string
        details:
          type: string
    Consent:
      type: object
      required:
        - consent_string
      properties:
        version:
          type: string
          description: IAB TCF version
          example: '2.0'
        consent_timestamp:
          type: string
          format: date-time
          description: The timestamp when consent was given
        customer_id:
          type: string
          description: The customer unique identifier
        purposes:
          $ref: '#/components/schemas/ConsentPurposes'
        vendors:
          type: object
          description: 'Vendor consent mapping (vendor_id: boolean)'
          additionalProperties:
            type: boolean
          example:
            vendor_123: true
            vendor_456: false
        consent_string:
          type: string
          description: >-
            IAB TCF consent string in base64url format, starting with 'CO',
            minimum 20 characters, maximum 500 characters
          example: COvFyGBOvFyGBAbAAAENAPCAAOAAAAAAAAAAAEEUACCKAAA
          minLength: 20
          maxLength: 500
          pattern: ^CO[A-Za-z0-9_-]+$
    ConsentPurposes:
      type: object
      properties:
        behavioral_campaigns:
          type: boolean
          description: Consent for behavioral campaigns
        coupon_campaigns:
          type: boolean
          description: Consent for coupon campaigns
        punchcard_campaigns:
          type: boolean
          description: Consent for punchcard campaigns
        email_marketing:
          type: boolean
          description: Consent for email marketing
        push_notifications:
          type: boolean
          description: Consent for push notifications
        link_tracking:
          type: boolean
          description: Consent for link tracking
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````