Redeem Reward

curl --request POST \
  --url https://{cluster}.voucherify.io/v1/loyalties/members/{memberId}/redemption \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "reward": {
    "id": "rew_INt3fGH3n7xIr3ZQcq4kkUZ1",
    "points": 100
  },
  "order": {
    "items": [
      {
        "product_id": "prod_0c5d6689b39320059b",
        "quantity": "1"
      },
      {
        "product_id": "prod_0b2c36568000039138",
        "quantity": "2"
      }
    ]
  }
}
'

{
  "id": "r_0c6b4bf721439bf02b",
  "object": "redemption",
  "date": "2023-02-06T10:23:12.517Z",
  "customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
  "tracking_id": "track_9B0kB92+bJa8a+PegaWREw==",
  "metadata": null,
  "amount": 100,
  "result": "SUCCESS",
  "order": {
    "id": "ord_71Ayjxq2gFV80v3OP3qrxh37",
    "source_id": null,
    "created_at": "2023-02-06T10:23:12.485Z",
    "updated_at": null,
    "status": "PAID",
    "amount": 45000,
    "discount_amount": 2000,
    "total_discount_amount": 2000,
    "total_amount": 43000,
    "applied_discount_amount": 2000,
    "total_applied_discount_amount": 2000,
    "items": [
      {
        "object": "order_item",
        "product_id": "prod_0c5d6689b39320059b",
        "quantity": 1,
        "product": {
          "id": "prod_0c5d6689b39320059b",
          "source_id": "prod_anJ03RZZq74z4v",
          "name": "Apple iPhone 8"
        }
      },
      {
        "object": "order_item",
        "product_id": "prod_0b2c36568000039138",
        "quantity": 2,
        "amount": 45000,
        "price": 22500,
        "subtotal_amount": 45000,
        "product": {
          "id": "prod_0b2c36568000039138",
          "source_id": "86",
          "name": "[Sample] Able Brewing System",
          "price": 22500
        }
      }
    ],
    "metadata": {},
    "customer": {
      "id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
      "object": "customer"
    },
    "customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
    "referrer_id": null,
    "object": "order",
    "redemptions": {
      "r_0c6b4bf721439bf02b": {
        "date": "2023-02-06T10:23:12.517Z",
        "related_object_type": "voucher",
        "related_object_id": "v_u3dRiZ0XHqX5Euhy5ezB5UQ5Sf85VXFP",
        "related_object_parent_id": "camp_22noMlhTADb7Fq2UL3vWu3d1"
      }
    }
  },
  "customer": {
    "id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
    "name": "Bob Jones",
    "email": "bob.jones@email.com",
    "source_id": "36_bob",
    "metadata": {
      "age": 26,
      "favorite_brands": [
        "Nike",
        "Adidas",
        "Reebok"
      ],
      "accepts_marketing": false,
      "acquisition_channel": "Facebook"
    },
    "object": "customer"
  },
  "related_object_type": "voucher",
  "related_object_id": "v_u3dRiZ0XHqX5Euhy5ezB5UQ5Sf85VXFP",
  "voucher": {
    "id": "v_u3dRiZ0XHqX5Euhy5ezB5UQ5Sf85VXFP",
    "code": "AnsvocvP",
    "campaign": "Loyalty Campaign - Test Points",
    "campaign_id": "camp_22noMlhTADb7Fq2UL3vWu3d1",
    "category": null,
    "category_id": "cat_0bb81a481615a37b5e",
    "categories": [],
    "type": "LOYALTY_CARD",
    "discount": null,
    "gift": null,
    "loyalty_card": {
      "points": 9000,
      "balance": 5374
    },
    "start_date": null,
    "expiration_date": null,
    "validity_timeframe": null,
    "validity_day_of_week": null,
    "active": true,
    "additional_info": null,
    "metadata": {},
    "assets": {
      "qr": {
        "id": "U2FsdGVkX1/Au841M0T7UjYYRxYTzCRbNdZW6jW5YRNcV9PgblvN2MD5hdRuZfBRHEAm+d2pvzc2FOVHFkuh9BQoaIq4KVyvy0FvkWtKkMLe4zO+qL4ocNUIbaRMSLeY6Xiz4hjxKNq918oLyGrp9w==",
        "url": "{{internalVoucherifyURL}}"
      },
      "barcode": {
        "id": "U2FsdGVkX1+xG42zWo9nivfp6tg5jNuFCYOIFtw7iwas8kcA/8H4gu04dxO/hrbD41gFvxDhCuTSnIKwIPg9dEXzOvh8qy9VWN0UwDc6PL7lfNQuY+8Os7dqVsyNhoRned9pBo1uO6V4pjNu1gRTrw==",
        "url": "{{internalVoucherifyURL}}"
      }
    },
    "is_referral_code": false,
    "created_at": "2022-11-10T06:28:59.970Z",
    "updated_at": "2023-02-06T10:23:12.517Z",
    "holder_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
    "holder": {
      "id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
      "source_id": "36_bob",
      "metadata": {
        "age": 26,
        "favorite_brands": [
          "Nike",
          "Adidas",
          "Reebok"
        ],
        "accepts_marketing": false,
        "acquisition_channel": "Facebook"
      },
      "object": "customer"
    },
    "validation_rules_assignments": {
      "object": "list",
      "data_ref": "data",
      "data": [],
      "total": 0
    },
    "redemption": {
      "quantity": null,
      "redeemed_quantity": 16,
      "redeemed_points": 3626,
      "object": "list",
      "url": "/v1/vouchers/AnsvocvP/redemptions?page=1&limit=10"
    },
    "publish": {
      "object": "list",
      "count": 1,
      "url": "/v1/vouchers/AnsvocvP/publications?page=1&limit=10"
    },
    "object": "voucher",
    "applicable_to": {
      "data": [],
      "total": 0,
      "data_ref": "data",
      "object": "list"
    },
    "inapplicable_to": {
      "data": [],
      "total": 0,
      "data_ref": "data",
      "object": "list"
    }
  },
  "reward": {
    "customer": {
      "id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
      "name": "Bob Jones",
      "email": "bob.jones@email.com",
      "source_id": "36_bob",
      "metadata": {
        "age": 26,
        "favorite_brands": [
          "Nike",
          "Adidas",
          "Reebok"
        ],
        "accepts_marketing": false,
        "acquisition_channel": "Facebook"
      },
      "object": "customer"
    },
    "assignment_id": "rewa_YAIuU7AY6LNJVlUbRxSbNgiD",
    "id": "rew_INt3fGH3n7xIr3ZQcq4kkUZ1",
    "object": "reward",
    "name": "100 = $20",
    "created_at": "2022-11-10T06:28:39.582Z",
    "updated_at": null,
    "parameters": {
      "coin": {
        "exchange_ratio": 20,
        "points_ratio": 100
      }
    },
    "type": "COIN"
  },
  "loyalty_card": {
    "points": 100
  }
}

{
  "code": 400,
  "key": "missing_reward",
  "message": "Missing reward",
  "details": "A reward is required when redeeming a LOYALTY_CARD",
  "request_id": "v-0a885062c80375740f",
  "resource_id": "rf_0b3a1814550e5aaa34",
  "resource_type": "redemption",
  "error": {
    "message": "Missing reward = please add one."
  }
}

{
  "code": 404,
  "key": "not_found",
  "message": "Resource not found",
  "details": "Cannot find voucher with id :memberId",
  "request_id": "v-0c6b4b525d8e40cf3e",
  "resource_id": ":memberId",
  "resource_type": "voucher"
}

Redeem Reward

deprecated

Legacy loyalty API

This endpoint belongs to the legacy loyalty API (/v1/loyalties).

Voucherify will not develop new features for this API. However, critical issues may still receive fixes.

For new integrations, use Loyalty v2.

If you have questions, contact Voucherify support.

Alternative endpoint

This endpoint is an alternative to this endpoint. The URL was re-designed to allow you to redeem a reward without having to provide the campaignId as a path parameter.

POST

loyalties

members

{memberId}

redemption

Redeem Reward

curl --request POST \
  --url https://{cluster}.voucherify.io/v1/loyalties/members/{memberId}/redemption \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "reward": {
    "id": "rew_INt3fGH3n7xIr3ZQcq4kkUZ1",
    "points": 100
  },
  "order": {
    "items": [
      {
        "product_id": "prod_0c5d6689b39320059b",
        "quantity": "1"
      },
      {
        "product_id": "prod_0b2c36568000039138",
        "quantity": "2"
      }
    ]
  }
}
'

{
  "id": "r_0c6b4bf721439bf02b",
  "object": "redemption",
  "date": "2023-02-06T10:23:12.517Z",
  "customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
  "tracking_id": "track_9B0kB92+bJa8a+PegaWREw==",
  "metadata": null,
  "amount": 100,
  "result": "SUCCESS",
  "order": {
    "id": "ord_71Ayjxq2gFV80v3OP3qrxh37",
    "source_id": null,
    "created_at": "2023-02-06T10:23:12.485Z",
    "updated_at": null,
    "status": "PAID",
    "amount": 45000,
    "discount_amount": 2000,
    "total_discount_amount": 2000,
    "total_amount": 43000,
    "applied_discount_amount": 2000,
    "total_applied_discount_amount": 2000,
    "items": [
      {
        "object": "order_item",
        "product_id": "prod_0c5d6689b39320059b",
        "quantity": 1,
        "product": {
          "id": "prod_0c5d6689b39320059b",
          "source_id": "prod_anJ03RZZq74z4v",
          "name": "Apple iPhone 8"
        }
      },
      {
        "object": "order_item",
        "product_id": "prod_0b2c36568000039138",
        "quantity": 2,
        "amount": 45000,
        "price": 22500,
        "subtotal_amount": 45000,
        "product": {
          "id": "prod_0b2c36568000039138",
          "source_id": "86",
          "name": "[Sample] Able Brewing System",
          "price": 22500
        }
      }
    ],
    "metadata": {},
    "customer": {
      "id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
      "object": "customer"
    },
    "customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
    "referrer_id": null,
    "object": "order",
    "redemptions": {
      "r_0c6b4bf721439bf02b": {
        "date": "2023-02-06T10:23:12.517Z",
        "related_object_type": "voucher",
        "related_object_id": "v_u3dRiZ0XHqX5Euhy5ezB5UQ5Sf85VXFP",
        "related_object_parent_id": "camp_22noMlhTADb7Fq2UL3vWu3d1"
      }
    }
  },
  "customer": {
    "id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
    "name": "Bob Jones",
    "email": "bob.jones@email.com",
    "source_id": "36_bob",
    "metadata": {
      "age": 26,
      "favorite_brands": [
        "Nike",
        "Adidas",
        "Reebok"
      ],
      "accepts_marketing": false,
      "acquisition_channel": "Facebook"
    },
    "object": "customer"
  },
  "related_object_type": "voucher",
  "related_object_id": "v_u3dRiZ0XHqX5Euhy5ezB5UQ5Sf85VXFP",
  "voucher": {
    "id": "v_u3dRiZ0XHqX5Euhy5ezB5UQ5Sf85VXFP",
    "code": "AnsvocvP",
    "campaign": "Loyalty Campaign - Test Points",
    "campaign_id": "camp_22noMlhTADb7Fq2UL3vWu3d1",
    "category": null,
    "category_id": "cat_0bb81a481615a37b5e",
    "categories": [],
    "type": "LOYALTY_CARD",
    "discount": null,
    "gift": null,
    "loyalty_card": {
      "points": 9000,
      "balance": 5374
    },
    "start_date": null,
    "expiration_date": null,
    "validity_timeframe": null,
    "validity_day_of_week": null,
    "active": true,
    "additional_info": null,
    "metadata": {},
    "assets": {
      "qr": {
        "id": "U2FsdGVkX1/Au841M0T7UjYYRxYTzCRbNdZW6jW5YRNcV9PgblvN2MD5hdRuZfBRHEAm+d2pvzc2FOVHFkuh9BQoaIq4KVyvy0FvkWtKkMLe4zO+qL4ocNUIbaRMSLeY6Xiz4hjxKNq918oLyGrp9w==",
        "url": "{{internalVoucherifyURL}}"
      },
      "barcode": {
        "id": "U2FsdGVkX1+xG42zWo9nivfp6tg5jNuFCYOIFtw7iwas8kcA/8H4gu04dxO/hrbD41gFvxDhCuTSnIKwIPg9dEXzOvh8qy9VWN0UwDc6PL7lfNQuY+8Os7dqVsyNhoRned9pBo1uO6V4pjNu1gRTrw==",
        "url": "{{internalVoucherifyURL}}"
      }
    },
    "is_referral_code": false,
    "created_at": "2022-11-10T06:28:59.970Z",
    "updated_at": "2023-02-06T10:23:12.517Z",
    "holder_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
    "holder": {
      "id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
      "source_id": "36_bob",
      "metadata": {
        "age": 26,
        "favorite_brands": [
          "Nike",
          "Adidas",
          "Reebok"
        ],
        "accepts_marketing": false,
        "acquisition_channel": "Facebook"
      },
      "object": "customer"
    },
    "validation_rules_assignments": {
      "object": "list",
      "data_ref": "data",
      "data": [],
      "total": 0
    },
    "redemption": {
      "quantity": null,
      "redeemed_quantity": 16,
      "redeemed_points": 3626,
      "object": "list",
      "url": "/v1/vouchers/AnsvocvP/redemptions?page=1&limit=10"
    },
    "publish": {
      "object": "list",
      "count": 1,
      "url": "/v1/vouchers/AnsvocvP/publications?page=1&limit=10"
    },
    "object": "voucher",
    "applicable_to": {
      "data": [],
      "total": 0,
      "data_ref": "data",
      "object": "list"
    },
    "inapplicable_to": {
      "data": [],
      "total": 0,
      "data_ref": "data",
      "object": "list"
    }
  },
  "reward": {
    "customer": {
      "id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
      "name": "Bob Jones",
      "email": "bob.jones@email.com",
      "source_id": "36_bob",
      "metadata": {
        "age": 26,
        "favorite_brands": [
          "Nike",
          "Adidas",
          "Reebok"
        ],
        "accepts_marketing": false,
        "acquisition_channel": "Facebook"
      },
      "object": "customer"
    },
    "assignment_id": "rewa_YAIuU7AY6LNJVlUbRxSbNgiD",
    "id": "rew_INt3fGH3n7xIr3ZQcq4kkUZ1",
    "object": "reward",
    "name": "100 = $20",
    "created_at": "2022-11-10T06:28:39.582Z",
    "updated_at": null,
    "parameters": {
      "coin": {
        "exchange_ratio": 20,
        "points_ratio": 100
      }
    },
    "type": "COIN"
  },
  "loyalty_card": {
    "points": 100
  }
}

{
  "code": 400,
  "key": "missing_reward",
  "message": "Missing reward",
  "details": "A reward is required when redeeming a LOYALTY_CARD",
  "request_id": "v-0a885062c80375740f",
  "resource_id": "rf_0b3a1814550e5aaa34",
  "resource_type": "redemption",
  "error": {
    "message": "Missing reward = please add one."
  }
}

{
  "code": 404,
  "key": "not_found",
  "message": "Resource not found",
  "details": "Cannot find voucher with id :memberId",
  "request_id": "v-0c6b4b525d8e40cf3e",
  "resource_id": ":memberId",
  "resource_type": "voucher"
}

Authorizations

X-App-Id

string

header

required

X-App-Token

string

header

required

Scopes

api

Gives access to whole server-side API.

loyalties

Gives access to all endpoints and methods starting with /v1/loyalties.

Path Parameters

memberId

string

required

Unique loyalty card assigned to a particular customer.

Example:

"MmFAzfDe"

Body

application/json

Specify the reward to be redeemed. In case of a pay with points reward, specify the order and the number of points to be applied to the order. Please note that if you do not specify the amount of points, the application will default to applying the number of points to pay for the remainder of the order. If the limit of available points on the card is reached, then only the available points on the card will be applied to the order.

Request body schema for POST v1/loyalties/{campaignId}/members/{memberId}/redemption and for POST v1/loyalties/members/{memberId}/redemption.

reward

object

Contains information about the reward that the customer wants to redeem and the number of points the customer is choosing to use for the reward if the reward is a pay with points reward.

Show child attributes

order

Order · object

Order object that is required when redeeming a pay with points reward.

Show child attributes

metadata

object

A set of key/value pairs that you can send in the request body to check against vouchers requiring redemption metadata validation rules to be satisfied. The validation runs against rules that are defined through the Create Validation Rules endpoint or with the Validation Rule Builder in the the Dashboard.

Response

Returns a redemption object.

Response body schema for POST v1/loyalties/{campaignId}/members/{memberId}/redemption and for POST v1/loyalties/members/{memberId}/redemption.

string

required

Unique redemption ID.

Example:

"r_0bc92f81a6801f9bca"

object

enum<string>

default:redemption

required

The type of the object represented by the JSON

Available options:

redemption

date

string<date-time>

required

Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format.

Example:

"2021-12-22T10:13:06.487Z"

customer_id

string | null

required

Unique customer ID of the redeeming customer.

Example:

"cust_i8t5Tt6eiKG5K79KQlJ0Vs64"

tracking_id

string | null

required

Hashed customer source ID.

metadata

object | null

required

The metadata object stores all custom attributes assigned to the redemption.

redemption

null | string

required

Unique redemption ID of the parent redemption.

Example:

"r_0c656311b5878a2031"

result

enum<string>

required

Redemption result.

Available options:

SUCCESS,

FAILURE

status

enum<string>

required

Redemption status.

Available options:

SUCCEEDED,

FAILED,

ROLLED_BACK

order

Order Calculated No Customer Data · object | null

required

Order information.

Show child attributes

channel

object

required

Defines the details of the channel through which the redemption was issued.

Show child attributes

customer

Simple Customer · object | null

required

Simplified customer data.

Show child attributes

Defines the related object.

Available options:

voucher,

promotion_tier,

redemption

Unique related object ID assigned by Voucherify, i.e. v_lfZi4rcEGe0sN9gmnj40bzwK2FH6QUno for a voucher.

reward

Redemption Reward Result · object

required

Show child attributes

amount

integer

For gift cards, this is a positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the number of redeemed credits. For loyalty cards, this is the number of loyalty points used in the transaction.

Example:

10000

session

object

Contains details about the redemption session lock. Sessions can be established only for discount vouchers, promotions, and gift cards.

Show child attributes

failure_code

string

If the result is FAILURE, this parameter will provide a generic reason as to why the redemption failed.

Example:

"customer_rules_violated"

failure_message

string

If the result is FAILURE, this parameter will provide a more expanded reason as to why the redemption failed.

promotion_tier

Promotion Tier · object

Contains details of the promotion tier and the parent campaign.

Show child attributes

gift

object

Contains the amount subtracted from the gift card for the redemption.

Show child attributes

loyalty_card

object

Contains the number of points subtracted from the loyalty card for the redemption.

Show child attributes

voucher

Voucher Holder · object

Defines the details of the voucher being redeemed.

Show child attributes

Introduction

Endpoints

Events

Redeem Reward

Authorizations

Scopes

Path Parameters

Body

Response