Rollback Redemption

curl --request POST \
  --url https://{cluster}.voucherify.io/v1/redemptions/{redemptionId}/rollback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '{
  "customer": {
    "id": "cust_SolpIN5N4oZbCnrxZ5NHrbVB",
    "name": "Annie Lemons",
    "email": "annie@lemon.com",
    "phone": "+1 933 222 3334",
    "birthday": "1900-12-02",
    "birthdate": "1900-12-01",
    "address": {
      "city": "New York",
      "state": "NY",
      "line_1": "123 Main St.",
      "line_2": "APT 3 BLG 5",
      "country": "United States",
      "postal_code": "100012"
    },
    "metadata": {
      "age": 23
    }
  },
  "order": {
    "source_id": "test_rollback_8"
  },
  "metadata": {
    "location_id": [
      "L2"
    ]
  }
}'

{
  "id": "rr_0c5eba630bc4979e70",
  "object": "redemption_rollback",
  "date": "2023-01-27T16:05:23.631Z",
  "customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
  "tracking_id": "track_9B0kB92+bJa8a+PegaWREw==",
  "metadata": null,
  "amount": -2,
  "redemption": "r_0c5bf3323008a35032",
  "reason": "A UI rollback to check for result in API response to listing.",
  "result": "SUCCESS",
  "order": {
    "id": "ord_dqxr4uzaYWkTZnrSEMoQtCF8",
    "source_id": null,
    "created_at": "2023-01-25T12:18:09.203Z",
    "updated_at": "2023-01-27T16:05:23.687Z",
    "status": "CANCELED",
    "amount": 2100,
    "total_amount": 2100,
    "items": [
      {
        "object": "order_item",
        "product_id": "prod_0bc3bd8a4e072c5275",
        "quantity": 3,
        "amount": 2100,
        "price": 700,
        "subtotal_amount": 2100,
        "product": {
          "name": "Bouquet - Romantic Roses",
          "price": 700
        }
      }
    ],
    "metadata": {},
    "customer": {
      "id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
      "object": "customer"
    },
    "customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
    "referrer_id": null,
    "object": "order",
    "redemptions": {
      "r_0c5bf3323008a35032": {
        "date": "2023-01-25T12:18:09.216Z",
        "rollback_id": "rr_0c5eba630bc4979e70",
        "rollback_date": "2023-01-27T16:05:23.631Z",
        "related_object_type": "voucher",
        "related_object_id": "v_u3dRiZ0XHqX5Euhy5ezB5UQ5Sf85VXFP",
        "related_object_parent_id": "camp_22noMlhTADb7Fq2UL3vWu3d1"
      }
    }
  },
  "channel": {
    "channel_id": "user_g24UoRO3Caxu7FCT4n5tpYEa3zUG0FrH",
    "channel_type": "USER"
  },
  "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,
    "categories": [],
    "discount": null,
    "gift": null,
    "loyalty_card": null,
    "start_date": null,
    "expiration_date": null,
    "validity_timeframe": null,
    "validity_day_of_week": null,
    "additional_info": null,
    "assets": {
      "qr": {},
      "barcode": {}
    },
    "updated_at": null,
    "object": "voucher"
  },
  "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_0ZwLAHgeU9IrI2V1ofYRmW7g",
    "voucher": {
      "id": "v_4GaEX7clyqMaveT7vHhoyRpsIgxv95Q6",
      "code": "HAPPY-ORDER5My",
      "campaign": "$20 off the entire order",
      "campaign_id": "camp_5h0wc453_4",
      "category": null,
      "category_id": "cat_0b688929a2476386a6",
      "categories": [],
      "type": "DISCOUNT_VOUCHER",
      "discount": {
        "type": "AMOUNT",
        "amount_off": 2000,
        "effect": "APPLY_TO_ORDER"
      },
      "gift": null,
      "loyalty_card": null,
      "start_date": "2022-09-20T00:00:00.000Z",
      "expiration_date": "2022-09-30T00:00:00.000Z",
      "validity_timeframe": null,
      "validity_day_of_week": null,
      "active": true,
      "additional_info": null,
      "metadata": {},
      "assets": {
        "qr": {
          "id": "21ceb848-4869-4dac-ba41-f854bda3a101",
          "url": "{{internalVoucherifyURL}}"
        },
        "barcode": {
          "id": "1dba9cb2-fb28-4c8d-8548-5edb2eb01f5a",
          "url": "{{internalVoucherifyURL}}"
        }
      },
      "is_referral_code": false,
      "created_at": "2023-01-25T12:18:09.256Z",
      "updated_at": null,
      "holder_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
      "redemption": {
        "quantity": null,
        "redeemed_quantity": 0,
        "object": "list",
        "url": "/v1/vouchers/HAPPY-ORDER5My/redemptions?page=1&limit=10"
      },
      "publish": {
        "object": "list",
        "count": 1,
        "url": "/v1/vouchers/HAPPY-ORDER5My/publications?page=1&limit=10"
      },
      "object": "voucher"
    },
    "id": "rew_MF4hKh1IKYgJkPjbcFbH94Ho",
    "object": "reward",
    "name": "Digital Present",
    "created_at": "2023-01-25T12:16:44.557Z",
    "updated_at": null,
    "parameters": {
      "campaign": {
        "id": "camp_5h0wc453_4",
        "type": "DISCOUNT_COUPONS"
      }
    },
    "type": "CAMPAIGN"
  },
  "loyalty_card": {
    "points": -2
  }
}

Redemptions

Rollback Redemption

Your business logic may include a case when you need to undo a redemption. You can revert a redemption by calling this API endpoint. This endpoint rolls back only single redemptions, meaning those that are not stacked. Stacked redemptions belong to a parent redemption. To roll back a parent redemption, including all of its individual redemptions, use the POST Rollback Stackable Redemptions

🚧 You can roll back a redemption up to 3 months back.

Effect

The operation

creates a rollback entry in voucher’s redemption history (redemption.redemption_entries) and
gives 1 redemption back to the pool (decreases redeemed_quantity by 1).

Returned funds

In case of gift card vouchers, this method returns funds back according to the source redemption. In case of loyalty card vouchers, this method returns points back according to the source redemption.

POST

redemptions

{redemptionId}

rollback

Rollback Redemption

curl --request POST \
  --url https://{cluster}.voucherify.io/v1/redemptions/{redemptionId}/rollback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '{
  "customer": {
    "id": "cust_SolpIN5N4oZbCnrxZ5NHrbVB",
    "name": "Annie Lemons",
    "email": "annie@lemon.com",
    "phone": "+1 933 222 3334",
    "birthday": "1900-12-02",
    "birthdate": "1900-12-01",
    "address": {
      "city": "New York",
      "state": "NY",
      "line_1": "123 Main St.",
      "line_2": "APT 3 BLG 5",
      "country": "United States",
      "postal_code": "100012"
    },
    "metadata": {
      "age": 23
    }
  },
  "order": {
    "source_id": "test_rollback_8"
  },
  "metadata": {
    "location_id": [
      "L2"
    ]
  }
}'

{
  "id": "rr_0c5eba630bc4979e70",
  "object": "redemption_rollback",
  "date": "2023-01-27T16:05:23.631Z",
  "customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
  "tracking_id": "track_9B0kB92+bJa8a+PegaWREw==",
  "metadata": null,
  "amount": -2,
  "redemption": "r_0c5bf3323008a35032",
  "reason": "A UI rollback to check for result in API response to listing.",
  "result": "SUCCESS",
  "order": {
    "id": "ord_dqxr4uzaYWkTZnrSEMoQtCF8",
    "source_id": null,
    "created_at": "2023-01-25T12:18:09.203Z",
    "updated_at": "2023-01-27T16:05:23.687Z",
    "status": "CANCELED",
    "amount": 2100,
    "total_amount": 2100,
    "items": [
      {
        "object": "order_item",
        "product_id": "prod_0bc3bd8a4e072c5275",
        "quantity": 3,
        "amount": 2100,
        "price": 700,
        "subtotal_amount": 2100,
        "product": {
          "name": "Bouquet - Romantic Roses",
          "price": 700
        }
      }
    ],
    "metadata": {},
    "customer": {
      "id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
      "object": "customer"
    },
    "customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
    "referrer_id": null,
    "object": "order",
    "redemptions": {
      "r_0c5bf3323008a35032": {
        "date": "2023-01-25T12:18:09.216Z",
        "rollback_id": "rr_0c5eba630bc4979e70",
        "rollback_date": "2023-01-27T16:05:23.631Z",
        "related_object_type": "voucher",
        "related_object_id": "v_u3dRiZ0XHqX5Euhy5ezB5UQ5Sf85VXFP",
        "related_object_parent_id": "camp_22noMlhTADb7Fq2UL3vWu3d1"
      }
    }
  },
  "channel": {
    "channel_id": "user_g24UoRO3Caxu7FCT4n5tpYEa3zUG0FrH",
    "channel_type": "USER"
  },
  "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,
    "categories": [],
    "discount": null,
    "gift": null,
    "loyalty_card": null,
    "start_date": null,
    "expiration_date": null,
    "validity_timeframe": null,
    "validity_day_of_week": null,
    "additional_info": null,
    "assets": {
      "qr": {},
      "barcode": {}
    },
    "updated_at": null,
    "object": "voucher"
  },
  "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_0ZwLAHgeU9IrI2V1ofYRmW7g",
    "voucher": {
      "id": "v_4GaEX7clyqMaveT7vHhoyRpsIgxv95Q6",
      "code": "HAPPY-ORDER5My",
      "campaign": "$20 off the entire order",
      "campaign_id": "camp_5h0wc453_4",
      "category": null,
      "category_id": "cat_0b688929a2476386a6",
      "categories": [],
      "type": "DISCOUNT_VOUCHER",
      "discount": {
        "type": "AMOUNT",
        "amount_off": 2000,
        "effect": "APPLY_TO_ORDER"
      },
      "gift": null,
      "loyalty_card": null,
      "start_date": "2022-09-20T00:00:00.000Z",
      "expiration_date": "2022-09-30T00:00:00.000Z",
      "validity_timeframe": null,
      "validity_day_of_week": null,
      "active": true,
      "additional_info": null,
      "metadata": {},
      "assets": {
        "qr": {
          "id": "21ceb848-4869-4dac-ba41-f854bda3a101",
          "url": "{{internalVoucherifyURL}}"
        },
        "barcode": {
          "id": "1dba9cb2-fb28-4c8d-8548-5edb2eb01f5a",
          "url": "{{internalVoucherifyURL}}"
        }
      },
      "is_referral_code": false,
      "created_at": "2023-01-25T12:18:09.256Z",
      "updated_at": null,
      "holder_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
      "redemption": {
        "quantity": null,
        "redeemed_quantity": 0,
        "object": "list",
        "url": "/v1/vouchers/HAPPY-ORDER5My/redemptions?page=1&limit=10"
      },
      "publish": {
        "object": "list",
        "count": 1,
        "url": "/v1/vouchers/HAPPY-ORDER5My/publications?page=1&limit=10"
      },
      "object": "voucher"
    },
    "id": "rew_MF4hKh1IKYgJkPjbcFbH94Ho",
    "object": "reward",
    "name": "Digital Present",
    "created_at": "2023-01-25T12:16:44.557Z",
    "updated_at": null,
    "parameters": {
      "campaign": {
        "id": "camp_5h0wc453_4",
        "type": "DISCOUNT_COUPONS"
      }
    },
    "type": "CAMPAIGN"
  },
  "loyalty_card": {
    "points": -2
  }
}

Authorizations

X-App-Id

string

header

required

X-App-Token

string

header

required

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

redemptionId

string

required

The original redemption ID to be rolled back (undone).

Example:

"r_0ba186c4824e4881e1"

Query Parameters

reason

string

Reason for the rollback.

tracking_id

string

Customer's source_id.

Body

application/json

Add information about the original customer and order. Customer data and Redemption metadata can be updated in Voucherify when passing the customer data in the request body.

Request body schema for POST v1/redemptions/{redemptionId}/rollback.

reason

string

Reason for the rollback.

tracking_id

string

Customer's source_id.

customer

object

Show child attributes

order

object

Order information.

Show child attributes

metadata

object

A set of key/value pairs that you can send in the request body to update redemption metadata.

Response

Returns a redemption rollback object indicating the result of the rollback.

Response body schema for POST v1/redemptions/{redemptionId}/rollback. This is an object representing a redemption rollback.

string

required

Unique identifier of the redemption rollback.

Example:

"rr_0efeb3dab05e62e599"

object

enum<string>

default:redemption_rollback

required

The type of the object represented by the JSON

Available options:

redemption_rollback

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

string | null

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

order

object

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

object

required

Simplified customer data.

Show child attributes

Defines the related object.

Available options:

voucher,

promotion_tier,

redemption

Unique identifier of the related object. It is assigned by Voucherify, i.e. v_lfZi4rcEGe0sN9gmnj40bzwK2FH6QUno for a voucher.

amount

integer

For gift cards, this represents the number of the credits restored to the card in the rolledback redemption. The number is a negative integer in the smallest currency unit, e.g. -100 cents for $1.00 added back to the card. For loyalty cards, this represents the number of loyalty points restored to the card in the rolledback redemption. The number is a negative integer.

Example:

-10000

reason

string

System generated cause for the redemption being invalid in the context of the provided parameters.

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.

voucher

object

Defines the details of the voucher being originally redeemed. This is an object representing a voucher with categories and validation rules assignments. This is an object representing a voucher.

Show child attributes

promotion_tier

object

Contains details of the promotion tier and the parent campaign. This is an object representing a promotion tier. Promotion tiers are always assigned to a campaign and cannot be used standalone.

Show child attributes

reward

object

Show child attributes

gift

object

Contains the amount returned to the gift card in the redemption rollback. It is expressed as a negative integer.

Show child attributes

loyalty_card

object

Contains the number of points returned to the loyalty card in the reward redemption rollback. It is expressed as a negative integer.

Show child attributes

Redeem Voucher [Deprecated]Redeem Promotion [Deprecated]

⌘I

Introduction

Object schemas

Endpoints

Events

Rollback Redemption

Effect

Returned funds

Authorizations

Path Parameters

Query Parameters

Body

Response