--- title: "Estimates points, cashback earned and cashback usage limits per product." method: POST path: "/v1/pvt/Product/points" tags: ["Product"] --- # Estimates points, cashback earned and cashback usage limits per product. `POST /v1/pvt/Product/points` ## Request - Base URL: `https://api.bonifiq.com.br` - URL: `https://api.bonifiq.com.br/v1/pvt/Product/points` - Auth: HTTP basic Send an array of products with the store's external `Id` and current `Price`. Each item is estimated independently. Response order and repeated IDs are preserved. `Name` and `PriceCurrency` are optional; no currency conversion is performed. ### Cashback earned - `Points`: estimated points after bonuses, limits and zero-point rules. - `Cashback`: cashback earned from those points, truncated to whole currency units. - `CashbackPercent`: earned percentage before monetary truncation, rounded upward to a whole percentage. Do not calculate it from `Cashback / Price`. ### Cashback you can use - `CanUseCashback`: `false` for a restricted product; `true` for a permitted or unknown product, including when restrictions are disabled or empty. - `CanUseCashbackPercent`: maximum percentage of the price payable with cashback, assuming sufficient balance. Preserves the configured percentage and fractions, reduced by the monetary cap when applicable. Redemption rounding is not applied here. A restricted product can still earn cashback. For a positive price, its `CanUseCashbackPercent` is `0`. Without active cashback, all four cashback fields are `null`. For a nonpositive price, both percentage fields are `null`. Percentages use percentage units: `20` means **20%**. ### Example With no bonuses, one point per currency unit, cashback worth 0.01 per point, a 20% usage limit and no monetary cap: **Request** ```json [{"Id":"4571633770876","Price":2999.99}] ``` **Product estimate** ```json { "Id": "4571633770876", "Points": 2999, "Cashback": 29, "CashbackPercent": 1, "CanUseCashback": true, "CanUseCashbackPercent": 20 } ``` For a price of 200, a 30% usage limit and a monetary cap of 40, `CanUseCashbackPercent` is **20%**. ### Cart restrictions Minimum purchase requirements are ignored here and checked on the cart. The monetary cap applies to the **whole order**: do not sum product estimates to authorize redemption. Actual use also depends on the customer's balance and monetary rounding at redemption. ## Request body - object[] - `Id` string, required: Product Id on the ecommerce platform - `Price` number, required: Current product selling price - `PriceCurrency` string, nullable: Optional currency label (for example, BRL). It does not select a currency or perform conversion; the calculation uses Price as supplied. - `Name` string, nullable: Optional product name. It does not affect product lookup, earning rules or cashback restrictions. - `TradePolicyId` string, nullable: Optional trade policy (sales channel) identifier from the ecommerce platform, such as the VTEX `sc`. Earning rules restricted to this trade policy are included in the estimate. An unknown or empty value is ignored, so the estimate is the same as when the field is omitted. ## Response `200` An ApiResponse envelope. On success, Result contains the product estimates. Check HasError: an inactive objective or unsuccessful simulation returns an error envelope, rather than the HTTP 400 used by the public endpoints. - ApiResponseOfListOfProductPointResponse - `HasError` boolean - `ErrorMessages` string[] - `ErrorMessage` string - `ErrorDescriptions` object[] - `Description` 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 | 180 | 181 | 182 | 183 | 184 | 185: 0 = Campaign_InvalidDateRange 1 = Campaign_Conflict 2 = ReactivationCampaign_RoundUpPointsRequired 3 = ReactivationCampaign_LastPurchaseDateRequired 4 = ReactivationCampaign_LastPurchaseDateFuture 5 = ReactivationCampaign_ActiveCampaignConflict 6 = Reward_PointsShouldBePositive 7 = Reward_ValueShouldBePositive 8 = Reward_ValueShouldBe100PercentMax 9 = Reward_ValueShouldBe999ValueMax 10 = Reward_PointsShouldBe9999ValueMax 11 = General_FieldCannotBeNullOrBlank 12 = General_FieldCannotBeDefault 13 = General_BiggerThanZero 14 = Genaral_LengthLimitExceeded 15 = Order_OrderCompletedNeddCompletedDate 16 = Order_OrderCompletedDateMustBeAfterPlacementDate 17 = Order_CompletedOrderCannotBeCancelled 18 = Order_CancelledOrderRequiresCancellationDate 19 = Order_OrderCancellationDateBeforePlacementDate 20 = Points_PointsCannotBeZero 21 = FileUpload_NoFileReceived 22 = FileUpload_MoreThanOneFileReceived 23 = Objective_AmountOfPointsCannotBeLessThanOne 24 = Objective_DiscountValueCannotBeLessThanOne 25 = Objective_OrderMinimumValueCannotBeLessThanZero 26 = Objective_DaysToWaitToGrantPointsCannotBeLessThanZero 27 = Objective_CanceledStatusListMustHaveAValue 28 = Objective_CompletedStatusListMustHaveAValue 29 = FileUpload_InvalidFormat 30 = Objective_SignupStartDateMustHaveAValidValue 31 = FileUpload_FileTooLarge 32 = FileUpload_InvalidDimensions 33 = Account_UserAlreadyExists 34 = DaysToWaitToGrantPointsInvalidValue 35 = OrderMinimumValueInvalidValue 36 = ChangeActiveUser_UniqueAdmin 37 = ApiOrder_OrderIsCancelled 38 = PublicApiProductService_ObjectiveDisabled 39 = PublicApiProductService_ErrorCalculatingPoints 40 = ApiExternalOrder_Cant_Insert_Update 41 = ApiExternalOrder_Order_Not_Found 42 = ApiExternalProduct_Cant_Insert_Update 43 = ApiExternalErro_Original_Id_Cant_Be_Null 44 = ApiExternalCustomer_Cant_Insert 45 = ApiExternalCustomer_Cant_Update 46 = ApiTrustvoxKeysValidation 47 = ApiExternalRewardConfiguration_Error 48 = ApiExternalRewardConfiguration_Get_Error 49 = ApiExternal_Error_Page_Size 50 = ApiExternalRewardRedeem_Error_Customer_not_Found 51 = ApiExternalRewardRedeem_Error_Unable_to_Reedem 52 = ApiExternalObjective_not_found 53 = ApiExternalObjective_inactive 54 = ApiExternalCustomer_document_email_empty 55 = ApiExternalCustomer_documen_AlphaNumeric_only 56 = ApiExternalAffiliate_coupon_empty 57 = ApiJudgeMeAuthorizationError 58 = ApiExternalCustomObjective_max_bonification_reached 59 = ApiExternalObjective_type_incorrect 60 = ApiExternalCoupon_Customer_Not_Found 61 = ApiExternalCoupon_Cant_Update_Coupon 62 = ApiExternalCoupon_Not_found 63 = Referral_FriendAlreadyExists 64 = Customer_NotFound 65 = Tier_NotFound 66 = TierBenefit_Reward_Required 67 = ChangePoints_CannotAddPointsWithWrongOperationType 68 = ChangePoints_CannotRemovePointsWithWrongOperationType 69 = ChangePoints_CannotBeZeroPoints 70 = ChangePoints_ChangeKeyCannotBeNull 71 = ChangePoints_ChangeKeyAlreadyExists 72 = ChangePoints_ReasonCannotBeNullOrBlank 73 = ChangePoints_CustomerReasonTooLong 74 = ApiCustomer_InsertAlreadyExists 75 = ApiCustomer_ChangeCashback_Inactive 76 = ApiCustomer_RedeemCashback_Error 77 = ImportCoupons_AllCouponsAlreadyExists 78 = ApiCustomer_CannotChangeBirthday 79 = ApiRewardCancel_NotFound 80 = ApiRewardCancel_AlreadyCanceled 81 = ApiRewardCancel_InternalError 82 = ApiKonfidencyKeysValidation 83 = GenericError 84 = Account_UserWithoutLastName 85 = ApiDomain_NotFound 86 = ApiTenant_NotFound 87 = PdvUser_InvalidCredentials 88 = ApiReward_NoActiveRewards 89 = PdvReward_CustomerMismatch 90 = PdvReward_CoupomNotFound 91 = PdvReward_CoupomAlreadyUsed 92 = PdvReward_CoupomAlreadyRefunded 93 = PdvReward_RewardNotFound 94 = PdvReward_PurchaseValueInvalid 95 = PdvReward_CashbackValueInvalid 96 = PdvUser_NotFound 97 = PdvUser_NotInserted 98 = PdvOrder_WrongAmountOfPoints 99 = PdvOrder_ExcededMaxValue 100 = PdvOrder_NotEnoughPoints 101 = PdvOrder_OrderIdAlreadyExists 102 = PdvOrder_CreationError 103 = PdvOrder_CancellationError 104 = PdvOrder_NotFound 105 = PdvOrder_CustomerMismatch 106 = PdvOrder_OriginalIdUpdateError 107 = PdvBranch_NotInserted 108 = PdvBranch_OriginalIdAlreadyExists 109 = Too_Many_Requests 110 = PdvCustomer_AlreadyCompleted 111 = Quiz_QuizNotFound 112 = Quiz_MinimumAmountOfOptions 113 = Quiz_MaximumAmountOfOptions 114 = Quiz_MaximumAmountOfQuestions 115 = BillingGroupParticipants_ParticipantTenantIdIsActive 116 = BillingGroup_BillingGroupTenantIdIsActive 117 = BillingGroup_DuplicateTenantId 118 = AffiliateCouponGenericError 119 = AffiliateCouponNoExistsInPlatform 120 = AffiliateSettingsNotExist 121 = EndDate_ManageAdditionalBonuses 122 = AdditionalBonuses_ManageAdditionalBonuses 123 = Reinstall_The_App 124 = NewCustomer_EmailAlreadyUsed 125 = NewCustomer_DocumentAlreadyUsed 126 = WebhookSubscription_TopicRequired 127 = ParticipationCampaign_TotalAvailableLessThanRegistered 128 = FitnessChallenge_ActivityRequired 129 = FitnessChallenge_InvalidDateRange 130 = FitnessChallenge_RecurrenceRequired 131 = FitnessChallenge_ParticipationLimitRequired 132 = FitnessChallenge_DistanceNotSupported 133 = FitnessChallenge_DeleteHasParticipations 134 = ApiExternalOrder_Invalid_Partial_Cancel_Products 135 = CustomerNotFoundByDocument 136 = CustomerNotFoundByEmail 137 = ChangePoints_BalanceCannotBeNegative 138 = ChangePoints_BalanceCannotExceedLimit 139 = ChangePoints_CouldNotAcquireLock 140 = AdvancedRule_ActionButtonUrlInvalid 141 = AdvancedRule_InvalidPurchaseAmountRange 142 = AdvancedRule_StartDateCannotBeInThePast 143 = AdvancedRule_EndDateCannotBeInThePast 144 = AdvancedRule_AtLeastOneConditionRequired 145 = AdvancedRule_PurchaseAmountMustBePositive 146 = AdvancedRule_NotFound 147 = AdvancedRule_FeatureNotEnabled 148 = Objective_MaxCashbackPercentageLimitRequired 149 = Objective_MaxCashbackPercentageLimitInvalidValue 150 = Objective_MaxCashbackPercentageLimitBelowBase 151 = ReactivationCampaign_NeverPurchasedConflictsWithLastPurchase 152 = Objective_CustomGrantDelayRequiresPdvIntegration 153 = AccelerationCampaign_PointsAndCashbackAreMutuallyExclusive 154 = AdvancedRule_CompletedCannotBeEdited 155 = Reward_VtexCollectionSalesChannelOnlyCashback 156 = Reward_VtexCollectionSalesChannelPairsInvalid 157 = AdvancedRule_ActionButtonUrlRequired 158 = AdvancedRule_ActionButtonTextRequired 159 = CustomerSegment_TagInvalidFormat 160 = CustomerSegment_MembersRequired 161 = CustomerSegment_TagAlreadyExists 162 = CustomerSegment_FeatureNotEnabled 163 = CustomerSegment_ConcurrentUpdate 164 = CustomerSegment_NotFound 165 = CustomerSegment_MemberChangeNotQueued 166 = AdvancedRule_SegmentNotFound 167 = CustomerSegment_InUseByActiveAdvancedRules 168 = AffiliateOrderReprocess_CouponsRequired 169 = AffiliateOrderReprocess_StartDateRequired 170 = AffiliateOrderReprocess_TooManyCoupons 171 = AffiliateOrderReprocess_InvalidDateRange 172 = AdvancedRule_WithGeneratedOrdersCannotBeEdited 173 = AdvancedRule_StartDateCannotBeEditedAfterStart 174 = Objective_AmountOfPointsCannotBeNegative 175 = ParticipationCampaign_RewardValidityDaysRequired 176 = ParticipationCampaign_RewardValidityDaysMustBePositive 177 = ParticipationCampaign_RewardValidityDeadlineRequired 178 = ParticipationCampaign_RewardValidityDeadlineBeforeEndDate 179 = ParticipationCampaign_RewardValidityDaysTooLarge 180 = ParticipationCampaign_RewardValidityDeadlineTooLate 181 = ParticipationCampaign_RewardValidityTypeInvalid 182 = BillingGroup_BillingGroupTenantIdMustBeCurrentTenant 183 = AdvancedRule_ProductImportInProgress 184 = Account_UserNotFound 185 = BillingHistoryItems_InvalidRequest - `Field` string, nullable - `FieldText` string - `Result` object[], nullable - `Id` string: External product identifier, returned exactly as supplied in the request. - `Points` integer: Estimated earned points after applicable bonuses, limits and zero-point rules. This is a product estimate, not a guarantee of points granted for a completed order. - `Cashback` number, nullable: Estimated cashback earned from the simulated points, truncated to whole currency units. Null when cashback is unavailable; zero is a valid estimate and differs from null. - `CashbackPercent` number, nullable: The cashback percentage calculated from the final simulated points and product price, including bonuses and limits, rounded up to a whole percentage before monetary truncation. It will be null if cashback is unavailable or the product price is not positive. - `CanUseCashback` boolean, nullable: Whether cashback can be used on this product, considering product restrictions only, not the customer's balance. False for restricted products, true for eligible products (including unknown products or disabled restrictions), and null when cashback is inactive. - `CanUseCashbackPercent` number, nullable: Maximum percentage of this product's price payable with cashback, assuming sufficient balance. Includes product restrictions, the configured percentage limit and monetary cap, before redemption rounding. Null without active cashback or for a nonpositive price; zero for a restricted product. ## Changes - **2026-11-04** `bac0977b23d5`: 1 warning - added the new `185.00` enum value to the `allOf[#/components/schemas/ApiResponse]/ErrorDescriptions/items/oneOf[#/components/schemas/ApiResponseError]/Description/oneOf[#/components/schemas/ApiResponseErrorDescription]/` response property for the response status `200` - **2026-10-29** `0b2704b6ac3b`: 1 warning - added the new `184.00` enum value to the `allOf[#/components/schemas/ApiResponse]/ErrorDescriptions/items/oneOf[#/components/schemas/ApiResponseError]/Description/oneOf[#/components/schemas/ApiResponseErrorDescription]/` response property for the response status `200` - **2026-10-27** `fea2dc885d48`: 1 info - added the new optional request property `items/oneOf[#/components/schemas/ProductPointRequest]/TradePolicyId` - **2026-10-14** `43ce43db9d8e`: 1 warning - added the new `183.00` enum value to the `allOf[#/components/schemas/ApiResponse]/ErrorDescriptions/items/oneOf[#/components/schemas/ApiResponseError]/Description/oneOf[#/components/schemas/ApiResponseErrorDescription]/` response property for the response status `200` - **2026-10-10** `91be178ea8e3`: 1 warning - added the new `182.00` enum value to the `allOf[#/components/schemas/ApiResponse]/ErrorDescriptions/items/oneOf[#/components/schemas/ApiResponseError]/Description/oneOf[#/components/schemas/ApiResponseErrorDescription]/` response property for the response status `200` [Operation history](https://skmtc.dev/bonifiq/apis/bonifiq-private-apis/changes/v1/pvt/Product/points/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)