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

# Create an addon

> Creates a new addon in draft status, associated with a specific product.



## OpenAPI

````yaml https://app.stainless.com/api/spec/documented/stigg/openapi.documented.yml post /api/v1/addons
openapi: 3.0.0
info:
  title: Stigg API
  description: Stigg API documentation
  version: 7.93.1
  contact: {}
servers:
  - url: https://api.stigg.io
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Customers
    description: Operations related to customers
  - name: Subscriptions
    description: Operations related to subscriptions
  - name: Coupons
    description: Operations related to coupons
  - name: Bulk Import
    description: Operations related to import of customers and subscriptions
  - name: Usage
    description: Operations related to usage & metering
  - name: Promotional Entitlements
    description: Operations related to promotional entitlements
  - name: Products
    description: Operations related to products
  - name: Features
    description: Operations related to features
  - name: Addons
    description: Operations related to addons
  - name: Plans
    description: Operations related to plans
  - name: Credit grants
    description: Operations related to credit grants
  - name: Credit ledger
    description: Operations related to credit ledger
  - name: Custom currencies
    description: Operations related to custom currencies
paths:
  /api/v1/addons:
    post:
      tags:
        - Addons
      summary: Create an addon
      description: Creates a new addon in draft status, associated with a specific product.
      operationId: AddonController_createAddon
      parameters:
        - name: X-ACCOUNT-ID
          in: header
          description: >-
            Account ID — optional when authenticating with a user JWT (Bearer
            token); falls back to the user's first membership. Ignored for
            API-key auth.
          required: false
          schema:
            type: string
        - name: X-ENVIRONMENT-ID
          in: header
          description: >-
            Environment ID — required when authenticating with a user JWT
            (Bearer token) on environment-scoped endpoints. Ignored for API-key
            auth (env is intrinsic to the key).
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAddonRequestDto'
      responses:
        '201':
          description: The newly created addon object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddonResponseDto'
              examples:
                default:
                  value:
                    data:
                      id: addon-extra-seats
                      displayName: Extra Seats
                      description: Additional team member seats
                      productId: product-starter
                      status: PUBLISHED
                      pricingType: PAID
                      billingId: price_1234567890
                      versionNumber: 1
                      isLatest: true
                      entitlements:
                        - type: FEATURE
                          id: feature-advanced-analytics
                        - type: CREDIT
                          id: api-calls
                      metadata: {}
                      createdAt: '2025-10-26T10:00:00.000Z'
                      updatedAt: '2025-10-26T10:00:00.000Z'
                      maxQuantity: 100
                      dependencies:
                        - addon-premium-support
        '400':
          description: bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadInputErrorResponseDto'
        '401':
          description: User is not authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedErrorResponseDto'
        '403':
          description: User is not allowed to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponseDto'
        '409':
          description: Addon conflict error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictErrorResponseDto'
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsErrorResponseDto'
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Stigg from '@stigg/typescript';

            const client = new Stigg({
              apiKey: process.env['STIGG_API_KEY'], // This is the default and can be omitted
            });

            const addon = await client.v1.addons.create({
              id: 'id',
              displayName: 'displayName',
              productId: 'productId',
            });

            console.log(addon.data);
        - lang: Python
          source: |-
            import os
            from stigg import Stigg

            client = Stigg(
                api_key=os.environ.get("STIGG_API_KEY"),  # This is the default and can be omitted
            )
            addon = client.v1.addons.create(
                id="id",
                display_name="displayName",
                product_id="productId",
            )
            print(addon.data)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/stiggio/stigg-go\"\n\t\"github.com/stiggio/stigg-go/option\"\n)\n\nfunc main() {\n\tclient := stigg.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\taddon, err := client.V1.Addons.New(context.TODO(), stigg.V1AddonNewParams{\n\t\tID:          \"id\",\n\t\tDisplayName: \"displayName\",\n\t\tProductID:   \"productId\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", addon.Data)\n}\n"
        - lang: Java
          source: |-
            package io.stigg.example;

            import io.stigg.client.StiggClient;
            import io.stigg.client.okhttp.StiggOkHttpClient;
            import io.stigg.models.v1.addons.Addon;
            import io.stigg.models.v1.addons.AddonCreateParams;

            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    StiggClient client = StiggOkHttpClient.fromEnv();

                    AddonCreateParams params = AddonCreateParams.builder()
                        .id("id")
                        .displayName("displayName")
                        .productId("productId")
                        .build();
                    Addon addon = client.v1().addons().create(params);
                }
            }
        - lang: Ruby
          source: >-
            require "stigg"


            stigg = Stigg::Client.new(api_key: "My API Key")


            addon = stigg.v1.addons.create(id: "id", display_name:
            "displayName", product_id: "productId")


            puts(addon)
        - lang: C#
          source: |-
            using System;
            using Stigg.Client;
            using Stigg.Client.Models.V1.Addons;

            StiggClient client = new();

            AddonCreateParams parameters = new()
            {
                ID = "id",
                DisplayName = "displayName",
                ProductID = "productId",
            };

            var addon = await client.V1.Addons.Create(parameters);

            Console.WriteLine(addon);
        - lang: CLI
          source: |-
            stigg v1:addons create \
              --api-key 'My API Key' \
              --id id \
              --display-name displayName \
              --product-id productId
components:
  schemas:
    CreateAddonRequestDto:
      type: object
      properties:
        id:
          type: string
          maxLength: 255
          minLength: 1
          pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$
          description: The unique identifier for the entity
        displayName:
          type: string
          maxLength: 255
          description: The display name of the package
        description:
          type: string
          maxLength: 255
          description: The description of the package
          nullable: true
        productId:
          type: string
          maxLength: 255
          minLength: 1
          pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$
          description: The product id of the package
        pricingType:
          type: string
          enum:
            - FREE
            - PAID
            - CUSTOM
          description: The pricing type of the package
          nullable: true
        billingId:
          type: string
          maxLength: 255
          description: The unique identifier for the entity in the billing provider
          nullable: true
        maxQuantity:
          type: integer
          minimum: 0
          exclusiveMinimum: true
          description: >-
            The maximum quantity of this addon that can be added to a
            subscription
          nullable: true
        status:
          type: string
          enum:
            - DRAFT
            - PUBLISHED
            - ARCHIVED
          description: The status of the package
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Metadata associated with the entity
      required:
        - id
        - displayName
        - productId
      additionalProperties: false
      title: CreateAddonRequest
      description: Request to create a new addon
    AddonResponseDto:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              maxLength: 255
              minLength: 1
              pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$
              description: The unique identifier for the entity
            displayName:
              type: string
              maxLength: 255
              description: The display name of the package
            description:
              type: string
              maxLength: 255
              description: The description of the package
              nullable: true
            productId:
              type: string
              maxLength: 255
              minLength: 1
              pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$
              description: The product id of the package
            status:
              type: string
              enum:
                - DRAFT
                - PUBLISHED
                - ARCHIVED
              description: The status of the package
            pricingType:
              type: string
              enum:
                - FREE
                - PAID
                - CUSTOM
              description: The pricing type of the package
              nullable: true
            billingId:
              type: string
              maxLength: 255
              description: The unique identifier for the entity in the billing provider
              nullable: true
            versionNumber:
              type: integer
              description: The version number of the package
            isLatest:
              type: boolean
              description: Indicates if the package is the latest version
              nullable: true
            entitlements:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - FEATURE
                      - CREDIT
                  id:
                    type: string
                    maxLength: 255
                    description: The unique identifier for the entity
                required:
                  - type
                  - id
                title: PackageEntitlement
                description: Entitlement reference with type and identifier
              description: List of entitlements of the package
            metadata:
              type: object
              additionalProperties:
                type: string
              description: Metadata associated with the entity
            createdAt:
              type: string
              format: date-time
              description: Timestamp of when the record was created
            updatedAt:
              type: string
              format: date-time
              description: Timestamp of when the record was last updated
            maxQuantity:
              type: integer
              minimum: 0
              exclusiveMinimum: true
              description: >-
                The maximum quantity of this addon that can be added to a
                subscription
              nullable: true
            dependencies:
              type: array
              items:
                type: string
                maxLength: 255
                description: The unique identifier for the entity
              description: List of addons the addon is dependant on
              nullable: true
          required:
            - id
            - displayName
            - description
            - productId
            - status
            - pricingType
            - billingId
            - versionNumber
            - isLatest
            - entitlements
            - metadata
            - createdAt
            - updatedAt
            - maxQuantity
            - dependencies
          title: Addon
          description: Addon configuration object
      required:
        - data
      title: Response
      description: Response object
    BadInputErrorResponseDto:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
          enum:
            - BadUserInput
            - DuplicateIntegrationNotAllowed
            - EntityIsArchivedError
            - IntegrityViolation
            - FreePlanCantHaveCompatiblePackageGroupError
            - SubscriptionMustHaveSinglePlanError
            - AddonIsCompatibleWithPlan
            - AddonIsCompatibleWithGroup
            - DuplicateAddonProvisionedError
            - ScheduledMigrationAlreadyExistsError
            - SubscriptionAlreadyOnLatestPlan
            - EntityIdDifferentFromRefIdError
            - UnsupportedFeatureType
            - UnsupportedVendorIdentifier
            - UnsupportedSubscriptionScheduleType
            - InvalidEntitlementResetPeriod
            - IncompatibleSubscriptionAddon
            - UnPublishedPackage
            - MeteringNotAvailableForFeatureType
            - AuthCustomerMismatch
            - AuthCustomerReadonly
            - FetchAllCountriesPricesNotAllowed
            - MemberInvitationError
            - PlansCircularDependencyError
            - NoFeatureEntitlementInSubscription
            - CheckoutIsNotSupported
            - UnsupportedParameter
            - PricingModelNotSupportedByBillingIntegration
            - BillingIntegrationMissing
            - BillingIntegrationAlreadyExistsError
            - InvalidMemberDelete
            - PackageAlreadyPublished
            - DraftPlanCantBeArchived
            - DraftAddonCantBeArchived
            - PlanWithChildCantBeDeleted
            - PlanCannotBePublishWhenBasePlanIsDraft
            - PlanCannotBePublishWhenCompatibleAddonIsDraft
            - PlanIsUsedAsDefaultStartPlan
            - PlanIsUsedAsDowngradePlan
            - InvalidAddressError
            - InvalidQuantity
            - BillingPeriodMissingError
            - DowngradeBillingPeriodNotSupportedError
            - CustomerAlreadyUsesCouponError
            - CustomerAlreadyHaveCustomerCoupon
            - SubscriptionAlreadyCanceledOrExpired
            - TrialMustBeCancelledImmediately
            - SubscriptionDoesNotHaveBillingPeriod
            - InvalidCancellationDate
            - FailedToImportCustomer
            - FailedToImportSubscriptions
            - PackagePricingTypeNotSet
            - InvalidSubscriptionStatus
            - InvalidArgumentError
            - EditAllowedOnDraftPackageOnlyError
            - ResyncAlreadyInProgress
            - ArchivedCouponCantBeApplied
            - ImportAlreadyInProgress
            - AddonHasToHavePriceError
            - SelectedBillingModelDoesntMatchImportedItemError
            - CannotArchiveProductError
            - CannotUnarchiveProductError
            - CannotDeleteCustomerError
            - CannotRemovePaymentMethodFromCustomerError
            - CannotDeleteFeatureError
            - CannotArchiveFeatureError
            - InvalidUpdatePriceUnitAmountError
            - ExperimentAlreadyRunning
            - ExperimentStatusError
            - OperationNotAllowedDuringInProgressExperiment
            - EntitlementsMustBelongToSamePackage
            - CanNotUpdateEntitlementsFeatureGroup
            - MeterMustBeAssociatedToMeteredFeature
            - CannotEditPackageInNonDraftMode
            - CannotAddOverrideEntitlementToPlan
            - MissingEntityIdError
            - NoProductsAvailable
            - PromotionCodeNotForCustomer
            - PromotionCodeNotActive
            - PromotionCodeMaxRedemptionsReached
            - PromotionCodeMinimumAmountNotReached
            - PromotionCodeCustomerNotFirstPurchase
            - AddonWithDraftCannotBeDeletedError
            - CannotReportUsageForEntitlementWithMeterError
            - RecalculateEntitlementsError
            - ImportSubscriptionsBulkError
            - InvalidMetadataError
            - CannotUpsertToPackageThatHasDraft
            - IntegrationValidationError
            - AwsMarketplaceIntegrationValidationError
            - AwsMarketplaceIntegrationError
            - DataExportIntegrationError
            - HubspotIntegrationError
            - DuplicateProductValidationError
            - AmountTooLarge
            - CustomerHasNoEmailAddress
            - MergeEnvironmentValidationError
            - EntitlementLimitExceededError
            - EntitlementUsageOutOfRangeError
            - UsageMeasurementDiffOutOfRangeError
            - AddonQuantityExceedsLimitError
            - AddonDependencyMissingError
            - PackageGroupMinItemsError
            - CannotUpdateUnitTransformationError
            - SingleSubscriptionCantBeAutoCancellationTargetError
            - MultiSubscriptionCantBeAutoCancellationSourceError
            - ChangingPayingCustomerIsNotSupportedError
            - RequiredSsoAuthenticationError
            - InvalidDoggoSignatureError
            - InvalidReceivedSignatureError
            - CannotDeleteDefaultIntegration
            - CannotChangeBillingIntegration
            - FailedToResolveBillingIntegration
            - WorkflowTriggerNotFound
            - DeprecatedEstimateSubscriptionError
            - FeatureConfigurationExceededLimitError
            - FeatureNotBelongToFeatureGroupError
            - FeatureGroupMissingFeaturesError
            - VersionExceedsMaxValueError
            - CannotUpdateExpireAtForExpiredCreditGrantError
            - ExpireAtMustBeLaterThanEffectiveAtError
            - OfferAlreadyExists
            - DraftAlreadyExists
            - CreditGrantAlreadyVoided
            - CreditGrantCannotBeVoided
            - InvalidTaxId
            - ObjectAlreadyBeingUsedByAnotherRequestError
            - TooManySubscriptionsPerCustomer
            - TooManyCustomCurrencies
            - StripeError
            - SchedulingAtEndOfBillingPeriod
            - ApiKeyExpired
            - ApiKeyHasExpiry
          nullable: true
      required:
        - message
        - code
    UnauthenticatedErrorResponseDto:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
          enum:
            - Unauthenticated
          nullable: true
      required:
        - message
        - code
    ForbiddenErrorResponseDto:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
          enum:
            - IdentityForbidden
            - AccessDeniedError
            - NoFeatureEntitlementError
            - GovernanceNotEnabled
          nullable: true
      required:
        - message
        - code
    ConflictErrorResponseDto:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
          enum:
            - DuplicatedEntityNotAllowed
            - EntitlementBelongsToFeatureGroupError
            - InvoicePreviewNotAvailableForDraftContract
          nullable: true
      required:
        - message
        - code
    TooManyRequestsErrorResponseDto:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
          enum:
            - RateLimitExceeded
          nullable: true
      required:
        - message
        - code
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Server API Key

````