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

# Coupon

Represents a coupon in the Stigg system. Coupons provide discounts to customers, either as a percentage off or a fixed amount.

## Type Definition

```graphql theme={null}
type Coupon {
  id: UUID!
  refId: String!
  name: String!
  description: String
  type: CouponType!
  status: CouponStatus!
  source: CouponSource!

  # Discount values
  percentOff: Float
  amountsOff: [Money!]

  # Duration
  durationInMonths: Float

  # Integration
  billingId: String
  billingLinkUrl: String
  syncStates: [SyncState!]

  # Customers
  customers: [Customer!]

  # Metadata
  additionalMetaData: JSON

  # Timestamps
  createdAt: DateTime!
  updatedAt: DateTime!
  environmentId: UUID!
  environment: Environment
}
```

## Fields

### Core Fields

| Field         | Type                                                                    | Description                          |
| ------------- | ----------------------------------------------------------------------- | ------------------------------------ |
| `id`          | `UUID!`                                                                 | Unique identifier for the coupon     |
| `refId`       | `String!`                                                               | Your reference ID for this coupon    |
| `name`        | `String!`                                                               | Coupon name/code                     |
| `description` | `String`                                                                | Coupon description                   |
| `type`        | [`CouponType!`](/api-and-sdks/api-reference/types/enums#coupontype)     | Type of discount (PERCENTAGE, FIXED) |
| `status`      | [`CouponStatus!`](/api-and-sdks/api-reference/types/enums#couponstatus) | Current status                       |
| `source`      | [`CouponSource!`](/api-and-sdks/api-reference/types/enums#couponsource) | Where the coupon was created         |

### Discount Values

| Field        | Type       | Description                               |
| ------------ | ---------- | ----------------------------------------- |
| `percentOff` | `Float`    | Percentage discount (for PERCENTAGE type) |
| `amountsOff` | `[Money!]` | Fixed amounts off in different currencies |

### Duration

| Field              | Type    | Description                                           |
| ------------------ | ------- | ----------------------------------------------------- |
| `durationInMonths` | `Float` | How many months the discount applies (null = forever) |

### Integration

| Field            | Type           | Description                       |
| ---------------- | -------------- | --------------------------------- |
| `billingId`      | `String`       | Coupon ID in billing provider     |
| `billingLinkUrl` | `String`       | URL to coupon in billing provider |
| `syncStates`     | `[SyncState!]` | Integration sync status           |

### Customers

| Field       | Type                                                        | Description                 |
| ----------- | ----------------------------------------------------------- | --------------------------- |
| `customers` | [`[Customer!]`](/api-and-sdks/api-reference/types/customer) | Customers using this coupon |

## CouponType Enum

| Value        | Description                  |
| ------------ | ---------------------------- |
| `PERCENTAGE` | Discount is a percentage off |
| `FIXED`      | Discount is a fixed amount   |

## CouponStatus Enum

| Value      | Description                         |
| ---------- | ----------------------------------- |
| `ACTIVE`   | Coupon is active and can be applied |
| `ARCHIVED` | Coupon is no longer available       |

## CouponSource Enum

| Value     | Description                  |
| --------- | ---------------------------- |
| `STIGG`   | Created in Stigg             |
| `BILLING` | Synced from billing provider |

## SubscriptionCoupon Type

When a coupon is applied to a subscription:

```graphql theme={null}
type SubscriptionCoupon {
  id: UUID!
  name: String!
  type: CouponType!
  percentOff: Float
  amountsOff: [Money!]
  durationInMonths: Float
  environmentId: UUID!
}
```

## Example Response

### Percentage Coupon

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "refId": "SAVE20",
  "name": "SAVE20",
  "description": "20% off for new customers",
  "type": "PERCENTAGE",
  "status": "ACTIVE",
  "source": "STIGG",
  "percentOff": 20,
  "durationInMonths": null,
  "billingId": "coupon_abc123",
  "billingLinkUrl": "https://dashboard.stripe.com/coupons/coupon_abc123",
  "createdAt": "2024-01-10T10:00:00Z",
  "updatedAt": "2024-01-10T10:00:00Z"
}
```

### Fixed Amount Coupon

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "refId": "SAVE10",
  "name": "SAVE10",
  "description": "$10 off your first month",
  "type": "FIXED",
  "status": "ACTIVE",
  "source": "STIGG",
  "amountsOff": [
    {
      "amount": 10.00,
      "currency": "USD"
    },
    {
      "amount": 9.00,
      "currency": "EUR"
    }
  ],
  "durationInMonths": 1,
  "billingId": "coupon_def456",
  "createdAt": "2024-01-15T14:30:00Z",
  "updatedAt": "2024-01-15T14:30:00Z"
}
```

### Limited Duration Coupon

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "refId": "TRIAL3",
  "name": "TRIAL3",
  "description": "50% off for first 3 months",
  "type": "PERCENTAGE",
  "status": "ACTIVE",
  "source": "STIGG",
  "percentOff": 50,
  "durationInMonths": 3,
  "customers": [
    {
      "customerId": "customer-123",
      "name": "Acme Corp"
    },
    {
      "customerId": "customer-456",
      "name": "Startup Inc"
    }
  ],
  "createdAt": "2024-01-20T09:00:00Z",
  "updatedAt": "2024-01-20T09:00:00Z"
}
```

### Archived Coupon

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "refId": "SUMMER2023",
  "name": "SUMMER2023",
  "description": "Summer promotion 2023",
  "type": "PERCENTAGE",
  "status": "ARCHIVED",
  "source": "STIGG",
  "percentOff": 25,
  "durationInMonths": 2,
  "createdAt": "2023-06-01T00:00:00Z",
  "updatedAt": "2023-09-01T00:00:00Z"
}
```

## Related Types

* [Customer](/api-and-sdks/api-reference/types/customer) - Customer type
* [CustomerSubscription](/api-and-sdks/api-reference/types/subscription) - Subscription type

## Related Operations

* [Create Coupon](/api-and-sdks/api-reference/mutations/create-coupon) - Create new coupon
* [Set Coupon on Customer](/api-and-sdks/api-reference/mutations/set-coupon-on-customer) - Apply coupon
* [List Coupons](/api-and-sdks/api-reference/queries/list-coupons) - Query coupons