# BuyPass API Schema Reference

> **Auto-generated**: 2026-02-27 18:50 UTC
> **Source**: Pydantic model schemas with Field descriptions

This document provides the complete API schema for programmatic pass creation.
For URL-based pass creation (simpler), see `/llms.txt`.

---

## Overview

BuyPass supports two methods for creating wallet passes:

1. **URL Parameters** (documented in `/llms.txt`)
   - Simple link building with query params
   - Best for: ChatGPT, quick integrations, shared links

2. **API Endpoint** (documented here)
   - Full programmatic control via POST request
   - Best for: AI agents, automated workflows, custom integrations

---

## API Endpoint

**POST** `/cards/passes/preview`

Creates a wallet pass and returns download URLs for Apple and Google Wallet.

**Content-Type**: `multipart/form-data` (supports file uploads)

**Authentication**: Optional (creates anonymous preview pass if unauthenticated)

---

## Request Schema

### CardTypeRequestSchema

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `id` | string | null | No | `null` | ID of the card type to edit. |
| `groupId` | string | null | No | `null` | Identifier for the group to which this card type belongs. |
| `title` | string (max 15 chars) | **Yes** | `-` | Title for the card type - REQUIRED |
| `description` | string | null | No | `null` | Description/subtitle for the card type (max 40 chars). |
| `numPointsForRedemption` | integer | null | No | `null` | Minimum number of points required for redemption for the card type. |
| `backgroundColor` | string | null | No | `#fffffe` | Background color for issued cards in hex format |
| `foregroundColor` | string | null | No | `#000001` | Foreground color for issued cards in hex format. |
| `labelColor` | string | null | No | `#000001` | Label color for issued cards in hex format. |
| `iconUrl` | string | null | No | `https://framerusercontent.c...` | URL for the icon to be displayed on issued cards. |
| `customFieldTemplates` | array | null | No | `null` | Custom field templates for the card (camelCase format from frontend). |
| `shouldHideTitle` | boolean | null | No | `False` | Option to hide the title on the card. |
| `stripImageUrl` | string | null | No | `null` | URL for the strip image to be displayed on issued cards. |
| `heroImageUrl` | string | null | No | `null` | URL for the hero/background image to be displayed on issued cards. |
| `layoutStyle` | string | null | No | `CLASSIC` | Layout style for the card (CLASSIC, MODERN, ANGULAR). |
| `showTier` | boolean | null | No | `False` | Option to show tier information on the card. |
| `cardStatus` | string | null | No | `ACTIVE` | Status of the card (ACTIVE, PREVIEW, INACTIVE). |
| `customFields` | CustomPassFieldsSchema | null | No | `null` | Custom fields to display on the pass (legacy JSON format). |
| `pointsLabel` | string | null | No | `You Have` | Custom label for the points field (position fixed). |
| `alternateEncodedData` | string | null | No | `null` | Custom data to encode in the QR code (e.g., a URL). If provided, this replace... |
| `locationName` | string | null | No | `null` | Name of the location (e.g., business name from Google Places). |
| `locationAddress` | string | null | No | `null` | Full address of the location. |
| `locationLatitude` | number | null | No | `null` | Latitude coordinate of the location. |
| `locationLongitude` | number | null | No | `null` | Longitude coordinate of the location. |
| `globalRelevantDate` | string | null | No | `null` | Target date for all passes of this type. Used for Apple Wallet relevantDate n... |
| `notificationDateMessage` | string | null | No | `null` | Message shown when the globalRelevantDate notification triggers on Apple Wallet. |
| `passSource` | string | null | No | `null` | How this pass was created: TEMPLATE, FROM_TEMPLATE, CUSTOM, or API. |
| `sourceTemplateId` | string | null | No | `null` | ID of the template CardType this pass was created from (if FROM_TEMPLATE). |

---

## Response Schema

### PreviewPassResponse

Response from preview pass creation

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `success` | boolean | **Yes** | `-` | Whether preview creation was successful |
| `downloadUrl` | string | **Yes** | `-` | URL to download the preview pass |
| `applePassUrl` | string | **Yes** | `-` | URL to download Apple Wallet pass |
| `googlePassUrl` | string | **Yes** | `-` | URL to download Google Wallet pass |
| `cardTypeId` | string | **Yes** | `-` | ID of the created card type |
| `previewPassId` | string | **Yes** | `-` | ID of the preview pass (same as cardTypeId) |
| `previewData` | PreviewPassData | **Yes** | `-` | - |
### PreviewPassData (nested in response)

Preview pass metadata

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `points` | integer | **Yes** | `-` | Points to show in preview |
| `tier` | string | **Yes** | `-` | Tier to show in preview |
| `title` | string (max 15 chars) | **Yes** | `-` | Title of the preview pass |
| `icon_url` | string | null | No | `null` | Logo/icon image URL |
| `hero_image_url` | string | null | No | `null` | Hero image URL |
| `strip_image_url` | string | null | No | `null` | Strip image URL |

---

## Custom Field Templates

Add custom fields to the back of the pass (up to 4 fields).

Each field can be:
- **Static**: Fixed text value
- **Dynamic**: Value derived from user card properties (for rewards programs)

### CustomFieldTemplateFromFrontendSchema

Schema for parsing CustomFieldTemplate from frontend (camelCase). Converts to snake_case for internal use.

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `key` | string | **Yes** | `-` | - |
| `label` | string | **Yes** | `-` | - |
| `fieldType` | FieldType | No | `static` | - |
| `position` | FieldPosition | No | `back` | - |
| `displayOrder` | integer | No | `0` | - |
| `staticValue` | string | null | No | `null` | - |
| `sourceProperty` | string | null | No | `null` | - |
| `transform` | TransformType | null | No | `null` | Transformation: 'COUNTDOWN', 'DATE_FORMAT' |
| `formatTemplate` | string | null | No | `null` | - |
| `showWhen` | string | null | No | `null` | - |

---

## Enum Values

### FieldType

Type of custom field value.

| Value | Name |
|-------|------|
| `static` | STATIC |
| `dynamic` | DYNAMIC |

### FieldPosition

Where the field appears on the pass.

| Value | Name |
|-------|------|
| `auxiliary` | AUXILIARY |
| `back` | BACK |

### TransformType

Optional transformation for dynamic fields.

| Value | Name |
|-------|------|
| `COUNTDOWN` | COUNTDOWN |
| `DATE_FORMAT` | DATE_FORMAT |

---

## Color Extraction (Optional)

Upload an image to extract brand colors automatically.

**POST** `/cards/passes/extract-colors`

### ColorScheme

Color scheme for pass creation

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `name` | string | **Yes** | `-` | Name of the color scheme (e.g., 'Dominant', 'Light', 'Dark') |
| `backgroundColor` | string | **Yes** | `-` | Background color in hex format |
| `foregroundColor` | string | **Yes** | `-` | Foreground color in hex format |
| `labelColor` | string | **Yes** | `-` | Label color in hex format |

---

## Examples

### Minimal Pass (QR Code Only)

```json
{
  "title": "My Portfolio",
  "alternateEncodedData": "https://myportfolio.com"
}
```

### Full Pass with Custom Fields

```json
{
  "title": "Coffee Rewards",
  "description": "Earn points with every purchase",
  "backgroundColor": "#4A2C2A",
  "foregroundColor": "#FFFFFF",
  "labelColor": "#D4A574",
  "alternateEncodedData": "https://coffeeshop.com/rewards",
  "locationName": "Downtown Coffee",
  "locationAddress": "123 Main St, Seattle WA",
  "locationLatitude": 47.6062,
  "locationLongitude": -122.3321,
  "customFieldTemplates": [
    {
      "key": "hours",
      "label": "Hours",
      "fieldType": "static",
      "position": "back",
      "displayOrder": 0,
      "staticValue": "Mon-Fri 7am-6pm"
    },
    {
      "key": "phone",
      "label": "Phone",
      "fieldType": "static",
      "position": "back",
      "displayOrder": 1,
      "staticValue": "(206) 555-0123"
    }
  ]
}
```

### Event Pass with Date

```json
{
  "title": "Tech Summit 2025",
  "description": "Annual Developer Conference",
  "backgroundColor": "#1a1a2e",
  "foregroundColor": "#eaeaea",
  "alternateEncodedData": "https://techsummit.io/ticket/abc123",
  "locationName": "Convention Center",
  "locationAddress": "800 Convention Place, Seattle WA",
  "globalRelevantDate": "2025-06-15T09:00:00Z",
  "notificationDateMessage": "Tech Summit starts tomorrow!"
}
```

---

## Image Upload

When using `multipart/form-data`, include images as file fields:

- `logo`: Square icon/logo (recommended: 512x512px PNG)
- `strip_image`: Banner image (recommended: 1125x432px PNG, 3:1 aspect)

### Crop Coordinates (Optional)

If the uploaded image needs cropping:

- `strip_image_crop_x`: X offset in pixels
- `strip_image_crop_y`: Y offset in pixels
- `strip_image_crop_width`: Crop width in pixels
- `strip_image_crop_height`: Crop height in pixels

Same pattern for logo: `logo_crop_x`, `logo_crop_y`, etc.

---

## Error Handling

| Status | Meaning |
|--------|---------|
| 200 | Success - pass created |
| 400 | Validation error (check field constraints) |
| 413 | Image too large (max 10MB) |
| 422 | Invalid request format |
| 500 | Server error |

Error responses include a `detail` field with specific error message.

---

## Rate Limits

- Anonymous: 10 passes/minute
- Authenticated: 100 passes/minute

---

## Integration Tips for AI Agents

1. **Always set `alternateEncodedData`** - This is the QR code destination URL
2. **Use hex colors with #** - e.g., `#FF9900` not `FF9900`
3. **Title max 15 chars** - Keep it short for wallet display
4. **Description max 40 chars** - Appears as subtitle
5. **Location improves UX** - Wallet shows pass when user is nearby
6. **Custom fields appear on back** - Use for contact info, hours, etc.