# Piggy — how to use (mcp.ai)

Connect your Piggy account and use 14 tools for marketing automation straight from your AI agent. Connect with your own API key. Piggy offers cashback and loyalty program integrations for online stores, letting users earn points or discounts and encouraging repeat purchases.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_piggy?ms=1787293560000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `piggy_claim_anonymous_contact`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/piggy`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/piggy/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/piggy/claim/anonymous/contact` — Tool to claim an anonymous contact by associating it with a real email address. Use when converting an anonymous contact (with a fictional email) into a verified contact with a real email address.
  - body: { email?: string, anonymous_contact_uuid: string }
- `POST https://api.mcp.ai/api/piggy/create/contact/attribute` — Tool to create a custom Contact Attribute. Use when you need to define new fields for contacts after initial setup.
  - body: { name: string, label?: string, options?: object[], data_type: string, description?: string }
- `POST https://api.mcp.ai/api/piggy/create/credit/reception` — Tool to create a credit reception for a contact. Use when awarding credits to customers based on purchases or fixed amounts.
  - body: { credits?: integer, shop_uuid: string, unit_value?: integer, contact_uuid: string }
- `POST https://api.mcp.ai/api/piggy/create/vouchers/batch` — Tool to create a batch of vouchers for a promotion. Use when you need to generate multiple vouchers at once for a specific promotion. Batch processing is asynchronous and returns a PENDING status init
  - body: { quantity: integer, contact_uuid?: string, promotion_uuid: string, activation_date?: string, expiration_date?: string, custom_attributes?: object[] }
- `POST https://api.mcp.ai/api/piggy/find/or/create/products` — Tool to find an existing product by external_identifier or create a new one if it doesn't exist. Use when you need to ensure a product exists in Piggy's system for loyalty programs or rewards.
  - body: { name?: string, categories?: object[], description?: string, external_identifier: string }
- `POST https://api.mcp.ai/api/piggy/find/voucher/by/code` — Tool to find a voucher by its unique code. Use when you need to retrieve voucher details, check redemption status, or validate a voucher code.
  - body: { code: string }
- `POST https://api.mcp.ai/api/piggy/get/contact/auth/token` — Tool to get an auth token for a Contact. Use after obtaining a Contact UUID and needing to verify identity for secure operations.
  - body: { contact_uuid: string }
- `POST https://api.mcp.ai/api/piggy/get/contacts/credit/balance` — Tool to get a Contact's credit balance. Use when you need to check a contact's current credit balance before processing rewards or promotions.
  - body: { contact_uuid: string }
- `POST https://api.mcp.ai/api/piggy/list/forms` — Tool to list all forms in the Piggy account. Use when you need to retrieve available forms for customer interactions.
- `POST https://api.mcp.ai/api/piggy/list/perks` — Tool to list all available perks in Piggy. Use when you need to retrieve the catalog of perks that can be associated with contacts or transactions.
- `POST https://api.mcp.ai/api/piggy/merge/contacts` — Merges a source contact into a destination contact in Piggy's CRM. The source contact's data (attributes, balances, transactions) is transferred to the destination contact, and the source contact is r
  - body: { source_contact_uuid: string, destination_contact_uuid: string }
- `POST https://api.mcp.ai/api/piggy/send/contact/verification/email` — Send a verification email to a Piggy contact for identity verification. The contact must exist in the system with a configured Contacts Portal. Returns success message with email sent confirmation. Us
  - body: { email: string }
- `POST https://api.mcp.ai/api/piggy/update/bookings` — Tool to update an existing booking in Piggy. Use when you need to modify booking details such as party size, status, or company name. Note: Shop and contact cannot be updated after creation.
  - body: { source?: string, status?: string, ends_at?: string, starts_at?: string, external_id?: string, booking_uuid: string, company_name?: string, checked_in_at?: string, prepaid_amount?: integer, number_of_people?: integer }
- `POST https://api.mcp.ai/api/piggy/update/contact/identifiers` — Tool to update a contact identifier in Piggy. Use when you need to modify the display name or active state of an existing contact identifier. Only the name and active properties can be updated; the id
  - body: { contact_identifier_name?: string, contact_identifier_value: string, contact_identifier_active?: boolean }

## Example prompts
- "What can I do in Piggy?"
- "Show me a summary of my Piggy account"

## More
- Page: https://mcp.ai/piggy
- Agent spec (llms.txt): https://mcp.ai/piggy/llms.txt
- Postman collection: https://mcp.ai/piggy/postman.json