# Piggy

Piggy offers cashback and loyalty program integrations for online stores, letting users earn points or discounts and encouraging repeat purchases

- **Category:** marketing automation
- **Auth:** API_KEY
- **Composio Managed App Available?** N/A
- **Tools:** 14
- **Triggers:** 0
- **Slug:** `PIGGY`
- **Version:** 20260227_00

## Tools

### Claim Anonymous Contact

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | No | The real email address for the Contact that is about to be not anonymous anymore |
| `anonymous_contact_uuid` | string | Yes | The anonymous Contact's UUID containing the fictional email address |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Contact Attribute

**Slug:** `PIGGY_CREATE_CONTACT_ATTRIBUTE`

Tool to create a custom Contact Attribute. Use when you need to define new fields for contacts after initial setup.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Unique internal identifier for the Contact Attribute |
| `label` | string | No | Display label for the Contact Attribute |
| `options` | array | No | List of options for select or multi_select types. Each option has label and value |
| `data_type` | string ("url" | "text" | "date" | "phone" | "float" | "color" | "email" | "number" | "select" | "boolean" | "rich_text" | "date_time" | "long_text" | "date_range" | "time_range" | "identifier" | "birth_date" | "file_upload" | "media_upload" | "multi_select" | "license_plate") | Yes | Data type of the attribute. Determines how values are validated and rendered |
| `description` | string | No | Human-readable description of the Contact Attribute |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Credit Reception

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `credits` | integer | No | Fixed number of credits to award. Either unit_value or credits must be provided |
| `shop_uuid` | string | Yes | UUID of the shop where the transaction occurred |
| `unit_value` | integer | No | Unit value (e.g., purchase amount in cents) for calculating credits. Either unit_value or credits must be provided |
| `contact_uuid` | string | Yes | UUID of the contact to receive credits |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Vouchers Batch

**Slug:** `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 initially.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `quantity` | integer | Yes | The number of Vouchers you want to generate (min: 1, max: 500) |
| `contact_uuid` | string | No | The Contact's UUID to be linked to the batch of Vouchers |
| `promotion_uuid` | string | Yes | UUID of the Promotion for which the Vouchers are to be created |
| `activation_date` | string | No | The activation date for the batch of Vouchers in ISO 8601 format |
| `expiration_date` | string | No | The expiration date for the batch of Vouchers in ISO 8601 format |
| `custom_attributes` | array | No | Additional Custom Attributes for the Vouchers |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Find or Create Products

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | The name of the Product. Required when creating a new product |
| `categories` | array | No | List of Categories that the product belongs to. Each category can be referenced by uuid or external_identifier |
| `description` | string | No | The description of the Product |
| `external_identifier` | string | Yes | A unique identifier from your system to find or create the product |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Find Voucher By Code

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `code` | string | Yes | The unique code of the Voucher, which serves as its identifier |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Contact Auth Token

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `contact_uuid` | string | Yes | UUID of the Contact for which to retrieve an auth token |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Contact's Credit Balance

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `contact_uuid` | string | Yes | The UUID of the Contact for which to retrieve the credit balance |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Forms

**Slug:** `PIGGY_LIST_FORMS`

Tool to list all forms in the Piggy account. Use when you need to retrieve available forms for customer interactions.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Perks

**Slug:** `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.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Merge Contacts

**Slug:** `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 removed. This operation is irreversible and processed asynchronously via a job queue. Use this when consolidating duplicate customer records.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source_contact_uuid` | string | Yes | UUID of the source contact to merge. This contact will be removed after the merge, and all its data will be transferred to the destination contact. |
| `destination_contact_uuid` | string | Yes | UUID of the destination contact. This contact will remain active and receive all data from the source contact after the merge. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Send Contact Verification Email

**Slug:** `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. Use this when implementing email-based authentication workflows or when contacts need to verify their email address to access the Contacts Portal.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | Yes | Email address of the Contact to send the verification email to. The contact must already exist in the Piggy system. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Bookings

**Slug:** `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.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `source` | string | No | Source from where the Booking was created |
| `status` | string ("created" | "in_progress" | "canceled" | "completed") | No | Booking status values. |
| `ends_at` | string | No | The end date and time of the Booking in ISO 8601 format |
| `starts_at` | string | No | The start date and time of the Booking in ISO 8601 format |
| `external_id` | string | No | External identifier for the Booking |
| `booking_uuid` | string | Yes | The UUID of the Booking to update |
| `company_name` | string | No | Company name associated with the booking |
| `checked_in_at` | string | No | The date and time when the party checked into the booking in ISO 8601 format |
| `prepaid_amount` | integer | No | Amount prepaid (in cents) prior to booking start |
| `number_of_people` | integer | No | Party size for the booking |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Contact Identifiers

**Slug:** `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 identifier value itself cannot be changed.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `contact_identifier_name` | string | No | Display name of the contact identifier. Use this to update the human-readable label. |
| `contact_identifier_value` | string | Yes | The unique value of the contact identifier to update. This is the identifier of the contact identifier record itself. |
| `contact_identifier_active` | boolean | No | Active state of the contact identifier. Set to false to deactivate, true to activate. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |