Giftpro API
  • Getting started
  • Common uses
    • Redeem at point-of-sale
    • Retrieving customer data
  • Filtering
  • Pagination
  • Errors
  • Reference
    • Properties
      • Delivery methods
    • Locations
    • Categories
    • Orders
      • Statuses
      • Address properties
    • Codes
      • Statuses
    • Balance events
      • Types of event
    • Vouchers
Powered by GitBook
On this page
  • Endpoints
  • Lookup voucher
  • Topup voucher
  • Redeem voucher
  1. Reference

Codes

PreviousAddress propertiesNextStatuses

Last updated 5 months ago

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

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 with code location_not_allowed

Lookup voucher

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

The code must already have been sold or 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.

{
  "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/"
        }
      }
    }
  },            
  
}
{
    "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.

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".

Request Body

Name
Type
Description

amount*

String

locationID*

int

{
    "result": {
        "type": "error",
        "reason": "topup_not_allowed"
    }
}
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.

Request Body

Name
Type
Description

locationID*

int

amount

String

If an amount is not provided, the default is to use all remaining balance.

{
  "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/"
      }
  }
}

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

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

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

here.
error is returned
activated
balance event
balance event
reverse