Two-step voucher redemption

A two-step voucher redemption process is our suggested way to integrate Vouchery API into your shopping funnel. The first step of the voucher redemption means verification of the voucher code (and the reward), and the transaction. This should be done before the customer starts the payment process. For example, in e-commerce context, voucher validation should be performed when customer enters the checkout process and enters the Voucher Code. Once the payment is complete, the voucher redemption should be confirmed so it is counted against campaign limitations, etc.

When the transaction information change during the redemption process, it is best to delete the initial voucher redemption and then create another one with updated information about the transaction (changing the transaction ID). This may be the case when the voucher code is added to the cart, validated, and then more items are added to the cart before the final checkout. An existing redemption can't be updated because this may cause it to become invalid (e.g. if minimum transaction value is not met anymore).

Step 1: Validate a voucher

Here's how a simple voucher validation looks like:

curl --request POST \
  --url https://preview.vouchery.io/api/v2.0/vouchers/VOU-S4H9LX/redemptions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {paste here API key}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "transaction_id": "TRAN-35f36ebb-f677-4ba0-8ea7-8ae589f51ddc",
  "total_transaction_cost": 299,
  "confirmed": false
}
'

Check an example of an extensive voucher validation, which includes all the products in the basket and the Customer ID:

curl --request POST \
  --url https://preview.vouchery.io/api/v2.0/vouchers/VOU-S4H9LX/redemptions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {paste here API key}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "product_items": [
    {
      "categories": [
        "Summer"
      ],
      "name": "T-Shirt",
      "sku": "12345",
      "quantity": 1,
      "price": 99,
      "product_identifier": "XOT"
    },
    {
      "categories": [
        "Spring"
      ],
      "name": "Trousers",
      "sku": "56789",
      "product_identifier": "FIR",
      "quantity": 1,
      "price": 200
    }
  ],
  "transaction_id": "TRAN-35f36ebb-f677-4ba0-8ea7-8ae589f51ddc",
  "customer_identifier": "JoeCustomer",
  "total_transaction_cost": 299,
  "confirmed": false
}
'

–

Here's a JSON example of another voucher validation:

{
  "type": "Redemption",
  "id": 4,
  "total_transaction_cost": 100.00,
  "granted_discount": 7.50,
  "transaction_id": "TRAN-01b7df8b-ae82-4ad2-899e-feddf538eb7e",
  "validated_at": "2018-10-14T20:32:58.339Z",
  "confirmed_at": null,
  "voucher": {
    "type": "Voucher",
    "id": 199,
    "campaign_id": 9,
    "code": "VOU-S4H9LX",
    "campaign": {
      "type": "Campaign",
      "id": 9,
      "name": "Fall Haul"
    }
  }
}

Step 2: Confirm a redemption

curl --request PATCH \
     --url "https://preview.vouchery.io/api/v2.0/vouchers/VOU-S4H9LX/redemptions" \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {paste here API key}" \
     --data \
     
'{
"transaction_id":"TRAN-01b7df8b-ae82-4ad2-899e-feddf538eb7e"
"total_transaction_cost":0
"user_agent":"string"
"confirmed":true
}

–

{
  "type": "Redemption",
  "id": 4,
  "total_transaction_cost": 100.00,
  "granted_discount": 7.50,
  "transaction_id": "TRAN-01b7df8b-ae82-4ad2-899e-feddf538eb7e",
  "validated_at": "2018-10-14T20:32:58.339Z",
  "confirmed_at": "2018-10-14T20:35:23.430Z",
}