> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snappy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Campaigns API (V2): Plan, Schedule, and Report on Gifting Campaigns

> Plan, schedule, and report on gifting campaigns. Estimate cost, track delivery, and trigger from CRM or HR events.

A **Campaign** is the primary organizational object for configuring and sending gifts. It acts as a reusable template that defines all the settings for a gifting activity - including the gift type, budget, branding, notification messages, and billing.

Every gift in Snappy must be created within a Campaign.

<Tip>
  Want to understand how **Campaigns** fit into the bigger picture? Check out the [Core Concepts & Data Models](/pages/snappy-core-concepts-and-data-models) page.
</Tip>

***

## The Campaign Object

| Field           | Type   | Description                                                                                                                                                                                                       |
| :-------------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`            | string | Unique identifier for the Campaign                                                                                                                                                                                |
| `name`          | string | Display name of the Campaign                                                                                                                                                                                      |
| `status`        | string | Current status of the Campaign. See [Campaign Statuses](#campaign-statuses) below                                                                                                                                 |
| `type`          | string | Campaign type. Possible values: `anniversary`, `birthday`, `schedule`, `marketing`, `oneOffs`, `newHire`. The API only allows creating `oneOffs` - other types are created via the Snappy Dashboard.              |
| `source`        | string | Indicates how the Campaign was created (e.g. `dashboard`, `dashboard_ai`, `api_native`, `api_zapier`, `api_make`, `api_salesforce`, `api_ftp`)                                                                    |
| `accountId`     | string | The ID of the Account this Campaign belongs to                                                                                                                                                                    |
| `companyId`     | string | The ID of the Company this Campaign belongs to                                                                                                                                                                    |
| `account`       | object | Embedded Account summary containing `id` and `name`                                                                                                                                                               |
| `customization` | object | Gift Customization configuration including `giftProperties`, `notificationPolicy`, and `recipientExperience`. See [Core Concepts & Data Models → Gift Customization](/pages/snappy-core-concepts-and-data-models) |
| `createdAt`     | string | ISO 8601 timestamp of when the Campaign was created                                                                                                                                                               |
| `updatedAt`     | string | ISO 8601 timestamp of the last update                                                                                                                                                                             |

***

## Campaign Statuses

| Status      | Description                                                                 |
| :---------- | :-------------------------------------------------------------------------- |
| `draft`     | The Campaign is being configured and is not yet ready to send gifts         |
| `pending`   | The Campaign is awaiting activation (typically a Dashboard approval step)   |
| `scheduled` | The Campaign is scheduled to activate at a future date                      |
| `active`    | The Campaign is live and gifts can be created under it                      |
| `live`      | Equivalent to `active` for some Campaign types (Dashboard-driven)           |
| `paused`    | The Campaign has been temporarily paused. No new gifts can be created       |
| `sent`      | All gifts in the Campaign have been sent (terminal state for one-off sends) |
| `archived`  | The Campaign has been archived. No new gifts can be created                 |

***

## Key Concepts & Business Rules

#### Every gift requires a Campaign

A Campaign must exist before any gifts can be created. It provides the context, budget, and configuration for every gift sent within it.

#### Collection or Product - not both

A Campaign is configured with either a Collection (recipient chooses from a catalog) or a specific Product (a predetermined item). These are mutually exclusive - you cannot assign both to the same Campaign.

#### Billing Method

Each Campaign is assigned exactly one Billing Method at creation. This is the funding source that will be debited each time a gift is sent under this Campaign. If the Billing Method has insufficient funds, gift creation will fail.

When a Campaign is created via the API, it is automatically assigned the Account's default Billing Method. When created via the Dashboard, you can select any active Billing Method on the Account.

#### Gift Customization inheritance

Campaigns inherit Gift Customization defaults from their parent Account and Company. Any settings defined at the Campaign level override the Account defaults and apply to all gifts created under this Campaign, unless overridden again at the individual Gift level.

<Tip>
  See [Core Concepts & Data Models → Gift Customization](/pages/snappy-core-concepts-and-data-models) for the full inheritance model.
</Tip>

***

## How to Work with Campaigns

**Create a Campaign**

Campaigns can be created via the Snappy Dashboard or programmatically via the API. For most use cases we recommend creating Campaigns in the Dashboard, where you can configure Gift Customization settings visually and preview the recipient experience.

```text theme={null} theme={null}
POST /v2/campaigns
```

**Retrieve Campaigns**

To retrieve a list of all Campaigns available to your API key:

```text theme={null} theme={null}
GET /v2/campaigns
```

To retrieve a specific Campaign by ID:

```text theme={null} theme={null}
GET /v2/campaigns/{campaignId}
```

**Update a Campaign**

Campaign settings can be updated after creation. Changes to Gift Customization settings apply only to gifts created **after** the update - previously created gifts are not affected.

```text theme={null} theme={null}
PATCH /v2/campaigns/{campaignId}
```

**Estimate the Campaign Cost**

Before launching a Campaign, you can retrieve an estimated cost based on the configured budget and a target number of gifts:

```text theme={null} theme={null}
GET /v2/campaigns/{campaignId}/estimatedCost
```

*