# 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.](/reference/codes/statuses.md)

## 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](/errors.md) with code `location_not_allowed`
{% endhint %}

## Lookup voucher

<mark style="color:blue;">`GET`</mark> `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" %}

<pre class="language-json" data-line-numbers><code class="lang-json"><strong>{
</strong>  "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
      },
      <a data-footnote-ref href="#user-content-fn-1">{...}</a>
    },
    "current": {
      "GBP": 60,
      <a data-footnote-ref href="#user-content-fn-2">{...}</a>
    }
  },
  "name": "Monetary Voucher",
  <a data-footnote-ref href="#user-content-fn-3">"description"</a>: "Lorem ipsum dolor sit amet...",
  "termsAndConditions": "Lorem ipsum dolor sit amet...",
  "redeemInstructions": "Lorem ipsum dolor sit amet...",
  "redeemCode": "1245441ASDBQ",
  <a data-footnote-ref href="#user-content-fn-4">"subtotal": 100.00,</a>
  <a data-footnote-ref href="#user-content-fn-5">"total": 100.00,</a>
  "status": "Valid",
  "currencyCode": "GBP",
  "partiallyRedeemable": false,
  "redeemableDomains": {
    <a data-footnote-ref href="#user-content-fn-6">"479"</a>: {
      "locations": [
        {
          "locationID": "71",
          "name": "Lymington Hotel Montagne"
        },
        {
          "locationID": "102",
          "name": "Ampress Park Hotel"
        },
        <a data-footnote-ref href="#user-content-fn-7">{...}</a>
       ]
     },
     <a data-footnote-ref href="#user-content-fn-8">{...}</a>
  },
  "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/"
        }
      }
    }
  },            
  <a data-footnote-ref href="#user-content-fn-9">{...}</a>
}
</code></pre>

{% endtab %}

{% tab title="404: Not Found " %}
{% code lineNumbers="true" fullWidth="false" %}

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

{% endcode %}

#### Error codes

<table><thead><tr><th width="240">Code</th><th>Explanation</th></tr></thead><tbody><tr><td>no_matching_code</td><td>The specified code does not exist.</td></tr><tr><td>code_not_activated</td><td>The specified code exists but has not been activated.</td></tr></tbody></table>
{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}
{% endtabs %}

## Topup voucher

<mark style="color:green;">`POST`</mark> `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](/reference/balance-events.md), which also contains a row representing the voucher and the order the row is in.

#### Request Body

| Name                                         | Type   | Description |
| -------------------------------------------- | ------ | ----------- |
| amount<mark style="color:red;">\*</mark>     | String |             |
| locationID<mark style="color:red;">\*</mark> | 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

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark> | 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.giftpro.co.uk/reference/codes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.