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

# Coupontools API

Jentic publishes the only available OpenAPI specification for Coupontools API, keeping it validated and agent-ready. The Coupontools API exposes a digital coupon and campaign platform across 9 endpoints, supporting CRUD on coupons, redemption, validation, and campaign retrieval. Authentication uses paired X-API-Key and X-API-Secret headers on the v3 base URL. Suitable for retailers, loyalty programs, and marketing teams that need to issue, distribute, and redeem digital coupons programmatically rather than through the Coupontools UI.

## For AI agents

Create, distribute, validate, and redeem digital coupons, and read campaign details. Suitable for marketing automation flows that issue and track promotional codes.

## Scope

Does not handle gift card processing, point-of-sale terminals, or full loyalty point ledgers - use for digital coupon issuance, validation, and redemption only.

## Capabilities

- Create new digital coupons with specific value, expiry, and redemption rules
- List, retrieve, update, and delete coupons through the v3 endpoint set
- Validate a coupon code before applying a discount at checkout
- Redeem a coupon and mark it consumed via the redeem endpoint
- List active marketing campaigns and retrieve campaign details
- Issue per-customer coupon codes inside automated email or SMS flows

## Use cases

### E-Commerce Discount Code Issuance

Generate unique digital coupons on the fly when a shopper completes a signup, abandons a cart, or hits a milestone. POST /coupon creates the coupon, GET `/coupon/{couponId}/validate` is called from the checkout backend before applying the discount, and POST `/coupon/{couponId}/redeem` marks it consumed once the order is placed. Keeps fraud risk low because each code is single-use and validated server-side.

Example prompt: On cart abandonment, call POST /coupon to create a 10% off code, then email it to the shopper with a 7-day expiry

### Campaign Performance Sync

Pull campaign details from Coupontools into a marketing data warehouse to join coupon redemption data with email, SMS, and ad spend. GET /campaign and GET `/campaign/{campaignId}` return the structured campaign records, and the per-coupon endpoints give the redemption history needed to attribute revenue to a specific promotion.

Example prompt: Daily, call GET /campaign, then for each campaign call GET /coupon to load redemption counts into a warehouse staging table

### Loyalty Program Redemption

Power a loyalty or rewards program where members exchange points for digital coupons. The agent creates the coupon when a member redeems points, returns it via email, and validates and redeems it when the member uses it in store or online. Each step is a single API call, so the flow can run inside a serverless function.

Example prompt: When a member redeems 500 points, call POST /coupon to mint a $5 reward and POST `/coupon/{couponId}/redeem` when the member uses it

### AI Agent Promo Concierge

Let an AI agent handle promo issuance and validation through Jentic. The agent searches for the right operation in plain English, supplies the discount value and expiry, and the X-API-Key plus X-API-Secret stay in the encrypted vault. Agents can issue and validate coupons inside chat or voice channels without ever seeing the credentials.

Example prompt: Use Jentic to search 'create a Coupontools coupon', load the schema for POST /coupon, and execute it with discount, expiry, and customer reference

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/coupon` | Create a coupon |
| GET | `/coupon` | List coupons |
| GET | `/coupon/{couponId}` | Get coupon details |
| PUT | `/coupon/{couponId}` | Update a coupon |
| DELETE | `/coupon/{couponId}` | Delete a coupon |
| POST | `/coupon/{couponId}/redeem` | Redeem a coupon |
| GET | `/coupon/{couponId}/validate` | Validate a coupon |
| GET | `/campaign` | List campaigns |

## Key resources

- **Coupons** — Create, list, retrieve, update, delete, redeem, and validate digital coupons
- **Campaigns** — List campaigns and retrieve campaign details

## Why Jentic

- **Setup:** Wiring Coupontools by hand means handling its paired API-key request header and secret-key header auth, pinning the v3 host, and coding your own coupon issuance and redemption calls. Through Jentic you install once, import Coupontools from the API Directory, store the key and secret once, and your agent calls it.
- **Permission scoping:** Coupontools puts the coupon id in the URL path (`/coupon/{couponId}`, `/coupon/{couponId}/redeem`), so a rule can pin your agent to one coupon: it acts only on that coupon. You choose the operations it may call, so destructive ones like deleting a coupon are not included unless you add them.
- **Credential handling:** Your Coupontools key and secret are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'validate a coupon' or 'redeem a coupon', and Jentic returns the matching Coupontools operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Talon.One API** — Promotion engine with rule-based discounts, loyalty, and referrals
- **LoyaltyLion API** — Loyalty platform that issues points and rewards used as discounts
- **Reward Loyalty API** — Loyalty platform with rewards, tiers, and referral tracking

## FAQ

### Why is there no official OpenAPI spec for Coupontools API?

Coupontools does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Coupontools API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Coupontools API use?

Coupontools requires paired credentials sent as the `X-API-Key` and `X-API-Secret` headers on every request. Through Jentic, both values are stored encrypted in your Jentic One instance and the agent receives a scoped session token rather than the raw credentials.

### Can I validate a coupon code before applying a discount?

Yes. Call GET `/coupon/{couponId}/validate` with the coupon ID. The response indicates whether the coupon is active, unexpired, and not yet redeemed, so a checkout backend can decide whether to honour the discount.

### How do I redeem a coupon at checkout?

POST `/coupon/{couponId}/redeem` marks the coupon as consumed and is the right endpoint to call once an order has been confirmed. Pair it with the validate call to keep redemption logic atomic.

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

Coupontools applies plan-tier-based rate limits rather than a single public number. Most live shops should batch list calls and rely on per-coupon validate/redeem calls during user actions to stay well within typical quotas.

### How do I issue a coupon through Jentic?

Search Jentic for 'create a Coupontools coupon', load the schema for POST /coupon, and execute it with discount value, expiry, and any customer reference. Jentic supplies the X-API-Key and X-API-Secret headers automatically.

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

Yes. Because you run Jentic One yourself, your own rules decide which Coupontools operations the agent may call, so you can allow validate and redeem while withholding destructive calls like DELETE `/coupon/{couponId}` unless you explicitly add them. Since the coupon id sits in the URL path (for example `/coupon/{couponId}/redeem`), a rule can pin the agent to a single coupon so it acts only on that one. The paired X-API-Key and X-API-Secret stay in your own instance and are injected at execution time, so the agent never handles the raw credentials.