---
title: 'Release notes'
description: 'Behaviour changes, new endpoints and fixes shipped to the Guper API. Newest first.'
---

# Release notes

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

Each entry is tagged:

- <span class="rn-tag rn-tag--breaking">Breaking change</span> — request or response contract changed; callers need to adapt.
- <span class="rn-tag rn-tag--new">New endpoint</span> — endpoint added.
- <span class="rn-tag rn-tag--improvement">Improvement</span> — backward-compatible change.
- <span class="rn-tag rn-tag--fix">Fix</span> — corrects wrong behaviour without changing the contract.
- <span class="rn-tag rn-tag--deprecated">Deprecation</span> — endpoint discontinued; migrate to the listed alternative.

---

## November 12, 2026

### <span class="rn-tag rn-tag--improvement">Improvement</span> Expired balance in the cards report

[Cashback issued & redeemed by campaign (aggregate)](/docs/{lang}/api-reference/loyalty/report/cards)

`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

### <span class="rn-tag rn-tag--new">New endpoint</span> Update customers in batch

[Update customers in batch](/docs/{lang}/api-reference/register/customer/update-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.

### <span class="rn-tag rn-tag--new">New endpoint</span> Cancel and reactivate cards in batch

[Cancel Cards in Batch](/docs/{lang}/api-reference/loyalty/card/cancel-batch) · [Reactivate Cards in Batch](/docs/{lang}/api-reference/loyalty/card/reactivate-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

### <span class="rn-tag rn-tag--new">New endpoint</span> Cancel and reactivate a card

[Cancel Card](/docs/{lang}/api-reference/loyalty/card/cancel) · [Reactivate Card](/docs/{lang}/api-reference/loyalty/card/reactivate)

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](/docs/{lang}/api-reference/loyalty/card/adjust) 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](/docs/{lang}/guides/loyalty-cancellation) guide.

## November 5, 2026

### <span class="rn-tag rn-tag--improvement">Improvement</span> Order date in Reward by Order

[Reward by Order](/docs/{lang}/api-reference/loyalty/checkout/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

### <span class="rn-tag rn-tag--improvement">Improvement</span> Audience by active card

[Query Audience (QON)](/docs/{lang}/api-reference/register/audience-query/qon-query)

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

### <span class="rn-tag rn-tag--new">New endpoint</span> One entity's refIds, without scanning the interface

[List refs of a Category](/docs/{lang}/api-reference/catalog/category/by-entity/list) · [of a Brand](/docs/{lang}/api-reference/catalog/brand/by-entity/list) · [of a Seller](/docs/{lang}/api-reference/catalog/seller/by-entity/list) · [of a Payment](/docs/{lang}/api-reference/register/payment/by-entity/list)

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.

### <span class="rn-tag rn-tag--fix">Fix</span> 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).

### <span class="rn-tag rn-tag--improvement">Improvement</span> Products report broken down by store and time

[Top products sold](/docs/{lang}/api-reference/order/report/products)

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

### <span class="rn-tag rn-tag--new">New endpoint</span> Validate your payload before integrating

[Validate your payload](/docs/{lang}/guides/payload-validation)

`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

### <span class="rn-tag rn-tag--improvement">Improvement</span> "Different from" on the Entity type rule

[Campaign rules: Create](/docs/{lang}/api-reference/loyalty/campaign/campaign-rules/create)

The **Entity type** campaign rule ([`code` 11](/docs/{lang}/api-reference/loyalty/campaign/campaign-rules/create)) 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

### <span class="rn-tag rn-tag--improvement">Improvement</span> List messages by phone, with the body, in one call

[Messages: List](/docs/{lang}/api-reference/sender/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.

### <span class="rn-tag rn-tag--improvement">Improvement</span> Purchase type on rewardByOrder

[Reward by order](/docs/{lang}/api-reference/loyalty/checkout/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](/docs/{lang}/api-reference/loyalty/campaign/campaign-rules/create)) 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

### <span class="rn-tag rn-tag--improvement">Improvement</span> Revenue broken down, from list price to net

[Sales report](/docs/{lang}/api-reference/order/report/sales)

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

### <span class="rn-tag rn-tag--new">New endpoint</span> Sync store ↔ policy links

[Sync store ↔ policy links](/docs/{lang}/api-reference/register/stores/store-wallet-link/sync)

`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`.

### <span class="rn-tag rn-tag--improvement">Improvement</span> Redemption policies compete with each other

[Redemption policies](/docs/{lang}/guides/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](/docs/{lang}/api-reference/loyalty/checkout/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

### <span class="rn-tag rn-tag--improvement">Improvement</span> Per-api-key permissions

[Grant Access Scope](/docs/{lang}/api-reference/connect/api/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

### <span class="rn-tag rn-tag--improvement">Improvement</span> Draft campaigns

[List Campaigns](/docs/{lang}/api-reference/loyalty/campaign/list)

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

### <span class="rn-tag rn-tag--improvement">Improvement</span> Campaign status in the list

[List Campaigns](/docs/{lang}/api-reference/loyalty/campaign/list)

`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

### <span class="rn-tag rn-tag--breaking">Breaking change</span> Expired tokens are no longer accepted

[Get token](/docs/{lang}/api-reference/connect/api/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](/docs/{lang}/api-reference/connect/api/get-token) again.

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

### <span class="rn-tag rn-tag--new">New endpoint</span> Audience targeted by period

[Audience by period](/docs/{lang}/api-reference/loyalty/report/audience)

`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

### <span class="rn-tag rn-tag--new">New endpoint</span> Delivery and open rate by period

[Delivery by period](/docs/{lang}/api-reference/sender/report/delivery)

`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.

### <span class="rn-tag rn-tag--improvement">Improvement</span> Providers that never confirm delivery no longer drag the rate down

[Delivery by campaign](/docs/{lang}/api-reference/sender/report/sequence-delivery)

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

### <span class="rn-tag rn-tag--new">New endpoint</span> Notification campaign funnel

[Notification funnel](/docs/{lang}/api-reference/loyalty/report/notifications)

`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%.

### <span class="rn-tag rn-tag--improvement">Improvement</span> Campaign and origin rankings return the net

[Sales report](/docs/{lang}/api-reference/order/report/sales)

`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

### <span class="rn-tag rn-tag--improvement">Improvement</span> Sales report: tier breakdown and filter, store lists, and the discount warning

[Sales report](/docs/{lang}/api-reference/order/report/sales)

`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

### <span class="rn-tag rn-tag--breaking">Breaking change</span> `PUT /api/connect/user` requires `login`

[Update User](/docs/{lang}/api-reference/connect/user/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.

### <span class="rn-tag rn-tag--improvement">Improvement</span> Attempt lock on sign-in and token issuing

[Auth](/docs/{lang}/api-reference/connect/user/auth) · [Get token](/docs/{lang}/api-reference/connect/api/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

### <span class="rn-tag rn-tag--improvement">Improvement</span> Attributed, influenced and impacted sales in the sales report

[Sales report](/docs/{lang}/api-reference/order/report/sales)

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

### <span class="rn-tag rn-tag--improvement">Improvement</span> Redemption policy: dynamic minimum order (`minOrderRate`)

[Redemption policy](/docs/{lang}/api-reference/loyalty/wallet/read) · [Reward by order](/docs/{lang}/api-reference/loyalty/checkout/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.

### <span class="rn-tag rn-tag--new">New endpoint</span> Cashback time to redeem

[Time to redeem](/docs/{lang}/api-reference/loyalty/report/redemption-latency)

`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

### <span class="rn-tag rn-tag--improvement">Improvement</span> 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.

### <span class="rn-tag rn-tag--new">New endpoint</span> Cashback redemptions with order and stores

[Cashback redemptions](/docs/{lang}/api-reference/loyalty/report/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.

### <span class="rn-tag rn-tag--fix">Fix</span> Cashback cards: a redemption counts only once the sale is settled

[Cashback cards](/docs/{lang}/api-reference/loyalty/report/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.

### <span class="rn-tag rn-tag--improvement">Improvement</span> 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.

### <span class="rn-tag rn-tag--improvement">Improvement</span> 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.

### <span class="rn-tag rn-tag--improvement">Improvement</span> 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.

```json
{ "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

### <span class="rn-tag rn-tag--improvement">Improvement</span> 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`.

### <span class="rn-tag rn-tag--new">New endpoint</span> Program members / associates report

[Program associates](/docs/{lang}/api-reference/register/report/members)

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.

### <span class="rn-tag rn-tag--improvement">Improvement</span> 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`.

### <span class="rn-tag rn-tag--new">New endpoint</span> Top products sold

[Top products sold](/docs/{lang}/api-reference/order/report/products)

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

### <span class="rn-tag rn-tag--new">New endpoint</span> RFM by acquisition cohort

[RFM by cohort](/docs/{lang}/api-reference/register/report/rfm-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).

### <span class="rn-tag rn-tag--new">New endpoint</span> Cashback cards report (issued & redeemed)

[Cashback cards](/docs/{lang}/api-reference/loyalty/report/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).

### <span class="rn-tag rn-tag--improvement">Improvement</span> Sales report: channel, discounts and cohort

The [sales report](/docs/{lang}/api-reference/order/report/sales) gained
`groupBy=interface` (share by channel), a `discounts` metric and a `client`
filter (a list of client ids — a cohort/experiment).

## September 10, 2026

### <span class="rn-tag rn-tag--improvement">Improvement</span> Campaign rule: customer is a collaborator

[Create campaign rule](/docs/{lang}/api-reference/loyalty/campaign/campaign-rules/create)

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`.

```json
{ "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.

### <span class="rn-tag rn-tag--improvement">Improvement</span> Lean card list by default

[List cards](/docs/{lang}/api-reference/loyalty/card/list) 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

### <span class="rn-tag rn-tag--new">New endpoint</span> Order listing with the whole order

[List Orders (full)](/docs/{lang}/api-reference/order/order/list-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.

### <span class="rn-tag rn-tag--new">New endpoint</span> NPS / CSAT by store (consolidated)

[NPS by store](/docs/{lang}/api-reference/register/report/feedback-nps)

"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

### <span class="rn-tag rn-tag--improvement">Improvement</span> Sales report: period-over-period comparison

The [sales report](/docs/{lang}/api-reference/order/report/sales) 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

### <span class="rn-tag rn-tag--new">New endpoint</span> Delivery & open rate by campaign

[Delivery & open rate](/docs/{lang}/api-reference/sender/report/sequence-delivery)

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.

### <span class="rn-tag rn-tag--new">New endpoint</span> Aggregated sales report

[Sales report](/docs/{lang}/api-reference/order/report/sales)

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.

### <span class="rn-tag rn-tag--deprecated">Deprecation</span> financeSumary

`financeSumary` summed canceled orders, dropped the last day of the period and
grouped in UTC. Use the [sales report](/docs/{lang}/api-reference/order/report/sales)
instead (`groupBy=month` covers its case).

## September 2, 2026

### <span class="rn-tag rn-tag--new">New endpoint</span> Opt-out: register who does not want to be contacted

[Register](/docs/{lang}/api-reference/sender/opt-preference/create) ·
[Check](/docs/{lang}/api-reference/sender/opt-preference/lookup) ·
[Revoke](/docs/{lang}/api-reference/sender/opt-preference/delete) ·
[List](/docs/{lang}/api-reference/sender/opt-preference/list) ·
[Count](/docs/{lang}/api-reference/sender/opt-preference/count) ·
[History](/docs/{lang}/api-reference/sender/opt-preference/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

### <span class="rn-tag rn-tag--breaking">Breaking change</span> Redeem status is now `redeemed`, not `rescued`

[Redeem: Settle](/docs/{lang}/api-reference/loyalty/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.

### <span class="rn-tag rn-tag--new">New endpoint</span> `POST /redeem/settle/{hash}` settles a redeem reservation

[Redeem: Settle](/docs/{lang}/api-reference/loyalty/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.

### <span class="rn-tag rn-tag--deprecated">Deprecation</span> `GET /redeem/rescue/{hash}`

[Redeem: Settle](/docs/{lang}/api-reference/loyalty/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

### <span class="rn-tag rn-tag--new">New endpoint</span> Guper through AI: per-person sign-in with OAuth 2.1

[Guper through AI (MCP)](/docs/{lang}/guides/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

### <span class="rn-tag rn-tag--fix">Fix</span> `confirmOrder` no longer advertises accrual on anonymous sales

[Confirm Order by confirmToken](/docs/{lang}/api-reference/loyalty/checkout/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.

### <span class="rn-tag rn-tag--breaking">Breaking change</span> `GET /api/loyalty/redeem/cancel/{hash}` has been removed

Use [Transaction · Cancel](/docs/{lang}/api-reference/loyalty/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

### <span class="rn-tag rn-tag--improvement">Improvement</span> 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

### <span class="rn-tag rn-tag--new">New endpoint</span> 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

### <span class="rn-tag rn-tag--deprecated">Deprecation</span> `/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

### <span class="rn-tag rn-tag--new">New endpoint</span> 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`)

### <span class="rn-tag rn-tag--new">New endpoint</span> 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).

### <span class="rn-tag rn-tag--improvement">Improvement</span> `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.

### <span class="rn-tag rn-tag--deprecated">Deprecation</span> `/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

### <span class="rn-tag rn-tag--deprecated">Deprecation</span> `GET /api/loyalty/reward` (Reward Direct: Balance) is deprecated

For per-customer balance, use [Report · Balance by person](/docs/{lang}/api-reference/loyalty/report/reward-balances-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

### <span class="rn-tag rn-tag--breaking">Breaking change</span> `GET /api/loyalty/transaction/byOrder/{idOrder}` now returns a list of transactions

[Transaction · By Order](/docs/{lang}/api-reference/loyalty/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**

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

**After**

```json
{
    "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`.
