Validate Voucher

To verify a voucher code given by customer, you can use this method. It is designed for server side integration which means that is accessible only through private keys.

Response schema

{
    "valid": true, // result of the validation, returns true if the code can be applied and false if the code is not valid in a given context
    "applicable_to": { // if a discount is product-specific, returns items and collections from the given order that qualify for a discount
        "data": [
            {
                "object": "products_collection",
                "id": "pc_jTTFY7id2QNiJJR38Pf9LLWv",
                "source_id": null,
                "strict": false
            },
            {
                "object": "product",
                "id": "prod_09929913898fa69e80",
                "source_id": "prod_anJ03RZZq74z4v",
                "strict": true
            },
            {
                "object": "sku",
                "id": "sku_0KtP4rvwEECQ2U",
                "source_id": "apple534-ihd5",
                "strict": true
            }
        ],
        "total": 3,
        "data_ref": "data",
        "object": "list"
    },
    "inapplicable_to": { // lists excluded collections and items
        "data": [],
        "total": 0,
        "data_ref": "data",
        "object": "list"
    },
    "tracking_id": "track_VAVW6qltuo1/z+G2GI2LPw==",
    "order": {
        "amount": 200000,// total order amount before applying any discount
        "items_discount_amount": 20000,// sums up all product-specific discounts applied to this order id, if there is an order-level discount, API returns discount_amount that sums up all order-level discounts applied to a patricular order
        "total_discount_amount": 20000,// sums up all order-level and all product-specific discounts applied to this order id
        "total_amount": 180000,// order amount after applying all the discounts
        "items_applied_discount_amount": 20000,// sums up all product-specific discounts applied in a particular request
        "total_applied_discount_amount": 20000,// sums up all order-level and all product-specific discounts applied in a particular request
        "items": [
            {
                "object": "order_item",
                "source_id": "apple534",
                "related_object": "product",
                "product_id": "prod_anJ03RZZq74z4v",
                "quantity": 2,
                "amount": 100000, // "amount"= "quantity" * "price"
                "discount_amount": 10000,// sum of all discounts applied to this line item
                "applied_discount_amount": 10000,// sum of discounts applied to this line item in a particular request
                "price": 50000,
                "product": {
                    "id": "prod_09929913898fa69e80",
                    "source_id": "prod_anJ03RZZq74z4v",
                    "name": "Apple iPhone 8",
                    "metadata": {
                        "shop": "citycenter",
                        "category": "electronics"
                    },
                    "override": true
                },
                "metadata": {
                    "series": "2022-783CV"
                }
            },
            {
                "object": "order_item",
                "source_id": "apple534-ihd5",
                "related_object": "sku",
                "sku_id": "sku_0KtP4rvwEECQ2U",
                "quantity": 1,
                "amount": 100000,// "amount"= "quantity" * "price"
                "discount_amount": 10000,// sum of all discounts applied to this line item
                "applied_discount_amount": 10000,// sum of discounts applied to this line item in a particular request
                "price": 100000,
                "sku": {
                    "sku": "Apple iPad 10 Silver 64GB",
                    "metadata": {
                        "category": "electronics"
                    },
                    "override": true
                }
            }
        ],
        "customer_id": null,
        "referrer_id": null,
        "object": "order"
    },
    "code": "Electronics10OFF",
    "discount": { // discount details presenting how the discount is applied to the order
        "type": "PERCENT",
        "effect": "APPLY_TO_ITEMS", // discount effect, the discount is applied to specific items
        "percent_off": 10 // discount value
    },
    "start_date": "2021-07-20T00:00:00.000Z",
    "expiration_date": "2023-07-01T00:00:00.000Z",
    "metadata": {}
}

Gift Vouchers - validate Gift Card and control amount to redeem

Voucherify also gives the possibility to create a gift card, which allows using credits to fulfill the order. A user can specify how many credits he wants to use from the gift card. The available balance of credits is counted based on policy rules attached to the Gift Voucher definition.

curl -i -X POST \
   -H "Content-Type:application/json" \
   -H "X-App-Id:c70a6f00-cf91-4756-9df5-47628850002b" \
   -H "X-App-Token:3266b9f8-e246-4f79-bdf0-833929b1380c" \
   -d \
'{
    "order": {
        "amount": 2500
    },
    "gift": {
        "credits": 1500
    }
}' \
 'https://api.voucherify.io/v1/vouchers/aDm4CRR3/validate'
{
  "code": "91Ft4U",
  "valid": true,
  "gift": {
    "amount": 10000,
  },
  "tracking_id": "track_uP6K80aZLxpKYZWvVIVW4A=="
}

Returns

This operation returns information about the validity of the code. Moreover, it returns hashed source identifier which can be used as tracking id in future calls.

If a validation session is established then the session details will be returned as well. Read more about sessions: Validation Session

Voucher validation might fail because of one of these reasons:

  • voucher not found - voucher doesn't exist or was deleted
  • voucher expired - voucher is out of [start date - expiration date] time frame
  • voucher is disabled - learn more disable voucher
  • customer does not match segment rules - learn more customer tracking
  • order does not match validation rules - learn more about validation rules
{
  "code": "fUtuR3",
  "valid": false,
  "reason": "voucher not active yet",
  "tracking_id": "track_uP6K80aZLxpKYZWvVIVW4A==",
  "error": {
    "code": 400,
    "key": "voucher_not_active",
    "message": "voucher not active yet",
    "details": "fUtuR3",
    "request_id": "v-0942d7e51611c40a21"
  }
}
{
  "code": "m4DeUp",
  "valid": false,
  "reason": "voucher not found",
  "tracking_id": "track_uP6K80aZLxpKYZWvVIVW4A==",
  "error": {
    "code": 404,
    "key": "not_found",
    "message": "Resource not found",
    "details": "Cannot find voucher with id m4DeUp",
    "request_id": "v-0942d6599f94cbdf30",
    "resource_id": "m4DeUp",
    "resource_type": "voucher"
  }
}
{
  "code": "3xP1reD",
  "valid": false,
  "reason": "voucher expired",
  "tracking_id": "track_uP6K80aZLxpKYZWvVIVW4A==",
  "error": {
    "code": 400,
    "key": "voucher_expired",
    "message": "voucher expired",
    "details": "3xP1reD",
    "request_id": "v-2442dse51611c40a21"
  }
}
{
  "code": "d154bLeD",
  "valid": false,
  "reason": "voucher is disabled",
  "tracking_id": "track_uP6K80aZLxpKYZWvVIVW4A==",
  "error": {
    "code": 400,
    "key": "voucher_disabled",
    "message": "voucher is disabled",
    "details": "fUtuR3",
    "request_id": "v-0942d7849998577e98"
  }
}
{
  "code": "91Ft4U",
  "valid": false,
  "reason": "gift amount exceeded",
  "tracking_id": "track_uP6K80aZLxpKYZWvVIVW4A=="
}
{
   "code": "aDm4CRR3",
   "valid": true,
   "session": {
        "key": "ssn_1JGAB8ts1Uqrmdx2wcxFMDXKuU6Cy3gh",
        "type": "LOCK",
        "ttl": 7,
        "ttl_unit": "DAYS"
    }
}
Language
Response
Click Try It! to start a request and see the response here!