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.
Added
- Advanced coupon rules (
rules): support forSINGLE_USE_PER_CUSTOMER,MIN_ORDER_AMOUNT(minimum order amount in cents),AFFILIATE_ONLY(single or array of affiliate codes),MIN_ITEMS_QUANTITY, andPAYMENT_METHOD(specific gateway/method).
- New quantity limits (
9999): maximumstock(products),useLimit(coupons), andMIN_ITEMS_QUANTITYincreased from999to9999(aligned with the9999price ceiling).
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/paymentsandGET /stores/:storeId/payments/filter. -
cursorparameter (string) to advance through the list usingnextCursorfrom the previous response. -
sortBy(field) andorder(asc/desc) parameters for sorting on cursor endpoints. -
Responses include
nextCursorandhasMorein offset mode, allowing migration without starting from scratch. -
Affiliate click tracking: public endpoints
POST /stores/:storeId/clicks(registers click withref) andPOST /stores/:storeId/clicks/verify(validates origin and marks the script as installed). Validation ofOriginagainststore.trackingDomain. -
Tracking fields in the store:
trackingDomain,scriptInstalledandscriptInstalledAtreturned byGET /stores/:storeIdand updatable viaPUT /stores/:storeId(STORE_UPDATE). -
New Affiliates section in the API reference:
GET/POST /stores/:storeId/affiliatesandPUT/DELETE /stores/:storeId/affiliates/:affiliateId, withcommissionRules(DEFAULT/PRODUCT/CATEGORY/COUPON, lowestpositionwins) andstatistics=trueforstatistics/metrics. -
GET /stores/:storeId/payments/:paymentId: full payment with products (price, stock, categories) andmetadata(coupon inmetadata.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/gatewaywithactive: trueand 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-bunandsdk-java-kotlin): new optionsASAAS(gateway) andASAAS_ORDER_PIX/ASAAS_ORDER_CARD/ASAAS_ORDER_BOLETOinPaymentCreateGateway. -
Installment payments on checkout (Asaas and Mercado Pago): installment selector limited to the
maxInstallmentsconfigured by the merchant in the gateway form (default1, maximum12). -
Installment fee by range table (
installmentFees) in the gateway form: each rangefrom X to Y installmentshas its ownpercent+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/feesnow exposesmaxInstallmentsandinstallmentFeesper 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.
- Pagination documentation in
limitations.mdxupdated 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
DELETEendpoints 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
MetricCardwith uniform height and alignment (h-full min-h-[92px],mt-autofor the trend), 6-column grid to fit the new Gross Revenue card. - Gateway images reorganized from
public/images/banner/topublic/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
AUTH2and 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 flatfees.cardfee, persistingmetadata.gateway.card.installmentCountin 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
installmentCountagainst the store’smaxInstallmentsand refuses above the limit (new codes400 INVALID_INSTALLMENT_COUNTand400 MAX_INSTALLMENTS_EXCEEDED, withoutmessage— route default). - Card gateways (Asaas and Mercado Pago) apply the chosen
installmentCountin 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).
- 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.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 forn. - Checkout 500:
ReferenceError: Cannot access 'discountAmount' before initializationwhen applying coupon (declaration moved beforetotalForInstallments). - Duplicate/overlapping installment ranges now blocked on gateway save (
400 INVALID_DATAon backend + red highlight in form). - Step-up: error messages never show raw codes (
TOO_MANY_REQUESTSetc.) — friendly fallback in Portuguese.
- Changelog updated with the new gateway enable/disable flow, net receipt card, refresh data button and logo organization.
api-reference/payment/post.mdxwith 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.mdxwithASAASin thegatewayfilter parameter (EFI_BANKmarked as legacy).api-reference/store/fees.mdxclarifying 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.mdxupdated with the newmaxInstallmentsandinstallmentFees(installment ranges) fields per gateway.api-reference/payment/post.mdxdocumenting card installment viametadata.gateway.card.installmentCount(limitmaxInstallments, fee per range applied over total and persistence ofinstallmentCountin payment), with example of card in 6x.api-reference/payment/post.mdxupdated 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 codesINVALID_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+ fieldsinit_point,pixQrCode,copyPastePix; Java SDK: enums + corrected README). - Java SDK README: outdated value
MERCADOPAGO_SERVICE_PIXcorrected toMERCADOPAGO_ORDER_PIX.
- @sebastianjnuwu - Sebastian Jn.
Added
- Centralized
SendPushservice in the API to unify Firebase notification sending. - Support for sending push with
token,tokens,url,route,typeanddatain the same payload. - Automatic opening of the specific payment when clicking the notification, using
paymentIdin 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
metadatafield (JSON) in the API categories model. - Persistence and return of
metadatain category creation, edition and query flows (POST,PUT,GETandGET 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) andDELETE /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.pushTokenswith update of the user’s Redis cache after changes.
- 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,routeandhashwhen 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
metadataalong with the other fields. - Site API client for categories updated to accept optional
metadataon 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 asEXPIRED. - 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/filterpage 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.
- 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.
- Changelog updated with the push flow refactoring and the direct payment opening integration via notification.
- API category reference updated to include
metadatafield in endpoints:api-reference/category/postapi-reference/category/putapi-reference/category/getapi-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.
- @sebastianjnuwu - Sebastian Jn.
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 onUserSubscriptionHistory. - Subscription active validation logic using
getPrimarySubscriptionand checking expiration and notification criteria. - Minimalist function to set user plan (
setUserPlan). - Refactoring of
ACTIVE_SUBSCRIPTIONhelper 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). feeAppliedTofield 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
serviceandpaymentobjects separated. - Registration of
gatewayMethodfield 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).
feePercentagefield 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
gatewayFeePercentageandgatewayFeeAmountfields in payment metadata. - IDs and htmlFor of gateway modal fields now follow
gateway-TIPO-campopattern 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
positionfield in backend. - New private endpoint
PUT /stores/:storeId/categories/reorderto save order by ID list. - Panel actions to organize categories with
Move upandMove down. - Support for ordering of products, coupons and stores with
positionfield in backend. - New private endpoints
PUT /stores/:storeId/products/reorder,PUT /stores/:storeId/coupons/reorderandPUT /stores/reorder. - Panel actions to organize products, coupons and stores with
Move upandMove down.
- 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_SUBSCRIPTIONsignature. - Standardization of status returns and error codes in the stores backend.
- Fee calculation logic (
feePercentage) now considersfeeAppliedTo— 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_typesandexcluded_payment_methods. - Payment metadata structure in admin API is now identical to public for gateway fees.
- Enhanced validation to ensure
feePercentageis 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/categoriesnow returns categories inpositionorder.GET /stores/:storeId/categories/:categoryIdand category creation/edition responses now includeposition.GET /stores,GET /stores/:storeId/productsandGET /stores/:storeId/couponsnow return data inpositionorder.- Creation/edition responses and product, coupon and store details now include
position.
- 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_SERVICEdid not return the axios result due to missingreturn. - Fix bug where
value.gatewaywas overwritten withgatewayType, making the service always fall intoUNSUPPORTED_PAYMENT_TYPEflow. - Fix
gatewayfield saved in database to use correct Prisma enum (MERCADOPAGO) instead of full method. - Removal of
default_payment_method_id: "credit_card"that caused errorinvalid default_payment_method_idin 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.
- Field/mention of webhooks removed from the store response in documentation.
- Old webhooks file inside stores removed.
- Version and dependency updates in packages (API and Site)
- New reference page for
POST /stores/:storeId/paymentsendpoint 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
positionfield. - New API page for reordering:
api-reference/category/reorder. - API documentation of products, coupons and stores updated with
positionfield. - New reordering pages:
api-reference/product/reorder,api-reference/coupon/reorderandapi-reference/store/reorder.
- 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.
- @sebastianjnuwu - Sebastian Jn.