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

# Changelog

> This is the official change history of caBRAPI. Here you can follow all updates, from new features to bug fixes.

## Changelog Structure

Each version is organized into sections for easier reading:

* **Added**: new resources and features.
* **Changed**: changes to existing resources.
* **Fixed**: bug fixes.
* **Removed**: removed resources or features.
* **Deprecated**: resources or features that are obsolete and will be removed in future versions.
* **Security**: security-related updates.
* **Performance**: performance improvements.
* **Documentation**: documentation updates.
* **Notes**: additional notes about the version, such as links to pull requests, issues, or technical details.
* **Contributors**: list of contributors who worked on the version, with links to their profiles.
* **Other**: other changes that do not fit into the categories above.

***

**November 2026**

2026 — H2

Added

* **Advanced coupon rules (`rules`)**: support for `SINGLE_USE_PER_CUSTOMER`, `MIN_ORDER_AMOUNT` (minimum order amount in cents), `AFFILIATE_ONLY` (single or array of affiliate codes), `MIN_ITEMS_QUANTITY`, and `PAYMENT_METHOD` (specific gateway/method).

Changed

* **New quantity limits (`9999`)**: maximum `stock` (products), `useLimit` (coupons), and `MIN_ITEMS_QUANTITY` increased from `999` to `9999` (aligned with the `9999` price ceiling).

**September 2026**

2026 — H2

Added

* Cursor pagination on all listing endpoints: `GET /stores`, `GET /stores/:storeId/categories`, `GET /stores/:storeId/products`, `GET /stores/:storeId/coupons`, `GET /stores/:storeId/affiliates`, `GET /stores/:storeId/payments` and `GET /stores/:storeId/payments/filter`.

* `cursor` parameter (string) to advance through the list using `nextCursor` from the previous response.

* `sortBy` (field) and `order` (`asc`/`desc`) parameters for sorting on cursor endpoints.

* Responses include `nextCursor` and `hasMore` in offset mode, allowing migration without starting from scratch.

* **Affiliate click tracking**: public endpoints `POST /stores/:storeId/clicks` (registers click with `ref`) and `POST /stores/:storeId/clicks/verify` (validates origin and marks the script as installed). Validation of `Origin` against `store.trackingDomain`.

* **Tracking fields in the store**: `trackingDomain`, `scriptInstalled` and `scriptInstalledAt` returned by `GET /stores/:storeId` and updatable via `PUT /stores/:storeId` (`STORE_UPDATE`).

* New **Affiliates** section in the API reference: `GET/POST /stores/:storeId/affiliates` and `PUT/DELETE /stores/:storeId/affiliates/:affiliateId`, with `commissionRules` (`DEFAULT`/`PRODUCT`/`CATEGORY`/`COUPON`, lowest `position` wins) and `statistics=true` for `statistics`/`metrics`.

* `GET /stores/:storeId/payments/:paymentId`: full payment with products (price, stock, categories) and `metadata` (coupon in `metadata.items[].coupon`).

* Toggle to enable/disable payment gateway (Mercado Pago and Asaas) directly on the card, without re-entering credentials.

* New reactivation route in the backend: `POST /user/gateway` with `active: true` and no credentials reactivates a gateway using the already saved keys.

* Collapsible "Net receipt per gateway" card in the product editor, grouped by gateway (Mercado Pago/Asaas), with fee and net value forecast per method.

* "Gross Revenue" indicator next to "Net Revenue" in the dashboard.

* "Refresh data" button in the dashboard (refresh icon next to the store selector) that reloads stores, payments, categories, products and coupons in parallel, with a \~450ms spinner.

* Realtime: automatic periodic updates in stores (60s), categories, products and coupons (30s).

* Real gateway logos in `public/images/gateways/` (Mercado Pago and Asaas) used in dashboard forms.

* Asaas added to SDK types (`sdk-node-browser-bun` and `sdk-java-kotlin`): new options `ASAAS` (gateway) and `ASAAS_ORDER_PIX` / `ASAAS_ORDER_CARD` / `ASAAS_ORDER_BOLETO` in `PaymentCreateGateway`.

* Installment payments on checkout (Asaas and Mercado Pago): installment selector limited to the `maxInstallments` configured by the merchant in the gateway form (default `1`, maximum `12`).

* **Installment fee by range** table (`installmentFees`) in the gateway form: each range `from X to Y installments` has its own `percent` + `fixed`, with up to **12 ranges**; validated on the frontend (red highlight per row) and on the backend (overlap, `min > max`, limit).

* `GET /stores/:storeId/fees` now exposes `maxInstallments` and `installmentFees` per gateway, allowing checkout to display available installments and real fees (values and percentages) configured.

* Step-up reauthentication (email code, reusing the 2FA flow) for sensitive dashboard actions, such as viewing gateway credentials and changing password.

Changed

* Pagination documentation in `limitations.mdx` updated with a dedicated cursor section.
* The affiliate link now uses the store's `trackingDomain` (fallback to the store domain), allowing tracking on an external domain.
* All `DELETE` endpoints now use **soft delete** (`deletedAt`): the record disappears from listings but is preserved in the database (never physical removal again).
* Disabling a gateway now **preserves the registered credentials**, allowing reactivation without re-entering the keys (previously it deleted the credentials).
* Gateway button renamed from "Remove" to "Disable" reflecting the new behavior.
* Dashboard `MetricCard` with uniform height and alignment (`h-full min-h-[92px]`, `mt-auto` for the trend), 6-column grid to fit the new Gross Revenue card.
* Gateway images reorganized from `public/images/banner/` to `public/images/gateways/`, with normalized names (`mp.jpg` → `mercadopago.jpg`, `assas.png` → `asaas.png`).
* Gateway logos in the product receipt card with medium rounding (`rounded-md`).
* More stable sessions: **90s grace** tolerance in `AUTH2` and IP change no longer destroys the session (only marks it as suspicious for reauthentication).
* Price charged in card payment now uses the **installment range** of `installmentCount` (`installmentFees`) instead of the flat `fees.card` fee, persisting `metadata.gateway.card.installmentCount` in the payment — the charged value now matches what is shown in checkout.
* **The chosen number of installments is what counts** in all gateways: the API validates `installmentCount` against the store's `maxInstallments` and refuses above the limit (new codes `400 INVALID_INSTALLMENT_COUNT` and `400 MAX_INSTALLMENTS_EXCEEDED`, without `message` — route default).
* Card gateways (Asaas and Mercado Pago) apply the chosen `installmentCount` in all flows: Asaas splits the total equally across N× (including hosted invoice, previously only tokenized card) and Mercado Pago limits checkout to the chosen number (`max_installments`).

Fixed

* React hydration error caused by `<button>` inside `<button>` in the gateway card headers (switch is now a sibling of the expand button, not a child).
* Duplicate payment methods in the "Net receipt" card (aliases PIX/BANK\_TRANSFER, CARD/CREDIT\_CARD, BOLETO/TICKET) now deduplicated by label.
* Fee smaller than 1 cent (e.g. 0.99% of R$ 0.50) now displayed as "< R$ 0.01" instead of disappearing/being zeroed.
* Gateway reactivation without registered credentials now returns a clear error (`GATEWAY_NOT_FOUND` / `GATEWAY_NO_CREDENTIALS`).
* **Checkout card**: each installment option calculated the value using the fee of the current selection (not its own range), showing wrong values when switching 1x/2x/… — fixed to `totalForInstallments(n)` with the range for `n`.
* **Checkout 500**: `ReferenceError: Cannot access 'discountAmount' before initialization` when applying coupon (declaration moved before `totalForInstallments`).
* Duplicate/overlapping installment ranges now blocked on gateway save (`400 INVALID_DATA` on backend + red highlight in form).
* Step-up: error messages **never show raw codes** (`TOO_MANY_REQUESTS` etc.) — friendly fallback in Portuguese.

Documentation

* Changelog updated with the new gateway enable/disable flow, net receipt card, refresh data button and logo organization.
* `api-reference/payment/post.mdx` with the complete gateways/methods table (`<PROVIDER>_ORDER_<METHOD>`), examples for Asaas (PIX) and documentation of responses (QR code, `init_point`/`invoiceUrl`, `pixQrCode`).
* `api-reference/payment/filter.mdx` with `ASAAS` in the `gateway` filter parameter (`EFI_BANK` marked as legacy).
* `api-reference/store/fees.mdx` clarifying that returned fees are those **defined by the merchant** (not the cost charged by the gateway), as configured in the dashboard.
* `api-reference/store/fees.mdx` updated with the new `maxInstallments` and `installmentFees` (installment ranges) fields per gateway.
* `api-reference/payment/post.mdx` documenting **card installment** via `metadata.gateway.card.installmentCount` (limit `maxInstallments`, fee per range applied over total and persistence of `installmentCount` in payment), with example of card in 6x.
* `api-reference/payment/post.mdx` updated with the final installment behavior: the chosen one counts in **Asaas** (hosted invoice and tokenized) and **Mercado Pago** (limited to chosen), refusal above the limit and new codes `INVALID_INSTALLMENT_COUNT` / `MAX_INSTALLMENTS_EXCEEDED` (error table).
* Changelog updated with installment validation, application in both gateways and test coverage (unit tests for `ASAAS_SERVICE`/`MERCADOPAGO_SERVICE` + routes).
* SDK repositories updated with Asaas (Node/Browser/Bun SDK: types `PaymentGateway`/`PaymentCreateGateway` + fields `init_point`, `pixQrCode`, `copyPastePix`; Java SDK: enums + corrected README).
* Java SDK README: outdated value `MERCADOPAGO_SERVICE_PIX` corrected to `MERCADOPAGO_ORDER_PIX`.

Contributors

* [@sebastianjnuwu](https://github.com/sebastianjnuwu) - Sebastian Jn.

**April 2026**

2026 — H1

Added

* Centralized `SendPush` service in the API to unify Firebase notification sending.
* Support for sending push with `token`, `tokens`, `url`, `route`, `type` and `data` in the same payload.
* Automatic opening of the specific payment when clicking the notification, using `paymentId` in the dashboard flow.
* New renewal bonus control in subscription: when contracting a new plan, the user can receive remaining days as bonus, with a maximum limit of 7 days.
* Adjustment in API seed to activate only the default subscription defined in `SEED_ACTIVE_PLAN`, without recreating user or store.
* Visual improvements in the dashboard subscription card, with icons in plan, due date and status fields.
* Support for optional `metadata` field (JSON) in the API categories model.
* Persistence and return of `metadata` in category creation, edition and query flows (`POST`, `PUT`, `GET` and `GET by ID`).
* Metadata field in JSON format in the (Site) categories panel to create and edit using Monaco editor, with real-time syntax validation.
* New automatic stock and coupon reversal system when payments are not completed.
* Utility function `revertPaymentAllocation()` to atomically revert stock allocation and coupon useLimit.
* Automatic reversal integration in payment expiration flow (after 24h without confirmation).
* Automatic reversal integration in Mercado Pago webhook for statuses: `REJECTED`, `CANCELLED`, `REFUNDED`, `CHARGED_BACK`.
* New private filter endpoint for payments: `GET /stores/:storeId/payments/filter`.
* Support for combinable filters by payment fields: `id`, `uuid`, `status`, `name`, `email`, `cpf`, `price`, `coupon`, `gateway`, `shipment`, etc., pagination and ordering.
* Support for nested metadata filters (dot notation), for example: `metadataKey=items.0.product.sold&metadataValue=19`.
* New authenticated push token routes in the API: `POST /user/push-token` (registration) and `DELETE /user/push-token` (removal).
* New welcome flow via Firebase on token registration: when registering a valid token, the system sends an initial confirmation notification.
* Token persistence in `user.metadata.pushTokens` with update of the user's Redis cache after changes.

Changed

* Subscription flow updated to trigger push notification and plan-activated email with the same context standard.
* Payment push updated to open directly on the payments tab and focus the corresponding payment.
* Site service worker adjusted to respect `url`, `route` and `hash` when opening notifications.
* Firebase frontend adjusted to redirect notifications in foreground with the same behavior as the service worker.
* Subscription logic updated to calculate bonus days based on the current active subscription's due date.
* Dashboard subscription card simplified to display only status based on due date.
* Category flow in frontend updated to send payload with `metadata` along with the other fields.
* Site API client for categories updated to accept optional `metadata` on creation and update.
* Category cache key kept in original pattern (`stores:{storeId}:categories`) after rollout adjustments.
* Payment expiration flow (`paymentQueue`) now reverts stock and coupon before marking as `EXPIRED`.
* Mercado Pago webhook now automatically detects payment failures and reverts corresponding allocations.
* Payment filters controller adjusted to handle nested metadata more consistently.
* Metadata filter logic consolidated to avoid overwriting between criteria (`metadataKey`, `metadataValue`).
* Documentation navigation updated to include the new `api-reference/payment/filter` page in the Payments section.
* Naming and formatting adjustments to keep consistency with other API pages.
* Push token registration logic updated to avoid duplicates, keep up to 3 tokens per user and prioritize the most recent tokens.
* Notification Service Worker of the site reviewed to better support Firebase payloads in background and more complete display (title/body/icon/image/badge).
* Notification click handling added in the Service Worker to focus an existing window or open the URL sent in the payload.

Fixed

* Fix click on notifications to avoid generic opening of the home page when a specific destination exists.
* Automatic normalization of push payload fields to avoid sending values not supported by FCM.
* Critical fix: Stock and coupons were NOT reverted when payments failed, resulting in data inconsistency.
* Transactional reversal implementation to guarantee consistency even on partial failures.
* Adjustments in the background push display flow to reduce cases where the notification did not appear correctly in some payloads.

Documentation

* Changelog updated with the push flow refactoring and the direct payment opening integration via notification.
* API category reference updated to include `metadata` field in endpoints:
  * `api-reference/category/post`
  * `api-reference/category/put`
  * `api-reference/category/get`
  * `api-reference/category/get-by-id`
* Category request/response examples reviewed to reflect payload and return with `metadata`.
* Product and coupon limits documentation updated to reflect reversal behavior on non-approved payments.
* Changelog updated with the push notification improvements (API + Site) implemented on this date.

Contributors

* [@sebastianjnuwu](https://github.com/sebastianjnuwu) - Sebastian Jn.

**March 2026**

2026 — H1

Added

* User and Store models updated to support webhook URLs (API)
* Image upload refactored to use internal blob server and related components updated (Site)
* Webhook management enhanced with better state control and user feedback (Site)
* New Webhooks documentation structure: own section, GET/POST/DELETE endpoints documented separately.
* Documentation of encrypted payload and decryption example in the tutorial.
* Review of plan expiration job (`billing.job.js`) to ensure compatibility with the current subscription structure based on `UserSubscriptionHistory`.
* Subscription active validation logic using `getPrimarySubscription` and checking expiration and notification criteria.
* Minimalist function to set user plan (`setUserPlan`).
* Refactoring of `ACTIVE_SUBSCRIPTION` helper to direct and lean logic.
* Validation and documentation of error codes of the store creation endpoint.
* Frontend adjustment: error handling in the store creation modal now prevents undue success feedback.
* Support for multiple payment methods via Mercado Pago: PIX and Credit Card (`MERCADOPAGO_SERVICE_PIX`, `MERCADOPAGO_SERVICE_CARD`).
* `feeAppliedTo` field in gateway credentials to define in which payment methods the fee is applied (e.g.: card only, pix only, or both).
* Standardized payment response structure with `service` and `payment` objects separated.
* Registration of `gatewayMethod` field in internal payment metadata for traceability.
* Changelog updated to document new automatic schedulers (UserDelete, Billing) and translation of all scheduler/queue messages to English.
* Option to configure fee (%) passed to client when using payment gateways (frontend and backend).
* `feePercentage` field can now be defined per gateway and saved in encrypted credentials.
* Automatic application of fee in the final payment value, both in public and admin API.
* Registration of `gatewayFeePercentage` and `gatewayFeeAmount` fields in payment metadata.
* IDs and htmlFor of gateway modal fields now follow `gateway-TIPO-campo` pattern for compatibility and accessibility.
* Gateway validation messages displayed in Portuguese, both in frontend and backend.
* Dedicated **Changelog** tab in the main documentation navigation.
* Initial structure for continuous version and change recording.
* Copy user ID in profile modal to facilitate integration with other tools.
* Support for category ordering with `position` field in backend.
* New private endpoint `PUT /stores/:storeId/categories/reorder` to save order by ID list.
* Panel actions to organize categories with `Move up` and `Move down`.
* Support for ordering of products, coupons and stores with `position` field in backend.
* New private endpoints `PUT /stores/:storeId/products/reorder`, `PUT /stores/:storeId/coupons/reorder` and `PUT /stores/reorder`.
* Panel actions to organize products, coupons and stores with `Move up` and `Move down`.

Changed

* Adjustment in package.json of API and Site for new version 15.03.2026
* Session control and error logging adjustments in authentication controllers (API)
* Documentation navigation reorganized: webhooks no longer appear under stores, but in their own group.
* Webhooks tutorial revised to align with the real API and encrypted format.
* Example and explanation adjustments to reflect the real backend implementation.
* Subscription and expiration flow documentation reviewed via AI.
* Schedulers and queues refactor: job and queue names standardized to avoid conflicts and ensure correct processing.
* Automatic cleanup of completed and failed jobs is now default in all queues (removeOnComplete/removeOnFail).
* Scheduling methods updated to use only essential options, centralizing cleanup configuration in the queue core.
* Subscription webhook updated to use the new `ACTIVE_SUBSCRIPTION` signature.
* Standardization of status returns and error codes in the stores backend.
* Fee calculation logic (`feePercentage`) now considers `feeAppliedTo` — fee only applied if the payment method is listed.
* Payment API response restructured: now returns `{ service, payment }` instead of flat data.
* Free payments now return `service.type: "FREE_PAYMENT"` for consistency with other flows.
* Card gateway migrated to Mercado Pago Checkout Pro with exclusion of unwanted methods via `excluded_payment_types` and `excluded_payment_methods`.
* Payment metadata structure in admin API is now identical to public for gateway fees.
* Enhanced validation to ensure `feePercentage` is respected and applied correctly.
* Payments dashboard now shows most recent payments by default, even in "All" option.
* Adjustment in payment method checkboxes to ensure compatibility with backend and validation scripts.
* Navigation adjustment to separate updates from tutorials tab.
* Documentation grouping improvement to facilitate discovery of recent changes.
* `GET /stores/:storeId/categories` now returns categories in `position` order.
* `GET /stores/:storeId/categories/:categoryId` and category creation/edition responses now include `position`.
* `GET /stores`, `GET /stores/:storeId/products` and `GET /stores/:storeId/coupons` now return data in `position` order.
* Creation/edition responses and product, coupon and store details now include `position`.

Fixed

* Fix error logging and session recovery skip adjustment in authentication controllers (API)
* Expiration emails and plan expiration reviewed and corrected, now sent with new standardized design.
* Fix expiration job to process already expired subscriptions, not only active ones.
* Direct update of subscription history metadata, without external function dependency.
* Fix switch/case of errors in the store creation modal to ensure correct UX.
* Tailwind class adjustments to avoid build warnings.
* Fix bug where `MERCADOPAGO_SERVICE` did not return the axios result due to missing `return`.
* Fix bug where `value.gateway` was overwritten with `gatewayType`, making the service always fall into `UNSUPPORTED_PAYMENT_TYPE` flow.
* Fix `gateway` field saved in database to use correct Prisma enum (`MERCADOPAGO`) instead of full method.
* Removal of `default_payment_method_id: "credit_card"` that caused error `invalid default_payment_method_id` in Mercado Pago API.
* Fix variable reassignment error (`finalPrice`) in admin payment controller.
* Adjustments to ensure consistency between public and admin API in fee logic.
* Fix error `TypeError: Cannot read properties of undefined (reading 'split')` when saving gateways without id in inputs.
* Extra check to ignore elements without id in gateways script.
* Application of optional chaining (`?.`) to avoid errors accessing undefined properties.
* Lint/type check in API and site to ensure absence of critical errors.
* Fix broken links related to integration tutorials.
* Fix inconsistencies in previous version naming.
* Fix formatting in previous changelog sections.
* Routes that were private and are now public error.

Removed

* Field/mention of webhooks removed from the store response in documentation.
* Old webhooks file inside stores removed.

Documentation

* Version and dependency updates in packages (API and Site)
* New reference page for `POST /stores/:storeId/payments` endpoint with request examples, cURL snippets and documented responses for PIX, Card and free payment.
* Documentation updated to include changelog and usage instructions.
* New integration tutorials added to documentation, such as Mercado Pago, EFI Bank (tabs only).
* API category documentation updated with `position` field.
* New API page for reordering: `api-reference/category/reorder`.
* API documentation of products, coupons and stores updated with `position` field.
* New reordering pages: `api-reference/product/reorder`, `api-reference/coupon/reorder` and `api-reference/store/reorder`.

Notes

* This is the initial version of the changelog, and previous versions are being documented retroactively.
* Previous versions are being reviewed to ensure that all significant changes are recorded.
* The changelog will be updated regularly with each new version released, and previous versions will be reviewed to ensure that all significant changes are recorded.

Contributors

* [@sebastianjnuwu](https://github.com/sebastianjnuwu) - Sebastian Jn.


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