canonical: https://jentic.com/apis/clutch.com/clutch

# Clutch API

Jentic maintains this OpenAPI specification for Clutch API, keeping it validated and agent-ready. The Clutch API is the integration surface for the Clutch customer marketing platform's loyalty and gift-card programmes. It exposes operations to create and update customers, issue and look up loyalty or gift cards, retrieve a card balance and transaction history, and record point or value transactions against a card. Authentication uses an HTTP Bearer token, and the API is sized at 10 endpoints covering the core customer-card-transaction model.

## For AI agents

Run a loyalty or gift card programme on Clutch - create customers, issue cards, check balances, and record point or value transactions.

## Scope

Does not handle card payment processing, marketing email delivery, or referral programme management - use for Clutch loyalty and gift card customers, cards, and transactions only.

## Capabilities

- Create and update customer profiles tied to a loyalty or gift card programme
- Search customers by attributes such as email or phone number
- Issue new loyalty or gift cards and look up existing cards by ID
- Retrieve a card's current balance and full transaction history
- Record transactions that earn, redeem, or adjust card value or points
- Look up an individual transaction by ID for support or reconciliation

## Use cases

### Loyalty Points Earning From Point of Sale

Retailers running loyalty on Clutch wire their point-of-sale or e-commerce checkout to POST `/v1/transactions` whenever a customer makes a purchase. The transaction body references the customer's card and the amount or points earned, and Clutch updates the balance returned by GET `/v1/cards/{cardId}/balance` immediately. `/v1/customers/search` resolves the customer by email before the transaction is posted, removing the need for cashiers to look up loyalty IDs manually.

Example prompt: After a $48 purchase, search for the customer by email via POST `/v1/customers/search`, then POST `/v1/transactions` with cardId and the points earned for that purchase amount

### Gift Card Issuance and Redemption

Brands running gift card programmes use POST `/v1/cards` to issue new gift cards in bulk for promotional drops or B2B sales, and customers redeem them via POST `/v1/transactions` at checkout. GET `/v1/cards/{cardId}/balance` returns the remaining value, and GET `/v1/cards/{cardId}/transactions` surfaces the redemption history for support agents handling balance enquiries. The flow runs entirely against the API, removing manual gift card issuance from the marketing team's queue.

Example prompt: Issue 100 gift cards each with $25 value via POST `/v1/cards` in a loop, then send the resulting card IDs to the marketing team for distribution

### Customer Service Lookup During Support Calls

Support agents fielding 'what's my balance' and 'where did my points go' calls use the Clutch API to answer in seconds. `/v1/customers/search` resolves the customer by email or phone, GET `/v1/cards/{cardId}` returns the card details, GET `/v1/cards/{cardId}/balance` returns the current balance, and GET `/v1/cards/{cardId}/transactions` lists the transaction history. The 10-endpoint surface covers everything a tier-one support agent needs to resolve the call without a separate admin tool.

Example prompt: Search for the customer by email via `/v1/customers/search`, retrieve their card via `/v1/cards/{cardId}`, and return the balance plus the last 5 transactions to the support agent

### AI Agent Running Loyalty Operations via Jentic

AI agents handling customer marketing or support can call Clutch through Jentic to issue cards, record transactions, and answer balance enquiries. The agent expresses an intent like 'check a customer's loyalty balance', and Jentic loads the matching Clutch operation, supplies the Bearer token from the vault, and returns the structured response. The same flow scales from individual support resolutions to bulk gift card drops without the agent reading apidocs.clutch.com.

Example prompt: Through Jentic, search for 'check loyalty card balance', load the clutch.com `/v1/cards/{cardId}/balance` operation, and execute it with the customer's cardId

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/customers` | Create a customer |
| POST | `/v1/customers/search` | Search customers |
| POST | `/v1/cards` | Issue a card |
| GET | `/v1/cards/{cardId}/balance` | Get a card's balance |
| GET | `/v1/cards/{cardId}/transactions` | List transactions on a card |
| POST | `/v1/transactions` | Create a transaction |
| GET | `/v1/transactions/{transactionId}` | Get a transaction |

## Key resources

- **Customers** — Create, read, update, and search customer profiles
- **Cards** — Issue and look up loyalty or gift cards and read their balances
- **Transactions** — Record and look up point or value transactions against cards

## Why Jentic

- **Setup:** Wiring Clutch by hand means learning its bearer auth, targeting api.clutch.com, and handling retries across its loyalty and gift-card endpoints yourself. Through Jentic you install once, import the Clutch API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Clutch puts the card id in the URL path (`/v1/cards/{cardId}/...`), so a rule can pin your agent to one card for balance and transaction reads. You choose the operations it may call, so ones that mint value like creating a transaction are not included unless you add them.
- **Credential handling:** Your Clutch token is stored once, encrypted, by your own Jentic One instance and applied to the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'check a loyalty card balance', 'issue a gift card', or 'record a transaction', and Jentic returns the matching Clutch operation with its input schema so the agent calls the right endpoint without browsing apidocs.clutch.com.

## Related APIs

- **LoyaltyLion API** — LoyaltyLion is a directly comparable e-commerce loyalty platform with customers, points, and rewards endpoints
- **Yotpo API** — Yotpo bundles loyalty, reviews, and SMS marketing in a single API platform
- **Stripe API** — Stripe handles the underlying card payment that earns or redeems Clutch loyalty points at checkout

## FAQ

### Does Clutch publish an official machine-readable API specification?

Yes. Clutch serves a legacy Swagger 1.2 document at https://api.clutch.com/api-docs, with a per-resource sub-document at https://api.clutch.com/api-docs/merchant. Swagger 1.2 predates OpenAPI 3 and needs conversion before OpenAPI tooling can read it, so Jentic maintains this OpenAPI 3 specification for Clutch API, derived from the Clutch developer documentation at https://apidocs.clutch.com/ and kept validated and agent-ready. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Clutch API use?

The Clutch API uses an HTTP bearer scheme: an API token is sent in the Authorization header on every request. Through Jentic the token is stored encrypted in the vault and applied at execution time, so the agent never sees the raw token.

### Can I issue a gift card through the Clutch API?

Yes. POST `/v1/cards` creates a new card tied to a customer (or to be assigned later) with the requested initial balance. The response returns the cardId, which is then used to look up the balance via GET `/v1/cards/{cardId}/balance` and to record redemption transactions.

### How do I record a points-earning transaction at checkout?

Look up the customer with POST `/v1/customers/search`, retrieve their cardId, then POST `/v1/transactions` with the cardId and the points or value earned. The card's balance is updated immediately and is reflected in subsequent GET `/v1/cards/{cardId}/balance` calls.

### What are the rate limits for the Clutch API?

The OpenAPI specification does not declare explicit rate limit headers or a 429 response. Clutch applies plan-level limits documented in apidocs.clutch.com, and high-volume integrations should batch transactions per cart rather than per line item. Through Jentic, retries are handled by the SDK.

### How do I check a customer's card balance through Jentic?

Install the SDK with pip install jentic, search for 'check loyalty card balance', load the clutch.com `/v1/cards/{cardId}/balance` operation, and execute it with the cardId. Jentic supplies the Bearer token automatically and returns the current balance.

### Can I retrieve the transaction history for a card?

Yes. GET `/v1/cards/{cardId}/transactions` returns the list of point or value transactions against the card, which is the standard way to populate a customer's account history page or a support agent's lookup screen.

### Can I limit what my agent is allowed to do with the Clutch API?

Yes. Because Jentic One is self-hosted, you write the rules that decide which Clutch operations and credentials your agent may use. You can allow read-only calls like GET `/v1/cards/{cardId}/balance` and GET `/v1/cards/{cardId}/transactions` while withholding value-minting operations such as POST `/v1/cards` and POST `/v1/transactions` unless you explicitly add them. Since the card id sits in the URL path (`/v1/cards/{cardId}/...`), a rule can also pin the agent to a single card for balance and transaction reads.