Examine rewards

Evaluates rewards assigned to a customer’s active Loyalty v2 program memberships. Applies temporary customer and member metadata overrides without updating stored data. Returns reward availability by card, including points costs and applicable unavailability reasons. Omits a reward when it is inactive, out of stock, has no matching cost, or the member has no card for that cost.

This endpoint can examine rewards for all loyalty programs the customer belongs to by using customer_identification with customer_id or customer_source_id. To examine rewards only for one program, use member_id in customer_identification, as member_id is loyalty program-specific. A customer who exists but has no active membership returns 200 with an empty memberships array.

POST /v2/loyalties/examine/rewards

Examine rewards

cURL

curl --request POST \
  --url https://{cluster}.voucherify.io/v2/loyalties/examine/rewards \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "customer_identification": {
    "customer_id": "<string>",
    "customer_source_id": "<string>",
    "member_id": "<string>"
  },
  "customer": {
    "metadata": {}
  },
  "member": {
    "metadata": {}
  }
}
'

200

Examine reward

{
  "customer": {
    "id": "cust_6onRrs4kCnvSVrTs5YtDPFBG",
    "source_id": "lx-rdmptr",
    "metadata": {
      "VIP": true
    },
    "object": "customer"
  },
  "rewards": [
    {
      "id": "lrew_128f4cab04147c8608",
      "name": "Free item coupon",
      "type": "DIGITAL",
      "metadata": {},
      "object": "reward",
      "purchase_limits": {
        "cooldown": {
          "type": "FIXED_COOLDOWN",
          "fixed_cooldown": {
            "period": {
              "value": 1,
              "unit": "DAY"
            }
          }
        },
        "frequency": {
          "type": "LIMITED",
          "limits": [
            {
              "type": "TIME_BASED",
              "period": {
                "type": "CURRENT_PERIOD",
                "current_period": {
                  "unit": "DAY"
                }
              },
              "triggers": {
                "max": 1
              }
            }
          ]
        }
      }
    },
    {
      "id": "lrew_128f4c6710947c85d1",
      "name": "Minas Gerais 500",
      "type": "MATERIAL",
      "metadata": {},
      "object": "reward",
      "purchase_limits": {
        "cooldown": {
          "type": "NO_COOLDOWN"
        },
        "frequency": {
          "type": "NO_LIMIT",
          "limits": []
        }
      }
    },
    {
      "id": "lrew_1294cebb458e4904a0",
      "name": "Carioca shirt",
      "type": "MATERIAL",
      "metadata": {},
      "object": "reward",
      "purchase_limits": {
        "cooldown": {
          "type": "NO_COOLDOWN"
        },
        "frequency": {
          "type": "NO_LIMIT",
          "limits": []
        }
      }
    },
    {
      "id": "lrew_12b22d6ef31184e002",
      "name": "Carioca shorts",
      "type": "MATERIAL",
      "metadata": {},
      "object": "reward",
      "purchase_limits": {
        "cooldown": {
          "type": "NO_COOLDOWN"
        },
        "frequency": {
          "type": "NO_LIMIT",
          "limits": []
        }
      }
    },
    {
      "id": "lrew_12bb65405edf8d3dec",
      "name": "Carioca longsleeve",
      "type": "MATERIAL",
      "metadata": {},
      "object": "reward",
      "purchase_limits": {
        "cooldown": {
          "type": "NO_COOLDOWN"
        },
        "frequency": {
          "type": "NO_LIMIT",
          "limits": []
        }
      }
    }
  ],
  "memberships": [
    {
      "member": {
        "id": "lmbr_128f962dbc8c4ba5dc",
        "customer_id": "cust_6onRrs4kCnvSVrTs5YtDPFBG",
        "program_id": "lprg_128f58429f4c4bf7b2",
        "metadata": {},
        "object": "member"
      },
      "program": {
        "id": "lprg_128f58429f4c4bf7b2",
        "name": "AnnualProgram",
        "metadata": {},
        "object": "program"
      },
      "cards": [
        {
          "card": {
            "id": "lcrd_128f962dbd8c4ba5e1",
            "card_definition_id": "lcdef_128f4a88414c4bed69",
            "card_type": "INDIVIDUAL",
            "code": "AnnualTime-7M7ShPGfme",
            "object": "card"
          },
          "rewards": [
            {
              "reward": {
                "id": "lrew_128f4cab04147c8608",
                "object": "reward"
              },
              "status": "AVAILABLE",
              "cost": {
                "points": 300,
                "object": "reward_cost"
              },
              "object": "reward_estimation"
            },
            {
              "reward": {
                "id": "lrew_128f4c6710947c85d1",
                "object": "reward"
              },
              "status": "AVAILABLE",
              "cost": {
                "points": 150,
                "object": "reward_cost"
              },
              "object": "reward_estimation"
            },
            {
              "reward": {
                "id": "lrew_1294cebb458e4904a0",
                "object": "reward"
              },
              "status": "AVAILABLE",
              "cost": {
                "points": 500,
                "object": "reward_cost"
              },
              "object": "reward_estimation"
            }
          ],
          "object": "card_estimation"
        },
        {
          "card": {
            "id": "lcrd_128f962dbd8c4ba5df",
            "card_definition_id": "lcdef_128f495f720c4bec8c",
            "card_type": "INDIVIDUAL",
            "code": "SummerTime-7z8dWawICd",
            "object": "card"
          },
          "rewards": [
            {
              "reward": {
                "id": "lrew_12b22d6ef31184e002",
                "object": "reward"
              },
              "status": "UNAVAILABLE",
              "cost": {
                "points": 321,
                "object": "reward_cost"
              },
              "unavailability_reasons": [
                {
                  "reason": "insufficient_balance",
                  "details": {
                    "required": 321,
                    "available": 10,
                    "missing": 311
                  },
                  "object": "reward_unavailability_reason"
                }
              ],
              "object": "reward_estimation"
            }
          ],
          "object": "card_estimation"
        }
      ],
      "object": "member_rewards_opportunity"
    }
  ],
  "object": "rewards_examine_result"
}

Authorizations

X-App-Id & X-App-TokenbearerAuth

X-App-Id · string · header · required

X-App-Token · string · header · required

Body

application/json

Request body schema for POST /v2/loyalties/examine/rewards.

customer_identification · object · required

Identifies the customer or loyalty member to examine.

Show child attributes

customer · object

Provides temporary customer metadata overrides for the examination. Merges them with stored metadata without updating the customer.

Show child attributes

member · object

Overrides member metadata for this examination. Send it only when customer_identification.type is member_id. Merges the override with stored metadata without updating the member.

Show child attributes

Response

200

application/json

Rewards examination result. An empty memberships array means the customer has no active membership. An empty cards array means no assigned reward resolved onto a card.

Response body schema for POST /v2/loyalties/examine/rewards.

customer · object · required

Identifies the customer used for the examination.

Show child attributes

rewards · Loyalties Examine Rewards Examine Response Body Reward Detail · object[] · required

Lists rewards that resolved a points cost and appear on a returned card. Omits a reward when it is inactive, out of stock, has no matching cost, or the member has no card for that cost.

Show child attributes

memberships · Loyalties Examine Rewards Examine Response Body Membership · object[] · required

Lists one entry for each active membership whose program has reward assignments. cards can be empty when none of those rewards resolve onto a card.

Show child attributes

object · string · required

Object type marker. Always rewards_examine_result.

Allowed value: "rewards_examine_result"