Skip to content
platform
EN PT

API reference · CashBack

Update External Order Cashback

Method
PUT
Route
/loyaltyProgram/earnRewardExternal
Base URL
https://ws.autorei.net
Query parameters in the example
externalOrderId=PED-EXT-900201
Token
Requires Bearer token
Test in Postman

Opens this request in the public API documentation, the official source of the reference.

Description

Changes a cashback already granted for an external order: releases the credit that was in the grace period, cancels the grant, corrects the amount or the delivery date. The order is identified by the same externalOrderId used in the grant.

Query Parameters

Parameter Type Required Description
externalOrderId string Yes External order number, as sent in POST /loyaltyProgram/earnRewardExternal. It goes in the query string, not in the body.

Request Body (JSON)

Field Type Required Description
documentPartner string Yes Document of the partner that owns the grant. Same marketplace rule as the grant.
status string No New credit status: TO_RELEASE, RELEASED, CANCELLED or INVALID_EXPIRED.
earning number No New total cashback value for the order. See the rule below.
orderDeliveryDate string No New delivery date, in the format YYYY-MM-DD.
timeToReleasePoints integer No New grace period, in days, before the credit is released.

Do not send partnerId: it is resolved by the backend from the documentPartner.

Business rules

Only cashback in the grace period can be changed

The update reaches only entries that are still in TO_RELEASE. An order whose cashback has already been released, canceled, or expired responds 404 — even though it exists. In practice: the window to correct the grant is the grace period.

The update applies to the whole order

An external order with several items generated one entry per item, and the update is applied to all of them at once. There is no way to change just one item of the order through this route.

earning is the order total, split across the items

The value sent in earning is the cashback for the order, not for each item: in an order with two items, "earning": 10 writes 5 in each entry. Omit the field when you are not correcting the amount — the cashback calculated at the time of the grant is preserved.

Response · 200

Array with one object per updated entry — one per item of the external order. Omitting status keeps the current status and applies only the other fields sent.

Field Type Description
id uuid Cashback entry id.
externalOrderId string External order number.
skuId integer CWS product id of the entry.
value number Entry value after the update. Number, unlike the query endpoints, which return a string.
status string Status after the update.
type string Strategy type. CASHBACK.
createDate string Date and time of the original grant, in UTC.
orderDeliveryDate string Order delivery date, with offset (2026-09-10T00:00:00-03:00).
releaseDate string Date the credit was released. The field only exists when the entry is RELEASED — in other statuses it does not come in the response.
timeToReleasePoints integer Grace period in days in effect on the entry.
timeToExpire integer Days of validity of the credit after it is released, according to the store's program.
cumulative boolean Whether the credit stacks with other loyalty strategies.
partnerId integer Partner id resolved from the documentPartner.
ownerStoreId integer Id of the store that owns the program.
ownerStoreName string Store subdomain.
ownerStoreEmail string Store contact email.
customerRewardId uuid Id of the customer's cashback wallet.
loyaltyStrategyId uuid Id of the loyalty strategy that originated the credit.
orderId · partnerOrderId integer Order ids on the platform. They come as 0 in external-order cashback, which has no CWS order.

Errors

Code When
422 externalOrderId missing from the query, documentPartner missing or unknown, status outside the list, or marketplace partnership not authorized. The reason is in the message.
404 No entry to update: the externalOrderId does not exist, or exists and no entry is in TO_RELEASE. The message distinguishes the two cases — read errors[].message.
401 Token missing, malformed, or expired.

The rejection comes as a list of messages:

{"total":1,"errors":[{"message":"Nenhum registro encontrado com o número do pedido externo informado."}]}

Read the reason in errors[].message; total is the number of messages.

Example request

curl --request PUT 'https://ws.autorei.net/loyaltyProgram/earnRewardExternal?externalOrderId=PED-EXT-900201' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "documentPartner": "30424972000174",
  "status": "RELEASED",
  "earning": 12.34,
  "orderDeliveryDate": "2026-09-12"
}'

Example responses

200Success — cashback released

[
  {
    "ownerStoreEmail": "contato@lojaexemplo.com.br",
    "orderDeliveryDate": "2026-09-12T00:00:00-03:00",
    "orderId": 0,
    "partnerOrderId": 0,
    "releaseDate": "2026-09-12T00:00:00-03:00",
    "ownerStoreName": "lojaexemplo",
    "externalOrderId": "PED-EXT-900201",
    "type": "CASHBACK",
    "cumulative": false,
    "timeToReleasePoints": 30,
    "timeToExpire": 90,
    "customerRewardId": "6cf135ce-46a6-411d-82ad-c9a4e2c0ade1",
    "loyaltyStrategyId": "b78d03a7-5186-4d3e-8421-05d45cd3de0e",
    "ownerStoreId": 4470,
    "id": "5eab5e68-c57d-4ef3-8d57-2a809be4f810",
    "partnerId": 4471,
    "value": 6.17,
    "skuId": 500101,
    "createDate": "2026-09-04T14:15:02.534996Z",
    "status": "RELEASED"
  },
  {
    "ownerStoreEmail": "contato@lojaexemplo.com.br",
    "orderDeliveryDate": "2026-09-12T00:00:00-03:00",
    "orderId": 0,
    "partnerOrderId": 0,
    "releaseDate": "2026-09-12T00:00:00-03:00",
    "ownerStoreName": "lojaexemplo",
    "externalOrderId": "PED-EXT-900201",
    "type": "CASHBACK",
    "cumulative": false,
    "timeToReleasePoints": 30,
    "timeToExpire": 90,
    "customerRewardId": "6cf135ce-46a6-411d-82ad-c9a4e2c0ade1",
    "loyaltyStrategyId": "b78d03a7-5186-4d3e-8421-05d45cd3de0e",
    "ownerStoreId": 4470,
    "id": "dfc74296-d75d-4dc0-bd90-3a8af69ada33",
    "partnerId": 4471,
    "value": 6.17,
    "skuId": 500102,
    "createDate": "2026-09-04T14:15:02.534996Z",
    "status": "RELEASED"
  }
]

Used in

Related endpoints

← See the group: CashBack

Generated from the public API collection, published on 2026-09-04: api-docs.cws.digital.