Codes

These endpoints are specifically built for handling voucher codes and common actions against them such as redeeming or topups.

All voucher codes have 3 key attributes: Status, expiry date and balance. You can view the list of status values you may encounter here.

Endpoints

Avoid costly redemption logic

If the lookup is happening at a fixed location such as a point-of-sale terminal then we recommend passing the locationID with the lookup to ensure the code both exists and can be redeemed at the location based on it's current settings.

If it can't then an error is returned with code location_not_allowed

Lookup voucher

GET https://api.giftpro.co.uk/codes/{code}/

The code must already have been sold or activated as part of an existing order before it will be returned.

If the lookup is happening at a fixed location such as a point-of-sale terminal then we recommend passing the locationID with the lookup to ensure the code both exists and can be redeemed at the location based on it's current settings.

Query Parameters

Name	Type	Description
locationID	String	If the code isn't redeemable at the locationID provided an error is returned and feedback can be offered to the end user.

200: OK The voucher is returned

{
  "rowID": 987654,
  "orderID": 1234567,
  "productID": 701,
  "departmentID": 646
  "externalReference": "Lorum ipsum..."
  "expiryDate": "2024-09-12 11:32:41",
  "validFromDate": "2022-08-13 11:32:41",
  "balances": {
    "starting": {
      "GBP": {
        "amount": 60,
        "exchangeRate": 1
      },
      
    },
    "current": {
      "GBP": 60,
      
    }
  },
  "name": "Monetary Voucher",
  : "Lorem ipsum dolor sit amet...",
  "termsAndConditions": "Lorem ipsum dolor sit amet...",
  "redeemInstructions": "Lorem ipsum dolor sit amet...",
  "redeemCode": "1245441ASDBQ",
  
  
  "status": "Valid",
  "currencyCode": "GBP",
  "partiallyRedeemable": false,
  "redeemableDomains": {
    : {
      "locations": [
        {
          "locationID": "71",
          "name": "Lymington Hotel Montagne"
        },
        {
          "locationID": "102",
          "name": "Ampress Park Hotel"
        },
        
       ]
     },
     
  },
  "redeemHistory": [
    {
      "eventID": 4759602,
      "userID": null,
      "created": "2022-08-13 11:32:41",
      "rowID": 2939141,
      "locationID": null,
      "location": null,
      "type": "Activation",
      "amount": 100,
      "currencyCode": "GBP",
      "startingBalance": 100
      "balance": 100,
      "currencies": {
        "GBP": {
          "baseCurrencyCode": "GBP",
          "exchangeRate": "1.00",
          "redeemedCurrencyCode": "GBP",
          "amount": 100.00,
          "balance": 100
        }
      },
      "links": {
        "self": "/balance_events/4759602/"
      },
      "row": {
        "code": "1245441ASDBQ",
        "type": "Voucher",
        "links": {
          "self": "/codes/1245441ASDBQ/"
        }
      },
      "order": {
        "orderID": 1234567,
        "links": {
          "self": "/orders/1234567/"
        }
      }
    }
  },            
  
}

404: Not Found

{
    "result": {
        "type": "error",
        "reason": "no_matching_code"
    }
}

Error codes

Code	Explanation
no_matching_code	The specified code does not exist.
code_not_activated	The specified code exists but has not been activated.

401: Unauthorized

Topup voucher

POST https://api.giftpro.co.uk/codes/{code}/topup/

Add value to a voucher code. If the voucher hasn't been seen before the first topup will return a balance event "Activation".

A successful topup will return a balance event, which also contains a row representing the voucher and the order the row is in.

Request Body

Name	Type	Description
amount*	String
locationID*	int

200: OK

400: Bad Request

401: Unauthorized

404: Not Found

403: Forbidden

{
    "result": {
        "type": "error",
        "reason": "topup_not_allowed"
    }
}

Error codes

Code	Explaination
topup_not_allowed
topup_amount_too_small
topup_amount_too_big

Redeem voucher

POST https://api.giftpro.co.uk/codes/{code}/redeem/

This endpoint accepts two parameters that should be used when redeeming a voucher, which parameter you use depends on if you want to redeem the entire amount or not.

The response is a balance event specific to this redemption which you may need if you want to later reverse.

Request Body

Name	Type	Description
locationID*	int
amount	String	If an amount is not provided, the default is to use all remaining balance.

200: OK

{
  "eventID": 453562,
  "domainID": 479,
  "locationID": 1204,
  "amount": 50,
  "startingBalance": 100.00,
  "balance": 0.00,
  "type": "Redeemed",
  "confirmed": true,
  "created": "2019-12-07 22:19:02",
  "row": {
    "code": "1234EXAMPLECODE",
    "type": "Voucher",
    "links": {
      "self": "/codes/1234EXAMPLECODE/"
    }
  },
  "order": {
      "orderID": 623578,
      "links": {
          "self": "/orders/623578/"
      }
  }
}

400: Bad Request

403: Forbidden

404: Not Found

{
    "result": {
        "type": "error",
        "reason": "no_matching_code"
    }
}

401: Unauthorized