Sign in
.md

Release notes

Behaviour changes, new endpoints and fixes shipped to the Guper API. Newest first.

Each entry is tagged:

  • Breaking change — request or response contract changed; callers need to adapt.
  • New endpoint — endpoint added.
  • Improvement — backward-compatible change.
  • Fix — corrects wrong behaviour without changing the contract.
  • Deprecation — endpoint discontinued; migrate to the listed alternative.

November 12, 2026

Improvement Expired balance in the cards report

Cashback issued & redeemed by campaign (aggregate)

GET /api/loyalty/report/cards now returns expiredBalance on each row and in total: the balance left on expired cards — how much credit was lost because it was not used in time. Same cut as cardsExpired; in cents, like the other values. Also new: touchedRedeemed, the value redeemed by the same cards counted in touchedCards (at any date). redeemed keeps following the redemption date. New fields, nothing else changed.

November 11, 2026

New endpoint Update customers in batch

Update customers in batch

PUT /api/register/customer/batch updates many customers in one call — an items list of {id, ...fields}. Setting entityType=legal on hundreds of customers, or importing per-customer values, stops being hundreds of calls.

Each item reuses the same path as the single update (same sanitization and validation; only id is required per item). A bad item does not fail the batch: the response reports an outcome per item (updated / not_found / rejected with the reason) plus a summary. Pass dryRun: true to validate without writing (would_update). Up to 100 items per call.

New endpoint Cancel and reactivate cards in batch

Cancel Cards in Batch · Reactivate Cards in Batch

POST /api/loyalty/cards/cancel and POST /api/loyalty/cards/reactivate take up to 100 cards per call — cancelling 3,000 cards stops being 3,000 calls and becomes 30.

ids accepts ranges and single items in the same syntax used by collections: "1512200:1512299;1512305" means the cards from 1512200 to 1512299 plus 1512305. An array is accepted too. The limit of 100 applies to the expanded set, and a range never crosses organizations — an id from another account comes back not_found and is left untouched.

Partial failure is treated as normal: the answer is 200 with the outcome of each id (canceled, already_canceled, has_open_reservation, not_found), and 400 is reserved for a malformed request. A card that is already canceled or holds a reservation does not bring the rest of the batch down.

Run it with dryRun: true first: it shows what would happen item by item and how much balance would leave circulation, writing nothing. The response carries a batchId that ties the cards of one operation together.

November 9, 2026

New endpoint Cancel and reactivate a card

Cancel Card · Reactivate Card

Cancelling a card now has an endpoint of its own: POST /api/loyalty/cards/{id}/cancel takes the card out of circulation — it drops out of every balance query and reads as canceled — and POST /api/loyalty/cards/{id}/reactivate reverts it. Until now cancelling through the API existed only at transaction level (transaction/cancel), which reverses what a purchase generated; the target can now be the card itself, with no order involved: a campaign card granted by mistake, a manual card, a card the operation needs to close.

Cancelling a card is a change of state, not a movement: the balance is neither debited nor returned, and nothing is written to the card flow ledger. To take value out of a card that stays alive, keep using Adjust Card Balance with manual_debit.

A card holding an open redemption reservation is refused with 409 (the reserved value is waiting to be settled or returned), and a second cancellation also answers 409. The details and the comparison with transaction cancellation are in the Cancellation in loyalty guide.

November 5, 2026

Improvement Order date in Reward by Order

Reward by Order

rewardByOrder now documents and validates the creationDate field, the order date and time in ISO 8601 (e.g. 2026-11-02T10:00:00-06:00). Send it when the purchase happened before the call: the campaigns taken into account are the ones that were active on that date, the card's validity counts from it and it is recorded as the order date on the transaction. Without the field nothing changes: the time of the call is used.

An unreadable value, a date that does not exist (e.g. 2026-02-31) or one more than a day in the future now returns 400. Before, such a value was ignored in the calculation and the order could fail to be recorded on confirmation.

November 4, 2026

Improvement Audience by active card

Query Audience (QON)

Two new fields in the audience engine: hasActiveCard (has at least one card with balance that already started and has not expired) and activeCardExpiresWithinDays (has an active card expiring in the next N days). E.g. [{"col": "activeCardExpiresWithinDays"}, "inNextDays", {"int": 7}] is the "your cashback expires this week" audience. The balance is read live, so a customer who just redeemed everything drops out right away.

October 26, 2026

New endpoint One entity's refIds, without scanning the interface

List refs of a Category · of a Brand · of a Seller · of a Payment

Going from refId to the entity was already possible (GET /api/{service}/{interface}/{resource}/{refId}); the way back was missing. Now GET /api/catalog/category-external-ref/by-category/{categoryId} — and the brand, seller and payment equivalents — returns every refId of that entity, one per interface, with no need to list the whole interface and filter client-side.

Returns an empty array when there is no mapping (no 404). Mirrors the by-person endpoint that already existed for people.

Fix refId with special characters in the path

The external-ref endpoints did not URL-decode the {interface} and {refId} path segments. A refId containing a space (such as 00 71000000038, common at cegid) arrived as 00%2071000000038 and did not match in the database. Applies to catalog (brand, category, seller) and register (payment, person).

Improvement Products report broken down by store and time

Top products sold

The products report's groupBy now accepts a comma list: the item dimension (product/sku/category/brand) plus store and/or one time grain (day/week/month). E.g. groupBy=product,store, sku,week, product,store,month.

With a breakdown, limit picks the top items for the whole period and each row becomes one cell (item × store × period, carrying storeId/day/week/month). So "top products by store" or "by week" comes back in one call instead of one call per store. At most one time grain per call; a cell with no sales is not emitted. Backward compatible: without the extra tokens nothing changes.


October 22, 2026

New endpoint Validate your payload before integrating

Validate your payload

POST https://developers.guper.co/api/validate takes the JSON your integration produces and returns, field by field, what matches this documentation and what does not: a field that does not belong to the endpoint (with the right name suggested when it is close), a required field that is missing, a type that does not match, and a value outside the accepted list — including wrong casing, such as "Legal" where the field accepts legal.

No authentication, nothing stored, no transaction created. The comparison runs against the same file that generates the reference page, so it never drifts from what you read.

⚠️ This checks shape. It knows nothing about your organization: it will not tell you whether the storeId exists, whether the interface is registered, or whether an amount is on the right cents scale. A payload approved here can still be rejected by the API for those reasons.


October 21, 2026

Improvement "Different from" on the Entity type rule

Campaign rules: Create

The Entity type campaign rule (code 11) now honors reverse, like the customer tier and purchase type rules: false = equal to (what it always did), true = different from. The field was accepted and stored before, but ignored at evaluation time — the rule could only compare for equality.

⚠️ An order without client.entityType matches no value: it still fails with reverse: false and now fires with reverse: true. Since entityType comes only from the rewardByOrder body, "different from legal entity" also covers the order that did not report a type.

A rule created from the panel does not change behavior — the panel always stored reverse: false. If you created the rule through the API with reverse: true, that value was ignored and now actually inverts the rule.


October 12, 2026

Improvement List messages by phone, with the body, in one call

Messages: List

The message listing now accepts cellphone (exact match on the phone that received the message) and include (comma list that appends the rendered fields to each dispatcher: rendered_body, rendered_subject, rendered_text, rendered_meta).

Together they drop two round-trips for anyone finding which message started a conversation from a number: it used to mean resolving phone→customer in register, listing the messages, then opening each one's detail just to read the body. Now ?cellphone=...&include=rendered_body returns it all in one call.

⚠️ include is opt-in — without it the list stays lean (a rendered body can be a whole HTML document). cellphone matches the snapshot stored at send time, not the customer's live record.

Improvement Purchase type on rewardByOrder

Reward by order

POST /api/loyalty/rewardByOrder accepts the optional field purchaseType: the type of purchase, as free text defined by your integration (e.g. delivery, pickup). Up to 100 characters; surrounding spaces are trimmed and an empty value is ignored. A number, boolean or list returns 400. The value is kept with the transaction through confirmOrder.

On purchase campaigns, the new rule Purchase type (code 20) fires when purchaseType is equal to (or different from, with reverse) any of the configured values, not case sensitive. Use it to tell wholesale from retail, employee purchases, company from individual, and so on. Backward compatible: nothing changes if you don't send it.


October 7, 2026

Improvement Revenue broken down, from list price to net

Sales report

Every report/sales total now carries mix: listRevenue (list price) − discount − incentive = netRevenue, plus averageTicket (ASP, the price actually charged) and listAverageTicket (OSP, the list price). comparison.total carries the same block, so net revenue can be compared period over period.

⚠️ revenue is already net of the commercial discount — an item's price is the unit price after discount. List price is revenue plus discounts, not minus; subtracting the discount from revenue counts it twice. Avoiding that recomputation in every consumer is exactly why these fields now exist.

⚠️ incentive and netRevenue come back null without withAttribution=1 — the redeemed balance lives in the attribution block, and returning zero would be a lie.

⚠️ Not to be confused with attribution.revenueGross/revenueNet, which are scoped to the attributed orders; mix is the whole business.


October 3, 2026

New endpoint Sync store ↔ policy links

Sync store ↔ policy links

PUT /api/register/store/walletLink sets at once every store of a policy ({"wallet": 108, "stores": [...]}) or every policy of a store ({"store": 22, "wallets": [...]}), in a single transaction. The list is the final state: whatever is not in it is removed. It replaces one POST/DELETE per link. The list, create and delete link pages were also reviewed; the list now documents with=store.

Improvement Redemption policies compete with each other

Redemption policies

When the customer has balance in more than one redemption policy valid for the order, the policies now compete with each other: the order uses only the one that gives the largest discount (on a tie, the one with the closest expiry). Before, cards from different policies in Aggregate or Mixed mode were added up.

Nothing changed inside a single policy: Aggregate adds up the cards, Single uses the best one. Mixed mode now behaves like Aggregate. The Reward by order contract is the same; what changes is redeemable.total for customers with balance in more than one policy at the same store. The new guide explains the rule with examples.


September 30, 2026

Improvement Per-api-key permissions

Grant Access Scope

Every api-key now carries a list of permissions shaped as service.scope, and each route requires its own. Today every service exposes a single all scope — register.all, loyalty.all, order.all, sender.all, catalog.all, organization.all, journey.all, media-manager.all, auditObserver.all, pipeline.all, gapp-be.all — and connect exposes six finer ones: connect.user, connect.access, connect.scope, connect.session, connect.auth and connect.mcp.

Nothing changes for current integrations: every existing key was granted every permission. A call whose key lacks the route's permission is refused with 403, and the response names what is missing in requiredScope. Calls signed between Guper services do not go through this check.

Each key's permissions are also editable in the panel, under Settings › API Keys › Permissions.

September 29, 2026

Improvement Draft campaigns

List Campaigns

A campaign can now be saved as a draft (isDraft: true) on POST/PUT /api/loyalty/campaign: it stays editable and never runs — while it is a draft, isActive is forced to 0 server-side. Publish by sending isDraft: false; once published it only toggles between active and paused and cannot go back to draft (400).

In the list, the derived status gains the value draft, which wins over every other status; it also works in ?status=draft, statusCounts and sortByStatus (active, drafts, paused, finished). Backward compatible: existing campaigns are published (isDraft: false).


September 28, 2026

Improvement Campaign status in the list

List Campaigns

GET /api/loyalty/campaign now returns a derived status on every row: active, paused or finished. Backward compatible — nothing that was already there changed.

finished is not a column: for an audience campaign it means the send is over; for every other trigger it means the campaign period (finishAt) has ended. ⚠️ finished wins over isActive: a campaign whose period ended but is still switched on shows as finished, not active. It is read-only — isActive does not change.

Three new optional parameters: status filters by that status; statusCounts=1 returns the count for each one under the same q[...] filters; sortByStatus=1 lists active campaigns first, then paused, then finished.


September 24, 2026

Breaking change Expired tokens are no longer accepted

Get token

An x-guper-authorization presented after its expiresIn used to be accepted; it is now refused with 401 and Code: E0002.

No deadline was shortened — expiry times are the same as always and the issuing endpoint is unchanged. If you renew the token when it expires, nothing changes for you; if you kept an old token around, call Get token again.

⚠️ Asking for a new token before the current one expires has always been allowed and does not revoke the previous one.

New endpoint Audience targeted by period

Audience by period

GET /api/loyalty/report/audience/{start}/{end}: who the campaigns were addressed to — the denominator behind "of the people we aimed at, how many got the reward". The cards report already said how many rewards were created; the target was missing.

The work is in joining three tables with three different units. ⚠️ Last chance queues by card × campaign, not by person: counting rows there more than doubles the audience. It comes back deduplicated.

⚠️ Two numbers, and only one is a denominator: targeted (distinct people per campaign, summed — pairs with rewards granted) and clients (distinct people, never a denominator). In one organization last month two last-chance campaigns addressed nearly the same people: 77,429 addressings for ~38.7k people.

⚠️ For any rate, pass type=monetary: a notification campaign can use an audience list — it addresses people and never creates a reward, by design. And triggers with no target (forms, external events) do not appear in the response.


September 24, 2026

New endpoint Delivery and open rate by period

Delivery by period

GET /api/sender/report/delivery/{start}/{end}: the same reading as the per-campaign report, but over a date window — the whole organization or a list of campaigns (?sequence=). ?groupBy=sequence adds the per-campaign breakdown, sorted by volume. ?tz= reads the day boundary in the organization timezone (insertedAt is stored in UTC).

It answers "how did our messaging do in September" without walking campaign by campaign.

Improvement Providers that never confirm delivery no longer drag the rate down

Delivery by campaign

A provider with no delivery webhook (today, push) stops at sent and never speaks again. That is not "undelivered", it is delivery without confirmation — but it was counting as an implicit failure. It now goes to the new unconfirmed field, out of attempted and out of both rates. In an organization with push in the mix, the delivery rate moved with nothing having happened; now it measures only what can be measured.

attempted is still the denominator of the rates; the grand total that left the queue is the new sent field (= attempted + unconfirmed).


September 23, 2026

New endpoint Notification campaign funnel

Notification funnel

GET /api/loyalty/report/notifications/{start}/{end} with groupBy=campaign,day: how many people the message reached, and how many of them bought. It is the denominator that was missing — the sales report says how much the message generated, not at what cost of reach.

Only type=notification campaigns: a monetary campaign is attributed by the redemption of its balance, and the message it sends is a cashback notice. ⚠️ Two dates, kept apart in the response: total is the COHORT (messages sent in the window, followed wherever they convert) and total.result is what HAPPENED in the window — the latter is what lines up with the influenced revenue of the sales report.

⚠️ notificationCard.attributionAt is not the attribution date: it is written at the card's birth and is deprecated. Counting conversion by it would always give 100%.

Improvement Campaign and origin rankings return the net

Sales report

byCampaign and byOrigin now carry redeemed and revenueNet alongside the gross. Whoever displays it reports the net, so each consumer was deciding on its own — and a campaign that issues no balance showed zero revenue.


September 22, 2026

Improvement Sales report: tier breakdown and filter, store lists, and the discount warning

Sales report

groupBy=tier and tier=Diamond|none cut by the customer's level at the time of purchase (the order's own snapshot). ⚠️ none is the order with no snapshot — anonymous or unidentified — which in a large organization is over a third of the revenue: the tiers alone never add up to the total. The filter also narrows the attribution block and the product ranking.

store now takes a list (store[]=207&store[]=208 or 207,208, up to 500), for a channel filter: a channel is a store group, the group lives in Register, and the caller resolves the group into ids.

Every byDay, byStore and byInterface row now carries the split (attributed vs influenced, net) that previously existed only on the total.

New field ordersDiscountOverRevenue: orders whose discount is larger than the sale itself, which "list price minus sale price" makes impossible. Check it before publishing any ratio built on discounts — in one organization it is 27% of the orders, and with them in the mix the ratio reads 67%.


September 21, 2026

Breaking change PUT /api/connect/user requires login

Update User

Updating a user now requires login alongside personId, and both must belong to the same user: the login locates the record, the personId confirms it.

A wrong pair changes nothing and answers 404 (no such login) or 409 (the login belongs to someone else); a missing field answers 400. Only password, type and active can be changed — fields you omit stay as they are.

Improvement Attempt lock on sign-in and token issuing

Auth · Get token

After 8 failed attempts within 15 minutes, POST /api/connect/auth, GET /api/connect/token and the OAuth consent screen answer 429 and stop checking the credential for the next 15 minutes. One success clears the counter.

The lock is keyed differently in each case: for sign-in it is organization + login; for token issuing it is the api-key + the origin IP — so one integrator being blocked does not affect the other callers of the same organization.

Wrong-credential answers are now always identical (401), so the response no longer reveals whether a login exists.

September 18, 2026

Improvement Attributed, influenced and impacted sales in the sales report

Sales report

With withAttribution=true, the attribution block gains split, separating the two ways the program reaches a sale, in distinct orders: attributed (the order redeemed balance), influenced (the client only got the campaign's message and bought, redeeming nothing) and impacted (the sum, which is the block's own total). An order falls on one side only — getting the message and redeeming counts as attributed — so the two sides always add up. Each side carries the same derived fields as the total (revenueNet, avgDiscount, tickets).

The same block now accepts attributionBy=store,interface, returning byStore / byInterface — the attribution broken down by store and by channel, each row with the derived fields ready.

The campaign= filter now takes 500 ids (was 200).


September 17, 2026

Improvement Redemption policy: dynamic minimum order (minOrderRate)

Redemption policy · Reward by order

The wallet gains minOrderRate: the order has to be worth N times the customer's balance before the balance can be used (3 with a $30.00 balance requires a $90.00 purchase). It is all-or-nothing and applies per wallet, monetary wallets only; null = no rule, same behavior as always.

When the rule blocks the cart, redeemable.total comes back 0 and the new redeemable.blocked says why, with required (what the order would have to be worth) and missing (what is left) in cents — enough to show "$15.00 more to use your balance" at the POS. The key only shows up when something is blocked. Update transaction re-applies the rule: if the cart shrinks below the minimum after the quote, the reserved redemption is dropped — always charge by the redeemable.total of the latest response.

New endpoint Cashback time to redeem

Time to redeem

GET /api/loyalty/report/redemption-latency/{dateStart}/{dateEnd} returns the distribution of days (buckets=day) or weeks (buckets=week) between card availability (basis=available, default) or issuance (basis=issued) and the settled redemption, with median and p90. It takes the same filters as the redemptions report.


September 16, 2026

Improvement Cashback and sales reports: filter by several campaigns

loyalty.report.cards and loyalty.report.redemptions now accept a list in campaign (campaign=191,171 or campaign[]=191&campaign[]=171); a single id still works. order.report.sales gets the same campaign, together with withAttribution=true: it restricts only the attribution block (each order counted once), and the sales total is unchanged.

New endpoint Cashback redemptions with order and stores

Cashback redemptions

GET /api/loyalty/report/redemptions/{dateStart}/{dateEnd} lists settled redemptions, one row per (redemption, card), with the order, the store that issued the card and the store where it was redeemed. With groupBy (day, month, campaign, originStore, redeemStore) it returns aggregates — groupBy=originStore,redeemStore shows how balance circulates between stores. Supports cohort=redemption|issuance and filters by campaign, stores and client. Rows are at card grain: there is no order total, so it cannot be summed twice.

Fix Cashback cards: a redemption counts only once the sale is settled

Cashback cards

loyalty.report.cards now counts as redeemed only the balance of settled sales. Open checkout reservations and canceled reservations used to show up in redeemed; they are now left out. Closed periods change very little.

Improvement Cashback cards: conversion rate, partial/full use, groupBy=day and cohort

loyalty.report.cards now returns, on every row and in the total:

  • touchedCards — cards issued in the period with any settled redemption (partial or full);
  • cardsRedeemedPartial / cardsRedeemedFull, partialShare / fullShare;
  • usageRate — the conversion rate (touchedCards / (cards − cardsCanceled), in %);
  • cardsActive, which closes the status buckets against cards.

New parameters: groupBy=day (daily series, also combinable with store or campaign) and cohort=issuance, which windows redeemed by the card's issuance ("what happened to what I issued") instead of the redemption date (cohort=redemption, default). cardsRedeemed is still the card with zero balance and must not be used as the conversion: a reversal also zeroes a card.

Improvement Sales and campaign reports: average discount and gross/net tickets

order.report.sales?withAttribution=true (in the attribution block and on every byDay row) and order.campaign.report (in total) now return avgDiscount (redeemed / revenueGross, a ratio), averageTicketGross (revenueGross / orders) and averageTicketNet (revenueNet / orders). All are computed over distinct orders; the gap between the two tickets is the average balance applied per order. New fields only, nothing removed.

Improvement Tier: choose which campaigns add points

On the rewardCampaign source of tier_config, the new sources.rewardCampaign.campaigns list sets which campaigns add points to the tier. Without the list, every campaign keeps counting (previous behavior); with [], none counts. Not retroactive: points already credited are kept.

{ "sources": { "rewardCampaign": { "multiplier": 1, "expiresInDays": 365, "campaigns": [12, 40] } } }

The sources docs were also fixed: it is an object keyed by source name, not a list.


September 15, 2026

Improvement Sales report: membership=member filter (revenue from members)

order.report.sales?membership=member restricts to orders placed by program members (via the order_personMembership snapshot), in the total and attribution. It is revenue from members in the period, companion to register.report.members (the org-wide base). Only orders with a snapshot (from ~2026-05-28); non-member = total − member.

New endpoint Program members / associates report

Program associates

In one call, who a loyalty program's associates are: active base, tier and source mix, how many have ever bought (lifetime conversion) and lifetime value. Generic by tierConfig (any org):

GET /api/register/report/members?tierConfig=1

⚠️ The lens is lifetime, not a period: conversionLifetime = members who ever bought; lifetimeValue = lifetime spend. Revenue from members in a period is order.report.sales. meta.membershipStartedAt says since when members exist.

Improvement Sales report: generated sale (net) in attribution

order.report.sales?withAttribution now returns revenueNet (= revenueGross − redeemed), the generated sale Guper bills on, in the total and the daily series, plus participationNet. Before there was only gross (revenueGross); reporting it as "generated" overstated the invoice. Use revenueNet.

New endpoint Top products sold

Top products sold

To know "what sold most" you no longer page line items and sum them yourself. One call ranks items by product, SKU, category or brand:

GET /api/order/report/products/2025-08-01/2025-08-31?groupBy=product

Returns units, line revenue, orders and lines — top N by revenue, with total covering the whole period. product/sku work today; category/brand are ready and fill in as ingestion improves (the response carries coverage in meta). Note: revenue here is line revenue (sum of price×quantity), not the order total — for billing use the sales report.

September 14, 2026

New endpoint RFM by acquisition cohort

RFM by cohort

To analyze customers by cohort you no longer pull hundreds of thousands of RFM rows and group them yourself. One call returns RFM aggregated by acquisition cohort — by first-purchase month and/or acquisition store:

GET /api/register/report/rfm-cohort/2025-01-01/2025-06-30?groupBy=month

Per cohort: number of customers, lifetime and average value, average orders, repeat cadence and recency. Values in cents; total reconciles with the sum of the rows. Note: store is the acquisition store and the value is the customer's org-wide lifetime spend (not store sales — use the sales report for that).

New endpoint Cashback cards report (issued & redeemed)

Cashback cards

Seeing "every campaign" no longer means calling the per-campaign report one by one. One call returns issuance and redemption grouped by month, campaign, trigger or store:

GET /api/loyalty/report/cards/2026-08-01/2026-08-31?groupBy=campaign

Returns cards, credit distributed, redeemed, balance and expired. Reconciles with the single-campaign report (same math). Values in cents; rewardType separated (monetary by default).

Improvement Sales report: channel, discounts and cohort

The sales report gained groupBy=interface (share by channel), a discounts metric and a client filter (a list of client ids — a cohort/experiment).

September 10, 2026

Improvement Campaign rule: customer is a collaborator

Create campaign rule

New code 19 (collaborator, campaign scope): a campaign can now gate on whether the buyer is a collaborator of the organization. The common case is the inverse — collaborators do not earn cashback — written with reverse: true.

{ "campaign": 812, "code": 19, "params": [], "reverse": true }

The rule takes no params: the direction comes from reverse. false = only collaborators pass; true = collaborators are excluded.

The flag it reads is client.isCollaborator on the order itself — the same field rewardByOrder has accepted since June to mark the buyer as a collaborator. An order without the flag counts as NOT a collaborator, so the rule with reverse: true changes nothing for integrations that never send it.

The rule applies to purchase campaigns. On the other triggers (form-submission, last-chance, reactivate-reward) the customer is built from the register, which does not carry the flag — there it has no effect.

Improvement Lean card list by default

List cards no longer embeds the flow ledger (credit/debit history) on every row — it was ~1 KB per card, which made bulk extraction impractical. The list is now lean; for the ledger use the card flow endpoint or pass withFlow=true (only worth it for a single card or a small page). Each card's status stays on the list.

September 9, 2026

New endpoint Order listing with the whole order

List Orders (full)

The order listing returns summary rows; seeing items, payments, campaigns, history, store and customer meant one GET per order. You can now ask for the page already detailed:

GET /api/order/data/full?q[status][E]=paid&e=20

Same filters, ordering and pagination as the regular listing, and every row carries the same payload as GET /api/order/data/{idOrder}. Also available per interface: GET /api/order/{interface}/data/full, already mapped to the interface refIds.

Capped at 50 rows per page - each row carries its own items and payments, so e=0 would mean the whole history in a single response.

New endpoint NPS / CSAT by store (consolidated)

NPS by store

"NPS per store" no longer means paging the reviews and summing store by store. One call returns the overall NPS and the per-store breakdown:

GET /api/register/report/feedbackNps?days=90

Each row carries the raw components (promoters/passives/detractors), the nps, the avgRating and how many came in without a salesperson. Filter by type (nps/csat), store and period (days or dateStart/dateEnd).

September 8, 2026

Improvement Sales report: period-over-period comparison

The sales report gained a compareWith parameter:

GET /api/order/report/sales/2026-08-01/2026-08-31?groupBy=month&compareWith=previous

previous (equal-length window just before), previousYear (same dates a year back) or an explicit range YYYY-MM-DD..YYYY-MM-DD. The response adds a comparison block with the baseline total and the delta (absolute and percent) on orders, revenue and average ticket — enough to answer "sold X, +12% vs last month".

September 6, 2026

New endpoint Delivery & open rate by campaign

Delivery & open rate

Getting a campaign's open rate no longer means scanning the message log line by line (which timed out). This endpoint aggregates per channel and in total, keyed by the messageSequence a campaign carries:

GET /api/sender/report/sequence-delivery/e4dc1e58-lojas-expirados-whats

Returns opened, delivered, failed, attempted and the delivery/open rates. opened means the email was opened (Mailgun) or the WhatsApp was read. The count is per sequence: two campaigns sharing the same messageSequence add up here.

New endpoint Aggregated sales report

Sales report

Answering "how much did I sell yesterday by store" or "revenue per day this month" no longer means paging /order/data and summing client-side — there is now an endpoint that returns the number.

GET /api/order/report/sales/2026-08-01/2026-08-31?groupBy=day,store

Aggregates by day, month, store or combinations, filters by store and by status. Three decisions matter: revenue is net of cancellations by default (but the byStatus block always reports every status, canceled included, so what was excluded stays auditable); the day is cut from order_date converted to the organization timezone (a sale lands on the day it happened, not the day it synced); and updatedThrough reports the newest createAt that entered the calculation — because orders arrive after the sale, "yesterday" is a moving number.

Values in cents.

Deprecation financeSumary

financeSumary summed canceled orders, dropped the last day of the period and grouped in UTC. Use the sales report instead (groupBy=month covers its case).

September 2, 2026

New endpoint Opt-out: register who does not want to be contacted

Register · Check · Revoke · List · Count · History

There was no way to record a customer asking to stop receiving messages. There is now.

Register every identifier you have — person, e-mail and phone:

POST /api/sender/opt-preference
{ "person": 184532, "email": "cliente@exemplo.com",
  "cellphone": "5512345678", "countryCallingCode": "52" }

One row is stored per identifier and delivery is blocked when any of them matches. That is the point: if the customer signs up again and gets a new person id, the e-mail and phone still match, so the opt-out survives the new registration. If instead they change e-mail inside the same record, the person target still matches.

The opt-out is per organization. The same e-mail can be blocked in one organization and keep receiving in another — it never applies across organizations.

Everything is blocked except the login PIN. That is the only exemption — blocking it would lock the customer out of their own account.

countryCallingCode is required whenever cellphone is sent. The stored key is country code + digits; without it the key would differ from the one delivery looks up and the opt-out would silently do nothing.

Blocking is active for every organization from the start. The list begins empty, so nothing is blocked until a customer actually asks — every block corresponds to an explicit request.

August 27, 2026

Breaking change Redeem status is now redeemed, not rescued

Redeem: Settle

The word rescued suggested rescuing in the sense of saving something, not of redeeming a balance. The settled state is now called redeemed everywhere.

The response key changes. The status is the key inside redeem, not a value, so this is a shape change and not a string change:

before   {"organization": "acme", "person": 184532, "redeem": {"rescued": 1500},  "dateTime": "..."}
after    {"organization": "acme", "person": 184532, "redeem": {"redeemed": 1500}, "dateTime": "..."}

Anyone reading response.redeem.rescued gets undefined. Read response.redeem.redeemed instead — or, to survive both, take the single key of the redeem object rather than hard-coding the name.

redeemedStatus changes too. The card flow listing returns the stored value directly, so it goes from "rescued" to "redeemed".

Historical records were migrated in the same window, so there is no period where the two terms coexist in stored data. reserved and canceled are unchanged.

New endpoint POST /redeem/settle/{hash} settles a redeem reservation

Redeem: Settle

Settling a redeem reservation now has a route whose name says what it does:

POST /api/loyalty/redeem/settle/{hash}

It converts a reserved hold into a final debit, exactly as before — same handler, same response. The {hash} is the transaction id, not a card id: one call settles every card held by that reservation.

It is a POST because the call changes state — it writes the status, logs the event and triggers campaign attribution. The previous route was a GET, which is unsafe with prefetching, crawlers and automatic retries.

Deprecation GET /redeem/rescue/{hash}

Redeem: Settle

Replaced by POST /api/loyalty/redeem/settle/{hash}. The old route still works and is not scheduled for removal, but it has left the documentation.

rescue suggested rescuing in the sense of saving something, not of redeeming a balance — to the point that panel translations had inverted the meaning. The lifecycle term is reserved → redeemed, with settle as the action.

Migration is the URL and the verb. Request and response are unchanged: the response still carries "status": "rescued", since the stored value has not changed in this release.


August 26, 2026

New endpoint Guper through AI: per-person sign-in with OAuth 2.1

Guper through AI (MCP)

Every organization now has an address that MCP-capable AI assistants understand — https://{organization}.myguper.com/mcp. You paste the address into the assistant, sign in with your usual panel credentials, and the assistant operates Guper with exactly the permissions you already have.

It comes with an OAuth 2.1 authorization server with PKCE in connect:

  • GET /.well-known/oauth-authorization-server/api/connect — discovery
  • POST /api/connect/oauth/register — dynamic client registration
  • GET and POST /api/connect/oauth/authorize — authorization
  • POST /api/connect/oauth/token — code exchange and renewal
  • POST /api/connect/oauth/revoke — revocation
  • GET /api/connect/oauth/jwks — public key

The token is a JWT whose aud is the organization's canonical resource URI, and whose scope carries the permissions of the person's panel profile. A token issued for one organization is not valid in another.

Nothing changes for existing integrations. apiKey/apiSecret → token → calls remain identical, and no existing endpoint was altered. The new path sits alongside, for when the access belongs to a person and must respect their profile.


August 19, 2026

Fix confirmOrder no longer advertises accrual on anonymous sales

Confirm Order by confirmToken

When an order is confirmed with no identified customer there is nobody to credit — no reward card is created. Even so, cashback.accumulatedOrder came back filled with the predicted value rather than what was credited. Anyone reading that field showed the shopper an accrual that never existed.

On anonymous sales, redeemedOrder and accumulatedOrder now both return 0. The cashback key is still present with the same types — nothing changes for existing readers beyond the number now matching reality.

Sales with an identified customer are unaffected. So are campaigns with their own beneficiary (referral, staff): there the credit really happens even without an identified buyer, and the value is preserved.

While at it, the reference page was corrected — it still showed a response without customerId and without redeemedOrder, fields the service already returned. It now documents both cases, identified and anonymous.

Breaking change GET /api/loyalty/redeem/cancel/{hash} has been removed

Use Transaction · Cancel instead.

The endpoint no longer exists — calling it now returns 404.

It was redundant: POST /api/loyalty/transaction/cancel/{TID} goes through the same internal reservation-release process, and also covers the case redeem/cancel served — releasing a redeem reserved at checkout that never became an order (cart abandoned, payment failed). Since no reward has been credited in that scenario, there is nothing to debit: only the reservation returns to the customer's balance.

No integration is expected to be affected — the route did not receive a single production call since May 15, 2025. If you do have code calling this path, migrating means swapping the URL for transaction/cancel, using the same transaction identifier.

Before

GET /api/loyalty/redeem/cancel/{hash}

Now

POST /api/loyalty/transaction/cancel/{TID}

June 25, 2026

Improvement New path prefix /mdw/vtex/* for middleware (aligns with other mdw_*)

The middleware service now accepts a new path prefix — /mdw/vtex/* — equivalent to the legacy /api/middleware/*. Both hit the same backend with identical request/response. Prefer the new prefix for new integrations; the legacy keeps working.

Examples:

  • GET /api/middleware/interface/by/slug/ecommerce (legacy)
  • GET /mdw/vtex/interface/by/slug/ecommerce (preferred)

Motivation: align with the other integration adapters (/mdw/clip, /mdw/shopify/front) and open the door to deprecate the /api/middleware prefix in the future — without forcing a coordination window (each consumer migrates at its own pace).


June 24, 2026

New endpoint New integration service — manages integrations activated per org

Integration identity was moved out of middleware into a dedicated service. Replaces /api/middleware/interface/* and /api/middleware/source (which remain as signed facades to the new service — backward compatible, but new consumers should call /api/integration/* directly).

source — global catalog of integration types (vtex, shopify, cegid, polishop, ...). Read open; write restricted to internal Guper services.

  • GET /api/integration/source
  • GET /api/integration/source/{id}

interface — instances activated by the org (e.g. the org has VTEX ecommerce + Linx loja-fisica). The org is implicit from the signature header.

  • GET /api/integration/interface — list org's interfaces
  • GET /api/integration/interface/{id} — read by id
  • GET /api/integration/interface/by/slug/{slug} — read by slug (hot path)
  • GET /api/integration/interface/by/source/{source} — list interfaces of a given type (e.g. all the org's VTEX instances)
  • POST /api/integration/interface — create
  • PUT /api/integration/interface/{id} — update (activated accepts boolean: true activates, false deactivates)
  • DELETE /api/integration/interface/{id} — delete

Deprecation /api/middleware/interface/* and /api/middleware/source

Still functional as a transparent facade (signed proxy to integration) — no immediate breakage. Migrate consumers to /api/integration/* directly; facade removal will be announced in advance.


June 23, 2026

New endpoint external_ref endpoints in catalog (brand, category, seller)

Pattern /api/catalog/{interface}/{resource}/... to map external refIds (vtex, shopify, cegid, ...) to brands, categories and sellers. Replaces the legacy mapping via middleware (see Deprecation entry below).

Per resource (brand, category, seller):

  • GET /api/catalog/{interface}/{resource} — lists the org's refs for the interface
  • GET /api/catalog/{interface}/{resource}/{refId} — read by external refId
  • POST /api/catalog/{interface}/{resource} — find-or-create (creates entity + ref)
  • PUT /api/catalog/{interface}/{resource}/{refId} — link to existing entity
  • DELETE /api/catalog/{interface}/{resource}/{refId} — removes only the ref (entity stays)
  • POST /api/catalog/{interface}/{resource}/_resolve — bulk lookup (up to 500 refIds, returns map refId → id|null)

New endpoint external_ref endpoints in register (payment, person with role)

Pattern /api/register/{interface}/{resource}/... to map external refIds to payments and persons. Replaces the legacy mapping via middleware (see Deprecation entry below).

payment follows the same shape as catalog:

  • GET /api/register/{interface}/payment
  • POST /api/register/{interface}/payment — find-or-create
  • GET /api/register/{interface}/payment/{refId}
  • PUT /api/register/{interface}/payment/{refId} — link
  • DELETE /api/register/{interface}/payment/{refId}
  • POST /api/register/{interface}/payment/_resolve

person has role in the path (cashier, salesperson, manager, client):

  • GET /api/register/{interface}/person/{role} — list
  • GET /api/register/{interface}/person/{role}/{refId} — read
  • PUT /api/register/{interface}/person/{role}/{refId} — link to existing person
  • DELETE /api/register/{interface}/person/{role}/{refId}
  • POST /api/register/{interface}/person/{role}/_resolve

role in the PK lets the same refId map different persons in different contexts (e.g. refId=99 as cashier points to one person, as salesperson to another).

Improvement seller moved from register to catalog

Conceptually, seller is a catalog dimension (owner of inventory and products, same as brand and category), not a registry entity. It was moved to catalog and the canonical endpoint is now /api/catalog/seller/*.

/api/register/seller/* remains as a backward-compatible alias — endpoints keep responding the same but internally proxy to catalog. Existing consumers (storeManager, smartPOS, admin) don't need to change anything right now.

New code should use /api/catalog/seller/* directly.

Deprecation /api/middleware/{interface}/{resource} Reference endpoints

The CRUD endpoints for mapping external refIds in the middleware are deprecated:

  • /api/middleware/{interface}/brand
  • /api/middleware/{interface}/category
  • /api/middleware/{interface}/seller
  • /api/middleware/{interface}/payment
  • /api/middleware/{interface}/cashier
  • /api/middleware/{interface}/salesperson
  • /api/middleware/{interface}/manager
  • /api/middleware/{interface}/client

Use the equivalents in catalog (brand/category/seller) or register (payment/person/{role}) — see entries above. The legacy endpoints keep working during migration; the middleware does dual-write, keeping both paths in sync. They will be removed in a future release, with advance notice.


June 16, 2026

Deprecation GET /api/loyalty/reward (Reward Direct: Balance) is deprecated

For per-customer balance, use Report · Balance by person.

The GET /api/loyalty/reward endpoint read its parameters from a JSON body on a GET (unreliable across many clients and proxies) and required a per-organization middleware interface. It had no active callers and was already flagged as non-functional in code.

Its reference page has been removed. To get a customer's reward-card balance, use GET /api/loyalty/report/rewardBalances/person/{person} — it takes the person id in the URL, needs no body, and returns the available / expired / canceled / used breakdown per wallet.


May 12, 2026

Breaking change GET /api/loyalty/transaction/byOrder/{idOrder} now returns a list of transactions

Transaction · By Order

An order can legitimately carry more than one loyalty transaction — reward accrual and redemption issued through separate flows, partial cancellations, retries on the same checkout. The endpoint used to return a single transaction at the top level, which masked the multi-transaction case.

The response now carries the full list under transactions: [...], oldest first.

Before

{
    "TID":        "dcf33b44…",
    "order":      2467383,
    "person":     570971,
    "canceledAt": null,
    "createdAt":  "2026-01-15T16:21:44-03:00"
}

After

{
    "order":     2467383,
    "refId":     "GUP-847",
    "interface": "vtex",
    "transactions": [
        {
            "TID":        "dcf33b44…",
            "person":     570971,
            "canceledAt": null,
            "createdAt":  "2026-01-15T16:21:44-03:00"
        },
        {
            "TID":        "8c91a2b3…",
            "person":     570971,
            "canceledAt": "2026-01-20T09:14:00-03:00",
            "createdAt":  "2026-01-15T17:02:11-03:00"
        }
    ]
}

If your integration was reading body.TID at the top level, iterate body.transactions[] and pick the TID you need (typically the most recent non-cancelled one).

Shipped in loyalty v0.48.81.