> ## 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.

# Addon

Represents an addon in the Stigg system. Addons are optional packages that can be added to a subscription to provide additional features or increased limits.

## Type Definition

```graphql theme={null}
type Addon {
  id: UUID!
  refId: String!
  displayName: String!
  description: String
  status: PackageStatus!
  type: String!
  versionNumber: Int!
  isLatest: Boolean

  # Pricing
  pricingType: PricingType
  prices: [Price!]
  overagePrices: [Price!]
  overageBillingPeriod: OverageBillingPeriod

  # Quantity limits
  maxQuantity: Float

  # Entitlements
  packageEntitlements: [PackageEntitlementUnion!]

  # Dependencies
  dependencies: [Addon!]

  # Subscriptions
  hasSubscriptions: Boolean!

  # Related entities
  product: Product
  productId: String
  offer: Offer

  # Metadata
  additionalMetaData: JSON
  hiddenFromWidgets: [WidgetType!]

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

  # Draft management
  draftDetails: PackageDraftDetails
  draftSummary: PackageDraftSummary

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

## Fields

### Core Fields

| Field           | Type                                                                      | Description                                         |
| --------------- | ------------------------------------------------------------------------- | --------------------------------------------------- |
| `id`            | `UUID!`                                                                   | Unique identifier for the addon                     |
| `refId`         | `String!`                                                                 | Your application's unique identifier for this addon |
| `displayName`   | `String!`                                                                 | Display name shown to customers                     |
| `description`   | `String`                                                                  | Addon description                                   |
| `status`        | [`PackageStatus!`](/api-and-sdks/api-reference/types/enums#packagestatus) | Publication status (DRAFT, PUBLISHED, ARCHIVED)     |
| `type`          | `String!`                                                                 | Package type identifier                             |
| `versionNumber` | `Int!`                                                                    | Version number of this addon                        |
| `isLatest`      | `Boolean`                                                                 | Whether this is the latest version                  |

### Pricing

| Field                  | Type                                                                 | Description                              |
| ---------------------- | -------------------------------------------------------------------- | ---------------------------------------- |
| `pricingType`          | [`PricingType`](/api-and-sdks/api-reference/types/enums#pricingtype) | Type of pricing (FREE, PAID, CUSTOM)     |
| `prices`               | [`[Price!]`](/api-and-sdks/api-reference/types/price)                | Price configurations for this addon      |
| `overagePrices`        | [`[Price!]`](/api-and-sdks/api-reference/types/price)                | Overage pricing for usage-based features |
| `overageBillingPeriod` | `OverageBillingPeriod`                                               | When overage is billed                   |

### Quantity

| Field         | Type    | Description                                          |
| ------------- | ------- | ---------------------------------------------------- |
| `maxQuantity` | `Float` | Maximum quantity that can be added to a subscription |

### Entitlements

| Field                 | Type                         | Description                         |
| --------------------- | ---------------------------- | ----------------------------------- |
| `packageEntitlements` | `[PackageEntitlementUnion!]` | Entitlements provided by this addon |

### Dependencies

| Field          | Type                                                  | Description                        |
| -------------- | ----------------------------------------------------- | ---------------------------------- |
| `dependencies` | [`[Addon!]`](/api-and-sdks/api-reference/types/addon) | Other addons this addon depends on |

### Related Entities

| Field              | Type       | Description                              |
| ------------------ | ---------- | ---------------------------------------- |
| `product`          | `Product`  | The product this addon belongs to        |
| `productId`        | `String`   | Product identifier                       |
| `hasSubscriptions` | `Boolean!` | Whether any subscriptions use this addon |

## SubscriptionAddon Type

When an addon is attached to a subscription, it's represented as:

```graphql theme={null}
type SubscriptionAddon {
  id: UUID!
  addonId: String!
  addon: Addon!
  quantity: Float!
  price: Price
  subscription: CustomerSubscription!
  createdAt: DateTime
  updatedAt: DateTime!
}
```

| Field      | Type                                                | Description                                     |
| ---------- | --------------------------------------------------- | ----------------------------------------------- |
| `addonId`  | `String!`                                           | Reference ID of the addon                       |
| `addon`    | [`Addon!`](/api-and-sdks/api-reference/types/addon) | The addon object                                |
| `quantity` | `Float!`                                            | Quantity of this addon in the subscription      |
| `price`    | [`Price`](/api-and-sdks/api-reference/types/price)  | Price configuration for this subscription addon |

## Example Response

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "refId": "addon-extra-seats",
  "displayName": "Extra Seats",
  "description": "Add more team members to your plan",
  "status": "PUBLISHED",
  "versionNumber": 1,
  "isLatest": true,
  "pricingType": "PAID",
  "maxQuantity": 100,
  "prices": [
    {
      "id": "price-456",
      "billingModel": "PER_UNIT",
      "billingPeriod": "MONTHLY",
      "price": {
        "amount": 10.00,
        "currency": "USD"
      }
    }
  ],
  "packageEntitlements": [
    {
      "feature": {
        "refId": "feature-seats",
        "displayName": "Team Seats"
      },
      "usageLimit": 1,
      "hasUnlimitedUsage": false
    }
  ],
  "hasSubscriptions": true,
  "product": {
    "refId": "product-saas",
    "displayName": "SaaS Platform"
  },
  "createdAt": "2024-01-10T10:00:00Z",
  "updatedAt": "2024-01-15T15:30:00Z"
}
```

## Related Types

* [Plan](/api-and-sdks/api-reference/types/plan) - Plan type
* [Price](/api-and-sdks/api-reference/types/price) - Price configuration type
* [Feature](/api-and-sdks/api-reference/types/feature) - Feature type

## Related Operations

* [Get Addon](/api-and-sdks/api-reference/queries/get-addon) - Fetch a single addon
* [List Addons](/api-and-sdks/api-reference/queries/list-addons) - Query addons
* [Create Addon](/api-and-sdks/api-reference/mutations/create-addon) - Create new addon