# API

{% embed url="<https://doc.highlightcards.co.uk/>" %}

### API Access

**API access is available on the Business plan only.**

### Authentication & API Key

To get your API key, go to:\
[**Settings**](https://app.highlightcards.co.uk/settings/) **→** [**Integrations**](https://app.highlightcards.co.uk/settings/integrations)<br>

#### Authentication method

* **Type:** API Key
* **API Key parameter name:** `x-api-key`
* **API key placement:** Request header
* **Value:** Your API key from account settings

### **Types of cards:**

| Card Type          | ID |
| ------------------ | -: |
| Stamp              |  0 |
| Cashback           |  1 |
| Multipass          |  2 |
| Coupon             |  3 |
| Discount           |  4 |
| Gift (Certificate) |  5 |
| Membership         |  6 |
| Reward             |  7 |

### Card balance & activity methods

* **Add amount to card** — Cashback (ID 1)
* **Add point to card** — Cashback (ID 1), Discount (ID 4), Gift/Certificate (ID 5)
* **Add reward to card** — Stamp (ID 0)
* **Add scores to card** — Multipass (ID 2), Reward (ID 7) with mechanics type “Points”
* **Add stamp to card** — Stamp (ID 0)
* **Add visit to card** — Multipass (ID 2), Membership (ID 6) without limits, Stamp (ID 0) with visit mechanics, Reward (ID 7) with visit mechanics
* **Add purchase to card (add amount)** — Stamp (ID 0) with spend mechanics, Reward (ID 7) with spend mechanics
* **Receive reward (by client)** — Reward (ID 7)
* **Redeem coupon** — Coupon (ID 3)
* **Subtract amount from card** — Cashback (ID 1)
* **Subtract point from card** — Cashback (ID 1), Discount (ID 4), Gift/Certificate (ID 5)
* **Subtract reward from card** — Stamp (ID 0)
* **Subtract scores from card (subtract points)** — Multipass (ID 2), Reward (ID 7)
* **Subtract stamp from card** — Stamp (ID 0)
* **Subtract visit from card** — Multipass (ID 2), Membership (ID 6) with limits

### Core API endpoints

#### Cards

* **GET** `/cards` — List of cards
* **POST** `/cards` — Create card for customer (issue card)
* **GET** `/cards/{number}` — Get card by number
* **DELETE** `/cards/{number}` — Delete card by number

#### Customers

* **GET** `/customers` — List customers
* **GET** `/customers/{id}` — Get customer by ID
* **POST** `/customers` — Create customer
* **PATCH** `/customers/{id}` — Update customer data
* **DELETE** `/customers/{id}` — Delete customer by ID

#### Operations

* **GET** `/operations` — List operations

#### Push notifications

* **GET** `/pushes/{id}` — Get push by ID
* **GET** `/pushes` — List pushes
* **POST** `/pushes` — Send push

#### Templates

* **GET** `/templates/{id}` — Get template by ID
* **GET** `/templates` — List company card templates

### Redeeming rewards with cost (Stamp cards)

When redeeming a reward, you can specify its monetary value so it is added to the customer’s **LTV**. Use **Subtract reward from card**.

**POST**

```
https://api.highlightcards.co.uk/api/v2/cards/544256-439-856/subtract-reward
```

**Where:**\
`544256-439-856` = **Card serial number** (customer’s card QR / barcode)

**Example request**

```json
{
  "rewards": 1,
  "comment": "Reward redeemed",
  "purchaseSum": 10.5
}
```

* `rewards` — number of rewards to subtract
* `comment` — optional transaction note
* `purchaseSum` — reward value added to LTV

**Important:** The API does not auto-read reward prices from card settings; `purchaseSum` must be provided manually.

### Rate limits

* **10 requests/second** (**600 requests/minute**)
* Exceeding the limit returns **HTTP 429 – Too Many Requests**
* The limit is fixed; implement retries with backoff or request queueing