# 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.](https://docs.giftpro.co.uk/reference/codes/statuses) ## Endpoints {% hint style="info" %} **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](https://docs.giftpro.co.uk/errors) with code `location_not_allowed` {% endhint %} ## Lookup voucher `GET` `https://api.giftpro.co.uk/codes/{code}/` The code must already have been sold or [activated](https://docs.giftpro.co.uk/#activate-code) 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. | {% tabs %} {% tab title="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",
  "description": "Lorem ipsum dolor sit amet...",
  "termsAndConditions": "Lorem ipsum dolor sit amet...",
  "redeemInstructions": "Lorem ipsum dolor sit amet...",
  "redeemCode": "1245441ASDBQ",
  "subtotal": 100.00,
  "total": 100.00,
  "status": "Valid",
  "currencyCode": "GBP",
  "partiallyRedeemable": false,
  "redeemableDomains": {
    "479": {
      "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/"
        }
      }
    }
  },            
  {...}
}
{% endtab %} {% tab title="404: Not Found " %} {% code lineNumbers="true" fullWidth="false" %} ```json { "result": { "type": "error", "reason": "no_matching_code" } } ``` {% endcode %} #### Error codes
CodeExplanation
no_matching_codeThe specified code does not exist.
code_not_activatedThe specified code exists but has not been activated.
{% endtab %} {% tab title="401: Unauthorized " %} {% endtab %} {% endtabs %} ## 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](https://docs.giftpro.co.uk/reference/balance-events), which also contains a row representing the voucher and the order the row is in. #### Request Body | Name | Type | Description | | -------------------------------------------- | ------ | ----------- | | amount\* | String | | | locationID\* | int | | {% tabs %} {% tab title="200: OK " %} {% endtab %} {% tab title="400: Bad Request " %} {% endtab %} {% tab title="401: Unauthorized " %} {% endtab %} {% tab title="404: Not Found " %} {% endtab %} {% tab title="403: Forbidden " %} ```json { "result": { "type": "error", "reason": "topup_not_allowed" } } ``` {% tabs %} {% tab title="Error codes" %} | Code | Explaination | | ------------------------- | ------------ | | topup\_not\_allowed | | | topup\_amount\_too\_small | | | topup\_amount\_too\_big | | | {% endtab %} | | | {% endtabs %} | | | {% endtab %} | | | {% endtabs %} | | ## 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](https://docs.giftpro.co.uk/#the-balance-event-object) specific to this redemption which you may need if you want to later [reverse](https://docs.giftpro.co.uk/#reverse). #### Request Body | Name | Type | Description | | -------------------------------------------- | ------ | -------------------------------------------------------------------------- | | locationID\* | int | | | amount | String | If an amount is not provided, the default is to use all remaining balance. | {% tabs %} {% tab title="200: OK " %} ```json { "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/" } } } ``` {% endtab %} {% tab title="400: Bad Request " %} {% endtab %} {% tab title="403: Forbidden " %} {% endtab %} {% tab title="404: Not Found " %} ```json { "result": { "type": "error", "reason": "no_matching_code" } } ``` {% endtab %} {% tab title="401: Unauthorized " %} {% endtab %} {% endtabs %} [^1]: This array will contain all the acceptable currency codes and the agreed exchange rates for them. [^2]: The current balance amount in each available currency is shown. [^3]: For "experience" based vouchers these often contain important context as to what the voucher entitles the user to. [^4]: Refers to any payment amount *before* any discount was applied. [^5]: Refers to the total paid, and should not be used for any redemption balance. [^6]: This is a domainID representing a store. [^7]: A voucher can be used at one or many vouchers depending on configuration. [^8]: The locations a voucher is assigned might be shared across multiple stores. [^9]: More attributes are included