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

# Send events in bulk

> Sends up to 100 events and 1 MB in one call, each one as in POST /v1/events. It is not atomic: every event stands on its own, and results has the same order and length as events, with created, duplicate, or error in each position. Events are stored in the order sent; the order in which flows run is not guaranteed. The limit is 2000 events per second per API key, counted per event and not per request. Requires an API key with the write or events:write scope.



## OpenAPI

````yaml /openapi.en.json post /v1/events/bulk
openapi: 3.1.0
info:
  title: Bevits API
  version: 1.0.0
  description: >-
    Public API for querying CRM, purchase, and automation data from a Bevits
    organization, creating automations as drafts for review and activation,
    creating WhatsApp Official campaigns as drafts, and building customer
    segments and tags.
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://api.bevits.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: System
    description: API availability.
  - name: Identity
    description: Organization and API key identity.
  - name: Customers
    description: Customers and their relationships.
  - name: Segments
    description: Customer segments.
  - name: Purchases
    description: Purchases imported from integrations.
  - name: CRM data
    description: Tags and attribute definitions.
  - name: Automations
    description: Automation flows.
  - name: Campaigns
    description: Email campaigns.
  - name: Account and brand
    description: Account context, brand identity, and images.
  - name: Recipes
    description: Ready-made automations created from recipes, with undo.
  - name: Email templates
    description: Creating and importing email templates.
  - name: Events
    description: Custom events sent by the store and their types.
paths:
  /v1/events/bulk:
    post:
      tags:
        - Events
      summary: Send events in bulk
      description: >-
        Sends up to 100 events and 1 MB in one call, each one as in POST
        /v1/events. It is not atomic: every event stands on its own, and results
        has the same order and length as events, with created, duplicate, or
        error in each position. Events are stored in the order sent; the order
        in which flows run is not guaranteed. The limit is 2000 events per
        second per API key, counted per event and not per request. Requires an
        API key with the write or events:write scope.
      operationId: sendEvents
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventBatchRequest'
            example:
              events:
                - name: back_in_stock
                  customer:
                    email: ana@exemplo.com.br
                  properties:
                    product:
                      sku: CAM-01
                      name: Camiseta
                  external_id: stock_CAM-01_u_8842
                - name: back_in_stock
                  customer:
                    email: bruno@exemplo.com.br
                  properties:
                    product:
                      sku: CAM-01
                      name: Camiseta
                  external_id: stock_CAM-01_u_9120
      responses:
        '200':
          $ref: '#/components/responses/EventBatch'
        '400':
          $ref: '#/components/responses/InvalidBody'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/EventsScopeRequired'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '422':
          $ref: '#/components/responses/EventBatchValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      description: >-
        Unique key for the operation. Repeating the same key with the same body
        returns the original response instead of running it again.
      schema:
        type: string
  schemas:
    EventBatchRequest:
      type: object
      required:
        - events
      additionalProperties: false
      properties:
        events:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/EventInput'
    EventInput:
      type: object
      required:
        - name
        - customer
      additionalProperties: false
      properties:
        name:
          type: string
          pattern: ^[a-z][a-z0-9_]*$
          maxLength: 64
          description: >-
            What happened, such as order_shipped. Lowercase letters, digits, and
            underscores, starting with a letter.
        customer:
          $ref: '#/components/schemas/EventCustomerInput'
        properties:
          type: object
          additionalProperties: true
          description: >-
            Event details, free-form and with no reserved keys. Up to 200 keys
            in total, 5 levels of depth, and 100 items per list.
        occurred_at:
          type: string
          format: date-time
          description: >-
            When it happened, in ISO 8601 with offset. Default: the moment it is
            received.
        external_id:
          type: string
          minLength: 1
          maxLength: 255
          description: >-
            ID of this fact in your system. Sending the same name and
            external_id again within 90 days returns the original event and
            triggers nothing.
        backfill:
          type: boolean
          default: false
          description: >-
            If true, stores the event without triggering flows. Use it to import
            history.
    EventBatch:
      type: object
      required:
        - object
        - created
        - duplicate
        - failed
        - results
      properties:
        object:
          type: string
          const: event_batch
        created:
          type: integer
          minimum: 0
        duplicate:
          type: integer
          minimum: 0
        failed:
          type: integer
          minimum: 0
        results:
          type: array
          description: >-
            One result per event, in the same order and with the same length as
            events.
          items:
            $ref: '#/components/schemas/EventBatchResult'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
    RateLimitErrorResponse:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          required:
            - retry_after
          properties:
            retry_after:
              type: integer
              minimum: 1
              description: Seconds before retrying.
    EventCustomerInput:
      type: object
      description: >-
        Who it happened to. Send at least one identifier: id, external_id,
        tax_id, email, or phone.
      additionalProperties: false
      anyOf:
        - required:
            - id
        - required:
            - external_id
        - required:
            - tax_id
        - required:
            - email
        - required:
            - phone
      properties:
        id:
          type: string
          pattern: ^cus_[A-Za-z0-9_-]+$
          description: >-
            Bevits customer ID. An ID that does not exist responds 404 and no
            other identifier is tried.
        external_id:
          type: string
          minLength: 1
          maxLength: 255
          description: The customer's ID in your system, matched as exact text.
        tax_id:
          type: string
          minLength: 1
          maxLength: 32
          description: Valid CPF or CNPJ (Brazilian tax IDs), with or without punctuation.
        email:
          type: string
          format: email
          maxLength: 256
          description: Customer's email, matched in lowercase.
        phone:
          type: string
          minLength: 3
          maxLength: 32
          description: >-
            Phone in E.164, such as +5511988887777. Without a country code, the
            store's country is assumed.
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: Customer's name.
        attributes:
          type: object
          description: >-
            Customer attributes to set. Only the keys sent change; new
            attributes are created with the inferred type.
          additionalProperties:
            oneOf:
              - type: string
                maxLength: 256
              - type: number
              - type: boolean
        consent:
          type: object
          description: >-
            Marketing opt-in, read only when the event creates the customer.
            Without it, the customer is created without marketing opt-in.
          additionalProperties: false
          properties:
            email:
              type: boolean
            whatsapp:
              type: boolean
    EventBatchResult:
      type: object
      description: >-
        event is present when status is created or duplicate; error, when status
        is error.
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - created
            - duplicate
            - error
        event:
          $ref: '#/components/schemas/Event'
        error:
          $ref: '#/components/schemas/EventBatchError'
    Error:
      type: object
      required:
        - type
        - message
        - request_id
      properties:
        type:
          type: string
          enum:
            - authentication_error
            - conflict
            - internal_error
            - invalid_request
            - not_found
            - permission_denied
            - rate_limited
            - validation_error
        code:
          type: string
          description: >-
            Stable, machine-readable reason within type, such as
            invalid_event_name. Present when the error has a named reason.
        message:
          type: string
        param:
          type: string
          description: >-
            Full path of the offending field, such as customer.email or
            events[3].name.
        suggestion:
          type: string
          description: A value that would be accepted, when there is an obvious one.
        request_id:
          type: string
          pattern: ^req_[a-f0-9]{24}$
    Event:
      type: object
      required:
        - object
        - id
        - name
        - occurred_at
        - received_at
        - customer
        - flows
        - backfill
        - livemode
      properties:
        object:
          type: string
          const: event
        id:
          type: string
          pattern: ^evt_[A-Za-z0-9_-]+$
        name:
          type: string
        external_id:
          type: string
        occurred_at:
          type: string
          format: date-time
        received_at:
          type: string
          format: date-time
        customer:
          type: object
          description: >-
            Customer the event was linked to. A send-only key (events:write)
            receives id only.
          properties:
            id:
              type: string
              pattern: ^cus_[A-Za-z0-9_-]+$
              description: >-
                Absent when the event would create the customer and it was not
                created: in validation and in test mode.
            matched_by:
              type: string
              enum:
                - id
                - external_id
                - tax_id
                - email
                - phone
              description: >-
                Identifier that found the customer. Absent when the event
                created the customer.
            created:
              type: boolean
              description: true when the event created the customer.
            would_create:
              type: boolean
              const: true
              description: >-
                Present in validation and in test mode, when sending would
                create the customer.
        flows:
          type: array
          description: >-
            Active flows that listen to this event name. An empty list means no
            flow is listening.
          items:
            $ref: '#/components/schemas/EventFlow'
        properties:
          type: object
          additionalProperties: true
          description: Properties as they were sent. Absent after 30 days.
        backfill:
          type: boolean
        livemode:
          type: boolean
        warnings:
          type: array
          description: >-
            Present only when there is something to warn about. A warning never
            replaces an error.
          items:
            $ref: '#/components/schemas/EventWarning'
        duplicate:
          type: boolean
          const: true
          description: >-
            Present when the call returned an event that already existed with
            the same name and external_id.
    EventBatchError:
      type: object
      description: >-
        The same fields as the API error, without request_id. param starts with
        the position of the event, such as events[2].name.
      required:
        - type
        - message
      properties:
        type:
          type: string
          enum:
            - validation_error
            - not_found
            - internal_error
        code:
          type: string
        message:
          type: string
        param:
          type: string
        suggestion:
          type: string
    EventFlow:
      type: object
      required:
        - id
        - name
        - status
      properties:
        id:
          type: string
          pattern: ^flw_[A-Za-z0-9_-]+$
        name:
          type: string
        status:
          type: string
          enum:
            - queued
            - started
            - skipped
          description: >-
            queued is decided in the send response. When the event is read
            later, the flow shows as started or skipped.
        reason:
          type: string
          enum:
            - backfill
            - stale
            - filter_not_matched
            - test_mode
            - no_contact_channel
            - no_consent
            - flow_inactive
            - flow_error
            - dispatch_failed
          description: Why the flow was skipped. Present when status is skipped.
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/EventFlowWarning'
          description: >-
            What a started flow could not do and the sender can fix, such as a
            message skipped for a variable without a value. Present only when
            there is something to report.
    EventWarning:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - ambiguous_identifier
            - identifier_conflict
            - identifier_mismatch
            - payload_mismatch
        message:
          type: string
        param:
          type: string
    EventFlowWarning:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - missing_variable
          description: >-
            missing_variable: a message of the flow was skipped because a
            template variable had no value and no fallback text.
        message:
          type: string
        param:
          type: string
          description: >-
            The event property that was missing, such as
            properties.tracking.code. Absent when the variable is not from the
            event.
  responses:
    EventBatch:
      description: Result of each event, in the order sent.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EventBatch'
          example:
            object: event_batch
            created: 1
            duplicate: 0
            failed: 1
            results:
              - status: created
                event:
                  object: event
                  id: evt_01jd2v9k3m8q4r5s6t7u8v9w0x
                  name: back_in_stock
                  external_id: stock_CAM-01_u_8842
                  occurred_at: '2026-11-18T17:03:01.000Z'
                  received_at: '2026-11-18T17:03:01.000Z'
                  customer:
                    id: cus_ckabc123
                    matched_by: email
                    created: false
                  flows: []
                  properties:
                    product:
                      sku: CAM-01
                      name: Camiseta
                  backfill: false
                  livemode: true
              - status: error
                error:
                  type: validation_error
                  code: invalid_event_name
                  message: >-
                    Event names use lowercase letters, digits and underscores,
                    start with a letter and have at most 64 characters. Did you
                    mean "back_in_stock"?
                  param: events[1].name
                  suggestion: back_in_stock
    InvalidBody:
      description: >-
        Missing request body, a body that is not a JSON object, or an invalid
        route parameter.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing, invalid, expired, or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: authentication_error
              message: Invalid API key.
              request_id: req_07f6cdc3c20249d6afcd90b4
    EventsScopeRequired:
      description: The API key has neither the write scope nor the events:write scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: permission_denied
              code: missing_scope
              message: 'This API key needs one of these scopes: "write", "events:write".'
              param: scope
              request_id: req_07f6cdc3c20249d6afcd90b4
    IdempotencyConflict:
      description: The Idempotency-Key was already used with a different request body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    EventBatchValidationError:
      description: >-
        The batch was rejected before any event: events is empty, has more than
        100 items or more than 1 MB, or the body has an unknown field. An
        invalid event inside the batch does not cause this error; it shows up in
        results.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: validation_error
              code: batch_too_large
              message: A batch can have at most 1 MB. Split it into smaller batches.
              param: events
              request_id: req_07f6cdc3c20249d6afcd90b4
    RateLimited:
      description: Request limit exceeded.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitErrorResponse'
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  headers:
    RateLimitLimit:
      description: Total limit for the current window.
      schema:
        type: integer
        example: 600
    RateLimitRemaining:
      description: Requests remaining in the current window.
      schema:
        type: integer
        example: 599
    RateLimitReset:
      description: UTC instant when the current window ends.
      schema:
        type: string
        format: date-time
    RetryAfter:
      description: Seconds before retrying.
      schema:
        type: integer
        minimum: 1
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: bvt_live_...
      description: API key created in the organization settings.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.