---
title: "Estimates the points, cashback and availability dates for a sale without saving an order."
method: POST
path: "/v1/pvt/POS/orders/estimate"
tags: ["POS"]
---

# Estimates the points, cashback and availability dates for a sale without saving an order.

`POST /v1/pvt/POS/orders/estimate`

## Request

- Base URL: `https://api.bonifiq.com.br`
- URL: `https://api.bonifiq.com.br/v1/pvt/POS/orders/estimate`
- Auth: HTTP basic

Send the same body as POST /v1/pvt/POS/orders. The estimate in Result uses the submitted sale,
even if an order with the same OriginalId exists. The estimate applies the store's customer enrollment rules.

**Required permission:** `Pos` (Admin: PDV / POS - Acesso)

## Request body

- CreateOrderRequest: Purchase Order Model
  - `OriginalId` string: This is the Id in the client store.
  - `OrderPlacementDate` string, date-time: Date of the customer's purchase.
  - `OrderCompletedDate` string, date-time, nullable: Date the order reached the completed state (usually it's invoiced or delivered).
  - `OrderCancelledDate` string, date-time, nullable: if the order is cancelled, contains the date.
  - `OrderStatus` string: Status at the client's order system.
  - `IsCancelledOrReturned` boolean: if true the order was cancelled or returned.
  - `IsCompleted` boolean: If true it means the order has reached its final status and points can be awarded to the consumer.
  - `OrderTotal` number: Can be used at Loyalty Programs. Important: these values should not include Shipping costs.
  - `Customer` 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.
  - `Products` object[], nullable: Products listed on the order.
    - `OriginalId` string: Id from the client store.
    - `Title` string: Product Name
    - `Url` string, nullable: Direct url to the product on the client store.
    - `ImageUrl` string, nullable: Product img url.
    - `IsActive` boolean: if true the product is active on the store.
    - `ProductPrice` number, nullable: How much the customer paid for this product. If it is not null and not zero it can be used with extra points for products rule
    - `ProductBrand` CreateProductBrandRequest, nullable
      - `OriginalId` string: Id from the client store
      - `Name` string: Brand Name
    - `ProductCategory` CreateProductCategoryRequest, nullable: Product Category model with support for hierarchical categories.
      - `OriginalId` string: Id from the client store
      - `Name` string: Category Name
      - `Description` string, nullable: Category Description
      - `ParentCategory` CreateProductCategoryRequest (recursive)
  - `UpdatedDate` string, date-time: the date from the last update on this order.
  - `Coupon` string, nullable: Coupon code used on this order.
  - `Metadatas` object[], nullable: This is a key-value list of extra information regarding the order. It could be informative only or being part of an business rule to be used later.
    - `Name` string
    - `Value` string
  - `PaymentMethod` CreateOrderPaymentMethod, nullable
    - `OriginalId` string: The If of the Payment method. Can be any string unique to this Payment Method. If no Id is available you can used the Payment Method Name as Id
    - `Name` string: Name of the payment method used. It could be shown to the customer so it should be meaningful.
    - `PaidAmount` number, nullable: Optional amount paid using this payment method.
  - `PaymentMethods` object[], nullable: Preferred field for the payment methods used in this purchase. Each item should be as specific as possible (ie: instead of using "Credit Card" use "Visa Credit Card" and so on).
    - `OriginalId` string: The If of the Payment method. Can be any string unique to this Payment Method. If no Id is available you can used the Payment Method Name as Id
    - `Name` string: Name of the payment method used. It could be shown to the customer so it should be meaningful.
    - `PaidAmount` number, nullable: Optional amount paid using this payment method.
  - `Branch` CreateOrderBranch, nullable
    - `OriginalId` string: This is the Id of the branch (filial, loja, etc) in the client store. Can be any string.
    - `Name` string: This is the name of the branch. Can be any string possible
  - `SalesPerson` CreateOrderSalesPerson, nullable
    - `OriginalId` string: This is the Id of the Sales Person. Can be any string or number.
    - `Name` string: This is the name of the sales person. Can be any string.
  - `TradePolicy` CreateOrderTradePolicy, nullable
    - `OriginalId` string: Id of the trade policy in the client system. Can be any string, such as `FULLPRICE` or `OUTLET`. Trade policies received from the ecommerce platform share the same ids, so use a distinct id unless the rule should be shared.
    - `Name` string, nullable: Name of the trade policy shown in the BonifiQ panel. When empty, `OriginalId` is used as the name.
  - `ExternalCoupon` string, nullable

## Response `200`

- BaseExternalApiResponseOfOrderEstimatedBonusResponse: 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` OrderEstimatedBonusResponse, nullable: Estimate of the bonus (points and cashback) the customer will earn for this order. It is a simulation made when the order is saved: the bonus actually granted may differ (eg: rules changed, order cancelled, bonus still pending its release date).
    - `GenerateBonus` boolean: `true` when this order is expected to generate a bonus for the customer. `false` when it is not expected to generate one (eg: customer not enrolled, order not eligible, no points) or when the estimate could not be calculated. In both cases the order itself was saved successfully.
    - `EstimatedPoints` integer: Estimated points the customer will earn. `0` when `GenerateBonus` is `false`.
    - `EstimatedCashback` number: Estimated points converted to cashback using the store's active cashback reward, rounded down like the customer's cashback balance (eg: 45 points at R$ 0,10 each = R$ 4,00). `0` when the store has no active cashback reward or `GenerateBonus` is `false`.
    - `EstimatedCashbackFormatted` string: `EstimatedCashback` formatted in the store's currency and culture (eg: "R$ 4,00"). Use it only for display.
    - `DaysToAvailable` integer: Days after the order is completed until the points are granted and available to use (the store's grant delay for this sales channel, or an advanced rule's). `0` means right after the order is completed.
    - `EstimatedAvailableDate` string, date-time, nullable: Estimated date (UTC) from which the points are available to use: `OrderCompletedDate` + `DaysToAvailable`. `null` when the order is not completed yet or `GenerateBonus` is `false`.
    - `ExpirationDays` integer, nullable: How many days the points are valid after being granted. `null` when the store's points do not expire or `GenerateBonus` is `false`.
    - `EstimatedExpirationDate` string, date-time, nullable: Estimated date (UTC) when the points expire, counted from `EstimatedAvailableDate`. `null` when the points do not expire, the order is not completed yet or `GenerateBonus` is `false`.
  - `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`.

## Other responses

- `400`
- `403`: The API credential does not have the permission required by this endpoint.
- `500`

## Changes

- **2026-11-13** `260edb232133`: 1 info
  - added the non-success response with the status `403`
- **2026-11-12** `c22db5d2a142`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bonifiq/apis/bonifiq-private-apis/changes/v1/pvt/POS/orders/estimate/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/a43551bf4b5f?raw)
