canonical: https://jentic.com/apis/swaggerhub.direct-wines/agent-gift-cards-api-suite

# Direct Wines Agent Gift Cards API Suite

This set of APIs allows the management of Gift Card balances. It is only supported for use within the Grapevine system. The API exposes 5 endpoints.

## For AI agents

Programmatically query gift card balance, query orders wtih gift card id. Covers 5 operations.

## Scope

Does not handle payments, communications, or developer tools - use for crm only.

## Capabilities

- Query Gift Card Balance
- delete the payment group id from the input order id
- update the transaction log after reverse call of gift card details for the given
- Query and filter Agent Gift Cards API Suite records by parameters
- Monitor Agent Gift Cards API Suite operational status and events

## Use cases

### CRM Operations

Use the Agent Gift Cards API Suite to perform crm operations programmatically. The API provides 5 endpoints covering core functionality including query gift card balance, query orders wtih gift card id, query savvy transaction log for gift card id.

Example prompt: Call GET /agent/giftcards/{cardNumber}/balance to query gift card balance

### Automated Agent Management

Automate agent operations by combining multiple Agent Gift Cards API Suite endpoints. Agents can query orders wtih gift card id and then query savvy transaction log for gift card id in a single workflow.

Example prompt: Call GET /agent/giftcards/orders/{cardNumber} to query orders wtih gift card id, then verify the result

### AI Agent Integration via Jentic

AI agents discover and call Agent Gift Cards API Suite endpoints through Jentic without managing credentials directly. An agent searches for the required operation by intent, receives the matching endpoint schema, and executes the call with Jentic-managed authentication. This eliminates the need to read API documentation or handle none tokens manually.

Example prompt: Search Jentic for 'query gift card balance', load the operation schema, and execute with Jentic-managed credentials

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /agent/giftcards/{cardNumber}/balance | Query Gift Card Balance |
| GET | /agent/giftcards/orders/{cardNumber} | Query Orders wtih Gift Card Id |
| GET | /agent/giftcards/transactionLogs/{cardNumber} | Query Savvy Transaction Log for Gift Card Id |
| DELETE | /agent/giftcards/order/payment/remove/{orderId}/{cardNumber} | delete the payment group id from the input order id |
| DELETE | /agent/giftcards/transaction/reverse/{transactionId}/{cardNumber} | update the transaction log after reverse call of gift card details for the given |

## Key resources

- **Agent** — Operations for agent

## Why Jentic

- **Setup:** Wiring the Agent Gift Cards API Suite by hand means reading its OpenAPI definition, pointing at the right server, and hand-coding each gift-card call and its retries yourself. Through Jentic you install once, import the Agent Gift Cards API Suite from the API Directory, store any credential it needs once, and your agent calls it.
- **Permission scoping:** The Agent Gift Cards API Suite puts the card number in the URL path (/agent/giftcards/{cardNumber}/...), so a rule can pin your agent to one card: it can read that card's balance, orders, and transaction logs and nothing else. You choose the operations it may call, so destructive ones like removing an order payment or reversing a transaction are not included unless you add them.
- **Credential handling:** Any credential this API requires is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'check a gift card balance' or 'list a gift card's orders', and Jentic returns the matching Agent Gift Cards API Suite operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Hubspot** — Alternative crm API
- **Salesforce** — Alternative crm API
- **Pipedrive** — Complementary crm API
- **Zoho** — Complementary crm API

## FAQ

### What authentication does the Agent Gift Cards API Suite use?

The Agent Gift Cards API Suite uses no authentication. Through Jentic, these credentials are stored encrypted in your Jentic One instance and injected at execution time, so raw secrets never enter the agent context.

### Can I query gift card balance with the Agent Gift Cards API Suite?

Yes. Use the GET /agent/giftcards/{cardNumber}/balance endpoint. The API returns structured JSON responses that agents can parse and act on directly.

### What are the rate limits for the Agent Gift Cards API Suite?

Rate limits are not specified in the OpenAPI spec. Check the vendor documentation for current limits. Through Jentic, rate limiting is handled automatically with retry logic built into the execution layer.

### How do I query gift card balance through Jentic?

Install the Jentic SDK with pip install jentic, authenticate through Jentic One, the self-hosted execution layer, then search for 'query gift card balance'. Jentic returns the matching Agent Gift Cards API Suite operation with its input schema. Load the schema and execute the call - credentials are injected automatically.

### How many endpoints does the Agent Gift Cards API Suite have?

The Agent Gift Cards API Suite exposes 5 endpoints covering agent operations.

### Can I limit what my agent is allowed to do with the Agent Gift Cards API Suite?

Yes. Jentic One is self-hosted, so your own rules decide which operations and credentials the agent may use. Because the card number sits in the URL path, you can pin the agent to a single card and let it only read that card's balance, orders, and transaction logs. You choose the operations it may call, so destructive ones like removing an order payment or reversing a transaction stay out of reach unless you explicitly add them.