Skip to content
platform
EN PT

API reference · CashBack

Grant Cashback for External Order

Method
POST
Route
/loyaltyProgram/earnRewardExternal
Base URL
https://ws.autorei.net
Token
Requires Bearer token
Test in Postman

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

Description

Grants cashback to a customer from an order that happened outside the CWS Platform — a sale at your counter, on your own e-commerce site or in another channel. You provide who bought, the order number in your system and the items; the loyalty program calculates how much each item earns and records the credit.

Request body (JSON)

Field Type Required Description
Customer identification — Yes It is not a field — it is a group. Send cpfCnpj or email; see the rule below.
cpfCnpj string Conditional Customer CPF or CNPJ. Required if email is not sent.
email string Conditional Customer login email in your store. Required if cpfCnpj is not sent.
externalOrderId string Yes Order number in your system. Unique per store — see the rule below.
status string No Initial status of the credit. TO_RELEASE, RELEASED, CANCELLED or INVALID_EXPIRED. If omitted, the credit is created as TO_RELEASE.
timeToReleasePoints integer No Grace period in days before the credit is released. Cannot be negative. If omitted, the grace period configured in the store's loyalty program applies.
orderItems array Yes Order items. Cannot be an empty list.
orderItems[].documentPartner string Yes Document of the partner that sold the item. See the marketplace rule below.
Product identification — Yes It is not a field — it is a group. In each item, send skuId or partnerPartCode.
orderItems[].skuId integer Conditional Product id at CWS. Required if partnerPartCode is not sent.
orderItems[].partnerPartCode string Conditional Product code in your catalog, as registered in inventory. Required if skuId is not sent.
orderItems[].deliveryDate string Yes Item delivery date, in the format YYYY-MM-DD.
orderItems[].quantity integer Yes Item quantity. Must be greater than zero.
orderItems[].unitaryValue number Yes Item unit price. Must be greater than zero.

Business rules

One customer, by document or by email

Send one of the two. The customer must already exist in the authenticated store: a customer from another store, or a document with no record, is rejected. If you send both, cpfCnpj is the one that counts.

externalOrderId is the key against double credit

The external order number is unique per partner. A second call with the same externalOrderId is rejected, not duplicated — this is what protects the integration from granting cashback twice when a delivery is reprocessed. Use the real order number in your system, not a value generated on each attempt.

documentPartner and the marketplace sale

The document provided in each item defines who sold that item. When it is the document of the authenticated partner itself, nothing else is required. When it is the document of another partner, an authorized marketplace partnership must exist between your store and that partner — otherwise the item is rejected.

The cashback amount is calculated by the platform, not sent

You provide quantity and unit price; how much that earns is decided by the rules of the store's loyalty program (product category and manufacturer, configured percentage). An item that does not fit any rule is recorded with a zero value — it does not cause an error and does not prevent the rest of the order.

Rejection applies to the entire order

Any rejected item brings down the entire request and nothing is saved — there is no partial result. When the rejection is product not found, the message lists all the items that were not located at once, so you do not discover them one per call.

Response · 200

Array with one object per accepted item, in the order you sent them.

Field Type Description
earning number Cashback generated by the item. A number, not a string — and unrounded: expect values like 0.49950000000000006. Comes as 0 when the item does not fit any program rule.
type string Type of the strategy applied. CASHBACK.
value number Balance amount consumed in the operation. Always 0 in this grant.
valueType string Comes as "" in this operation.
Reserve object Echo of the item as the platform interpreted it. The key starts with a capital letter.
Reserve.skuId integer CWS product id — useful when you identified the item by partnerPartCode.
Reserve.qty integer Quantity sent.
Reserve.unitaryValue number Unit price sent.
Reserve.deliveryDate string Delivery date sent.
Reserve.externalOrderId string External order number sent.
Reserve.partnerId integer Partner id resolved from the documentPartner.
Reserve.storeName string Subdomain of the authenticated store.
Reserve.brandId integer Product manufacturer id.
Reserve.categories array Ids of the categories the product belongs to.

Errors

Code When
422 Any validation or business rule rejection: customer not identified or nonexistent, externalOrderId missing or repeated, status outside the list, negative timeToReleasePoints, empty orderItems, item without product identification, without documentPartner, without deliveryDate or with a date in an invalid format, zero quantity or unitaryValue, product not found in the partner's catalog, unknown documentPartner, or unauthorized marketplace partnership. The specific reason comes in the message.
401 Token missing, malformed or expired.

The rejection comes as a list of messages:

{"total":1,"errors":[{"message":"Número de pedido externo já está associado a outro cashback concedido."}]}

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

Example request

curl --request POST 'https://ws.autorei.net/loyaltyProgram/earnRewardExternal' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'Content-Type: application/json' \
  --data '{
  "cpfCnpj": "70041364856",
  "externalOrderId": "PED-EXT-900201",
  "status": "TO_RELEASE",
  "orderItems": [
    {
      "documentPartner": "30424972000174",
      "skuId": 500101,
      "deliveryDate": "2026-09-10",
      "quantity": 2,
      "unitaryValue": 150.0
    },
    {
      "documentPartner": "30424972000174",
      "partnerPartCode": "SKU-B-002",
      "deliveryDate": "2026-09-10",
      "quantity": 1,
      "unitaryValue": 80.0
    }
  ]
}'

Example responses

200Success — external order with two items

[
  {
    "Reserve": {
      "brandId": 12593,
      "qty": 2,
      "storeName": "lojaexemplo",
      "partnerId": 4471,
      "categories": [
        26881,
        26903
      ],
      "externalOrderId": "PED-EXT-900201",
      "deliveryDate": "2026-09-10",
      "skuId": 500101,
      "unitaryValue": 150
    },
    "valueType": "",
    "type": "CASHBACK",
    "value": 0,
    "earning": 1.5
  },
  {
    "Reserve": {
      "brandId": 14713,
      "qty": 1,
      "storeName": "lojaexemplo",
      "partnerId": 4471,
      "categories": [
        26885,
        26878,
        26935
      ],
      "externalOrderId": "PED-EXT-900201",
      "deliveryDate": "2026-09-10",
      "skuId": 500102,
      "unitaryValue": 80
    },
    "valueType": "",
    "type": "CASHBACK",
    "value": 0,
    "earning": 0
  }
]

422Rejected — external order already granted

{
  "total": 1,
  "errors": [
    {
      "message": "Número de pedido externo já está associado a outro cashback concedido."
    }
  ]
}

Used in

Related endpoints

← See the group: CashBack

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