---
title: "Creates or updates a customer using the OriginalId provided in the request body."
method: POST
path: "/v1/pvt/Customer/upsert"
tags: ["Customer"]
---

# Creates or updates a customer using the OriginalId provided in the request body.

`POST /v1/pvt/Customer/upsert`

## Request

- Base URL: `https://api.bonifiq.com.br`
- URL: `https://api.bonifiq.com.br/v1/pvt/Customer/upsert`
- Auth: HTTP basic

This endpoint performs an upsert operation for customer data.
            
## Matching rule
- Uses OriginalId as the unique key
- If the customer does not exist, it is created (Operation = created)
- If the customer already exists, it is updated (Operation = updated)
            
## Response
Returns customer data plus an Operation field with created or updated.

## Request body

- ExternalCreateCustomerRequest: Creater Customer body Request
  - `OriginalId` string: This is the Id in the client store.
  - `Name` string: Customer name.
  - `Email` string, nullable: Customer email.
  - `Phone` string, nullable: Customer Contact Phone.
  - `BirthdayDate` string, date-time, nullable: Customer Birthdate.
  - `SignupDate` string, date-time, nullable: Date when the customer made the register on client store.
  - `Document` string, nullable: Some document number from the customer, accepts any string.
  - `IsEnrolled` boolean: If true the customer is participating on the points plan from the store.
  - `EnrolledDate` string, date-time, nullable: Date when the customer made entered into the program. Use the OrderPlacementDate if not informed.

## Response `200`

Upsert result containing customer data and operation metadata.

- BaseExternalApiResponseOfUpsertCustomerResponse: Standard response envelope used by the External API.
  - `ErrorMessage` string, nullable: Error message returned when the request fails validation or processing. For warnings and successful responses, consumers should usually inspect `Result`, `Code` and `Severity` first.
  - `ErrorCode` integer, nullable: Legacy numeric error code derived from internal API errors when available. This field is relevant only for error flows that use `ApiResponseErrorDescription`.
  - `Result` UpsertCustomerResponse
    - `OriginalId` string: This is the Id in the client store.
    - `PublicId` string, nullable: Bonifiq Plubic Id
    - `Name` string: Customer name.
    - `Email` string: Customer email.
    - `Phone` string, nullable: Customer Contact Phone.
    - `BirthdayDate` string, date-time, nullable: Customer Birthdate.
    - `SignupDate` string, date-time, nullable: Date when the customer made the register on client store.
    - `Document` string, nullable: Some document number from the customer, accepts any string.
    - `IsEnrolled` boolean: If true the customer is participating on the points plan from the store.
    - `ReferralURL` string, nullable: Customer`s Referral URL. Will be null if the Referral Objective is not active.
    - `WhatsappReferralUrl` string, nullable: Customer`s Referral URL for sharing in Whatsapp. Will be null if Referral Objective is not active
    - `CurrentTier` CustomerTierResponse
      - `Name` string
      - `Color` string
      - `IconUrl` string
    - `BalanceOfPoints` integer: Customer's current points balance
    - `BalanceCashback` number, nullable: Customer's current cashback balance (calculated from points). Will be null if cashback is not enabled.
    - `Segments` object[]: Active customer segments the customer belongs to (name and tag). Inactive segments are not returned. Empty list when the customer is not in any active segment. Populated by the customer endpoints (get, list, create, update, upsert and set birthday).
      - `Name` string: Segment name, as shown in the store's admin panel.
      - `Tag` string: Segment public identifier (slug, unique per store). Use it to reference the segment in integrations.
    - `Operation` string: Indicates if the upsert operation created or updated the customer.
  - `Code` string, nullable: Endpoint-specific business code formatted as a two-digit string, such as `03` or `07`. This field is available for success, warning and error outcomes.
  - `CodeName` string, nullable: Symbolic enum name associated with `Code`, such as `CheckoutNotFound`.
  - `Severity` 0 | 1 | 2: 0 = Success 1 = Warning 2 = Error
  - `HasWarning` boolean: Convenience flag that is `true` when `Severity` is `Warning`. Warnings are valid `200 OK` business outcomes and should not be handled as transport or validation errors.
  - `HasError` boolean: Indicates whether the request failed and should be handled as an error response. This flag is reserved for real API errors; warnings must keep this property as `false`.

## Changes

- **2026-09-02** `ab5bc0ffd114`: 1 info
  - added the optional property `Result/oneOf[#/components/schemas/UpsertCustomerResponse]/allOf[#/components/schemas/CreateCustomerResponse]/Segments` to the response with the `200` status

[Operation history](https://skmtc.dev/bonifiq/apis/bonifiq-private-apis/changes/v1/pvt/Customer/upsert/post.md)

---

[API](https://skmtc.dev/bonifiq/apis/bonifiq-private-apis.md) - [All operations](https://skmtc.dev/bonifiq/apis/bonifiq-private-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/bonifiq/apis/bonifiq-private-apis/revisions/bac0977b23d5?raw)