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

# Remove customers from a segment

> Takes up to 500 customers out of a segment. They are also left out of its conditions, so a filter segment doesn't bring them back; adding them again undoes the removal. The change applies to the campaigns that use the segment. RFM segments are kept up to date by Bevits. Requires an API key with the write scope.



## OpenAPI

````yaml /openapi.en.json post /v1/segments/{segment_id}/customers/remove
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/segments/{segment_id}/customers/remove:
    post:
      tags:
        - Segments
      summary: Remove customers from a segment
      description: >-
        Takes up to 500 customers out of a segment. They are also left out of
        its conditions, so a filter segment doesn't bring them back; adding them
        again undoes the removal. The change applies to the campaigns that use
        the segment. RFM segments are kept up to date by Bevits. Requires an API
        key with the write scope.
      operationId: removeSegmentCustomers
      parameters:
        - $ref: '#/components/parameters/SegmentId'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentCustomersRequest'
            example:
              customer_ids:
                - cus_3j9x0a
      responses:
        '200':
          $ref: '#/components/responses/SegmentMembership'
        '400':
          $ref: '#/components/responses/InvalidBody'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/WriteScopeRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '422':
          $ref: '#/components/responses/SegmentValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    SegmentId:
      name: segment_id
      in: path
      required: true
      description: Public segment ID.
      schema:
        type: string
        pattern: ^seg_[A-Za-z0-9_-]+$
    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:
    SegmentCustomersRequest:
      type: object
      required:
        - customer_ids
      properties:
        customer_ids:
          type: array
          items:
            type: string
            pattern: ^cus_[A-Za-z0-9_-]+$
          minItems: 1
          maxItems: 500
          description: Customer IDs (cus_...), up to 500 per call.
        operation_id:
          $ref: '#/components/schemas/OperationId'
    OperationId:
      type: string
      minLength: 8
      maxLength: 128
      description: >-
        Optional unique id for this call, such as a UUID. Reuse the same value
        only to retry the same call: the retry returns the first result instead
        of creating again. The same value with a different body is rejected with
        409.
    SegmentMembership:
      type: object
      required:
        - object
        - segment
        - action
        - changed
        - next_step
      properties:
        object:
          type: string
          const: segment_membership
        segment:
          $ref: '#/components/schemas/Segment'
        action:
          type: string
          enum:
            - add
            - remove
        changed:
          type: integer
          minimum: 0
          description: >-
            Customers that changed. When adding, customers already in the
            segment are not counted.
        next_step:
          type: string
    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.
    Segment:
      type: object
      required:
        - object
        - id
        - created_at
        - updated_at
        - html_url
      properties:
        object:
          type: string
          const: segment
        id:
          type: string
          pattern: ^seg_[A-Za-z0-9_-]+$
        name:
          type: string
        description:
          type: string
        type:
          type: string
          enum:
            - static
            - filters
            - rfm
            - campaign_engagement
          description: >-
            static: customers added by hand. filters: whoever matches the
            conditions at the moment, plus those added by hand. rfm: kept up to
            date by Bevits. campaign_engagement: campaign engagement recorded at
            creation.
        match:
          $ref: '#/components/schemas/SegmentMatch'
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/SegmentCondition'
          description: >-
            Conditions of a filter segment, in the same format creation and
            update take.
        customer_count:
          type: integer
          minimum: 0
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        html_url:
          type: string
          format: uri
    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}$
    SegmentMatch:
      type: string
      enum:
        - all
        - any
      description: >-
        all: customers who match every condition. any: customers who match at
        least one.
    SegmentCondition:
      description: >-
        One condition of a filter segment. The same format goes into create,
        update, and preview and comes back in GET /v1/segments/{segment_id}.
      oneOf:
        - $ref: '#/components/schemas/SegmentFieldCondition'
        - $ref: '#/components/schemas/SegmentTagsCondition'
        - $ref: '#/components/schemas/SegmentProductCondition'
        - $ref: '#/components/schemas/SegmentCouponCondition'
      discriminator:
        propertyName: kind
        mapping:
          field: '#/components/schemas/SegmentFieldCondition'
          tags: '#/components/schemas/SegmentTagsCondition'
          product: '#/components/schemas/SegmentProductCondition'
          coupon: '#/components/schemas/SegmentCouponCondition'
    SegmentFieldCondition:
      type: object
      additionalProperties: false
      required:
        - kind
        - field
        - operator
      properties:
        kind:
          type: string
          const: field
        field:
          type: string
          minLength: 1
          maxLength: 256
          description: >-
            A customer field (such as totalSpentInCents, lastPurchaseDate, or
            city) or the ID of a custom attribute (atr_...), from the filter
            catalog.
        operator:
          type: string
          minLength: 1
          maxLength: 32
          description: >-
            One of the field's operators in the catalog. Text: eq, neq, in,
            not_in, contains, not_contains, starts_with, is_null, is_not_null.
            Number: eq, neq, gt, gte, lt, lte. Boolean: eq_true, eq_false,
            is_null, is_not_null. Date: gt, lt, between.
        value:
          description: >-
            Leave it out for is_null, is_not_null, eq_true, and eq_false. A list
            for in and not_in. Money in cents. Dates in ISO 8601 with a
            timezone.
          oneOf:
            - type: string
              maxLength: 512
            - type: number
            - type: boolean
            - type: array
              items:
                type: string
                minLength: 1
                maxLength: 256
              minItems: 1
              maxItems: 500
        value_to:
          description: End of a between range.
          oneOf:
            - type: string
              maxLength: 64
            - type: number
    SegmentTagsCondition:
      type: object
      additionalProperties: false
      required:
        - kind
        - operator
        - tag_ids
      properties:
        kind:
          type: string
          const: tags
        operator:
          type: string
          enum:
            - has_any
            - has_all
            - has_none
          description: >-
            has_any: has any of the tags. has_all: has all of them. has_none:
            has none of them, including customers without any tag.
        tag_ids:
          type: array
          items:
            type: string
            pattern: ^tag_[A-Za-z0-9_-]+$
          minItems: 1
          maxItems: 50
          description: Tag IDs (tag_...), from GET /v1/tags.
    SegmentProductCondition:
      type: object
      additionalProperties: false
      required:
        - kind
        - operator
      properties:
        kind:
          type: string
          const: product
        operator:
          type: string
          enum:
            - has_purchased
            - has_not_purchased
            - purchased_in_category
        product_id:
          type: string
          minLength: 1
          maxLength: 256
          description: >-
            The store's product ID, as in purchase items. For has_purchased and
            has_not_purchased.
        category:
          type: string
          minLength: 1
          maxLength: 256
          description: Product category name. For purchased_in_category.
    SegmentCouponCondition:
      type: object
      additionalProperties: false
      required:
        - kind
        - status
      description: >-
        Coupons and cashback (giftback) Bevits issued to the customer in
        automations, in AI customer service, and in in-store sales.
      properties:
        kind:
          type: string
          const: coupon
        status:
          type: string
          enum:
            - has_available
            - has_unused
            - has_expired_unused
            - has_used
            - has_received
            - has_not_received
          description: >-
            has_available: has an unused, unexpired coupon, with credit to spend
            now. has_unused: has a coupon they never used, expired or not.
            has_expired_unused: let a coupon expire without using it. has_used:
            used a coupon in a purchase. has_received: received a coupon.
            has_not_received: never received a coupon.
        source:
          type: string
          enum:
            - cashback
            - any
            - flows
          default: cashback
          description: >-
            cashback: coupons generated by a purchase (cashback or giftback,
            online or in store). any: every coupon Bevits issued to the
            customer. flows: only the coupons of the automations in flow_ids.
        flow_ids:
          type: array
          items:
            type: string
            pattern: ^flw_[A-Za-z0-9_-]+$
          minItems: 1
          maxItems: 50
          description: >-
            With source flows: automations that issue coupons, listed in the
            catalog.
        received_within_days:
          type: integer
          minimum: 1
          maximum: 3650
          description: Only coupons issued in the last N days.
        expires_within_days:
          type: integer
          minimum: 1
          maximum: 365
          description: 'With has_available: only coupons that expire in the next N days.'
  responses:
    SegmentMembership:
      description: Segment customers updated.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SegmentMembership'
    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
    WriteScopeRequired:
      description: The API key does not have the write scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: permission_denied
              code: missing_scope
              message: This API key does not have the required "write" scope.
              param: scope
              request_id: req_07f6cdc3c20249d6afcd90b4
    NotFound:
      description: Resource does not exist or belongs to another organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    IdempotencyConflict:
      description: The Idempotency-Key was already used with a different request body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    SegmentValidationError:
      description: >-
        A condition or field was rejected, for example an operator that doesn't
        apply to the field or an RFM segment. The message says what to fix and
        the valid options, and error.param points to the field.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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:
    RetryAfter:
      description: Seconds before retrying.
      schema:
        type: integer
        minimum: 1
    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
  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.