Redeem member points

Description

Redeems points from a loyalty program member’s account using a trigger-based promotion.

Request URL

Method: POST

https://example.com/api/v1.1/loyalty/redeeme_points

Request parameters

Parameter	Type	Example	Required	Description
token	string	"abc123def456"	Yes	API token
loyalty_program_id	int	123	Yes	Loyalty program ID
promotion_id	string	"PROMO123"	No	Trigger promotion ID
points_currency_iid	int	1	No	Internal points currency ID
points_currency_eid	string	"stars"	No	External points currency ID (for example, "stars")
amount	string	"100.50"	Yes	Amount of points to redeem (string, supports fractional values)
is_temp	boolean	false	No	Temporary transaction flag. Can be rolled back by timeout or a separate request
temp_timeout_sec	int	123	No	Timeout in seconds after which a temporary transaction is rolled back if not confirmed
created_at	string	"2024-09-01T12:34:56Z"	No	Transaction creation date and time (current time if omitted), RFC3339
transaction_eid	string	"uiuiuiiu-ouiihfs-sdfsdf"	No	External transaction ID
external_data	object	{"order_id": "123"}	No	Arbitrary additional transaction data (JSON object)
matching	string	"email"	Yes	Profile lookup method: email, phone, profile_id, custom
field_name	string	"user_id"	Yes, if matching = custom	Custom field name for lookup
field_value	string / int	123456	Yes, if matching = custom	Custom field value
email	string	"user@example.com"	Yes, if matching = email	Member email
phone	string	"+1234567890"	Yes, if matching = phone	Member phone number in international format
profile_id	string	"profile123"	Yes, if matching = profile_id	Profile ID

Request example

JSON

{
  "token": "abc123def456",
  "loyalty_program_id": 123,
  "promotion_id": "PROMO123",
  "points_currency_eid": "stars",
  "amount": "100.50",
  "matching": "email",
  "email": "user@example.com",
  "is_temp": false,
  "transaction_eid": "uiuiuiiu-ouiihfs-sdfsdf",
  "external_data": {
    "order_id": "ORDER-123"
  }
}

XML

<xml>
  <token>abc123def456</token>
  <loyalty_program_id>123</loyalty_program_id>
  <promotion_id>PROMO123</promotion_id>
  <points_currency_eid>stars</points_currency_eid>
  <amount>100.50</amount>
  <matching>email</matching>
  <email>user@example.com</email>
  <is_temp>false</is_temp>
  <transaction_eid>uiuiuiiu-ouiihfs-sdfsdf</transaction_eid>
</xml>

Response example

JSON

{
  "error": 0,
  "error_text": "Successful operation",
  "data": {
    "transaction_id": "TRANS12345",
    "balance_before": "500.00",
    "balance_after": "399.50"
  }
}

XML

<xml>
  <error>0</error>
  <error_text>Successful operation</error_text>
  <data>
    <transaction_id>TRANS12345</transaction_id>
    <balance_before>500.00</balance_before>
    <balance_after>399.50</balance_after>
  </data>
</xml>

Response parameters

Parameter	Type	Description
error	int	Error code
error_text	string	Error text
transaction_id	string	Points redemption transaction ID
balance_before	string	Points balance before redemption
balance_after	string	Points balance after redemption