> ## 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 a promotional entitlements > Grants promotional entitlements to a customer, providing feature access outside their subscription. Entitlements can be time-limited or permanent. ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/stigg/openapi.documented.yml post /api/v1/customers/{id}/promotional-entitlements openapi: 3.0.0 info: title: Stigg API description: Stigg API documentation version: 7.99.2 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/customers/{id}/promotional-entitlements: post: tags: - Promotional Entitlements summary: Create a promotional entitlements description: >- Grants promotional entitlements to a customer, providing feature access outside their subscription. Entitlements can be time-limited or permanent. operationId: PromotionalEntitlementsController_grantPromotionalEntitlements parameters: - name: id required: true in: path description: The unique identifier of the entity schema: minLength: 1 maxLength: 255 type: string - 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/GrantPromotionalEntitlementsRequestDto' responses: '201': description: The granted promotional entitlement objects. content: application/json: schema: $ref: '#/components/schemas/PromotionalEntitlementsResponseDto' '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: Promotional Entitlements 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 promotionalEntitlement = await client.v1.customers.promotionalEntitlements.create('x', { promotionalEntitlements: [ { customEndDate: '2019-12-27T18:11:19.117Z', enumValues: ['string'], featureId: 'featureId', hasSoftLimit: true, hasUnlimitedUsage: true, isVisible: true, monthlyResetPeriodConfiguration: { accordingTo: 'SubscriptionStart' }, period: '1 week', resetPeriod: 'YEAR', usageLimit: -9007199254740991, weeklyResetPeriodConfiguration: { accordingTo: 'SubscriptionStart' }, yearlyResetPeriodConfiguration: { accordingTo: 'SubscriptionStart' }, }, ], }); console.log(promotionalEntitlement.data); - lang: Python source: >- import os from datetime import datetime from stigg import Stigg client = Stigg( api_key=os.environ.get("STIGG_API_KEY"), # This is the default and can be omitted ) promotional_entitlement = client.v1.customers.promotional_entitlements.create( id="x", promotional_entitlements=[{ "custom_end_date": datetime.fromisoformat("2019-12-27T18:11:19.117"), "enum_values": ["string"], "feature_id": "featureId", "has_soft_limit": True, "has_unlimited_usage": True, "is_visible": True, "monthly_reset_period_configuration": { "according_to": "SubscriptionStart" }, "period": "1 week", "reset_period": "YEAR", "usage_limit": -9007199254740991, "weekly_reset_period_configuration": { "according_to": "SubscriptionStart" }, "yearly_reset_period_configuration": { "according_to": "SubscriptionStart" }, }], ) print(promotional_entitlement.data) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"time\"\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\tpromotionalEntitlement, err := client.V1.Customers.PromotionalEntitlements.New(\n\t\tcontext.TODO(),\n\t\t\"x\",\n\t\tstigg.V1CustomerPromotionalEntitlementNewParams{\n\t\t\tPromotionalEntitlements: []stigg.V1CustomerPromotionalEntitlementNewParamsPromotionalEntitlement{{\n\t\t\t\tCustomEndDate: stigg.Time(time.Now()),\n\t\t\t\tEnumValues: []string{\"string\"},\n\t\t\t\tFeatureID: \"featureId\",\n\t\t\t\tHasSoftLimit: stigg.Bool(true),\n\t\t\t\tHasUnlimitedUsage: stigg.Bool(true),\n\t\t\t\tIsVisible: stigg.Bool(true),\n\t\t\t\tMonthlyResetPeriodConfiguration: stigg.V1CustomerPromotionalEntitlementNewParamsPromotionalEntitlementMonthlyResetPeriodConfiguration{\n\t\t\t\t\tAccordingTo: \"SubscriptionStart\",\n\t\t\t\t},\n\t\t\t\tPeriod: \"1 week\",\n\t\t\t\tResetPeriod: \"YEAR\",\n\t\t\t\tUsageLimit: stigg.Int(-9007199254740991),\n\t\t\t\tWeeklyResetPeriodConfiguration: stigg.V1CustomerPromotionalEntitlementNewParamsPromotionalEntitlementWeeklyResetPeriodConfiguration{\n\t\t\t\t\tAccordingTo: \"SubscriptionStart\",\n\t\t\t\t},\n\t\t\t\tYearlyResetPeriodConfiguration: stigg.V1CustomerPromotionalEntitlementNewParamsPromotionalEntitlementYearlyResetPeriodConfiguration{\n\t\t\t\t\tAccordingTo: \"SubscriptionStart\",\n\t\t\t\t},\n\t\t\t}},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", promotionalEntitlement.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.customers.promotionalentitlements.PromotionalEntitlementCreateParams; import io.stigg.models.v1.customers.promotionalentitlements.PromotionalEntitlementCreateResponse; import java.time.OffsetDateTime; public final class Main { private Main() {} public static void main(String[] args) { StiggClient client = StiggOkHttpClient.fromEnv(); PromotionalEntitlementCreateParams params = PromotionalEntitlementCreateParams.builder() .id("x") .addPromotionalEntitlement(PromotionalEntitlementCreateParams.PromotionalEntitlement.builder() .customEndDate(OffsetDateTime.parse("2019-12-27T18:11:19.117Z")) .addEnumValue("string") .featureId("featureId") .hasSoftLimit(true) .hasUnlimitedUsage(true) .isVisible(true) .monthlyResetPeriodConfiguration(PromotionalEntitlementCreateParams.PromotionalEntitlement.MonthlyResetPeriodConfiguration.builder() .accordingTo(PromotionalEntitlementCreateParams.PromotionalEntitlement.MonthlyResetPeriodConfiguration.AccordingTo.SUBSCRIPTION_START) .build()) .period(PromotionalEntitlementCreateParams.PromotionalEntitlement.Period._1_WEEK) .resetPeriod(PromotionalEntitlementCreateParams.PromotionalEntitlement.ResetPeriod.YEAR) .usageLimit(-9007199254740991L) .weeklyResetPeriodConfiguration(PromotionalEntitlementCreateParams.PromotionalEntitlement.WeeklyResetPeriodConfiguration.builder() .accordingTo(PromotionalEntitlementCreateParams.PromotionalEntitlement.WeeklyResetPeriodConfiguration.AccordingTo.SUBSCRIPTION_START) .build()) .yearlyResetPeriodConfiguration(PromotionalEntitlementCreateParams.PromotionalEntitlement.YearlyResetPeriodConfiguration.builder() .accordingTo(PromotionalEntitlementCreateParams.PromotionalEntitlement.YearlyResetPeriodConfiguration.AccordingTo.SUBSCRIPTION_START) .build()) .build()) .build(); PromotionalEntitlementCreateResponse promotionalEntitlement = client.v1().customers().promotionalEntitlements().create(params); } } - lang: Ruby source: >- require "stigg" stigg = Stigg::Client.new(api_key: "My API Key") promotional_entitlement = stigg.v1.customers.promotional_entitlements.create( "x", promotional_entitlements: [ { customEndDate: "2019-12-27T18:11:19.117Z", enumValues: ["string"], featureId: "featureId", hasSoftLimit: true, hasUnlimitedUsage: true, isVisible: true, monthlyResetPeriodConfiguration: {accordingTo: :SubscriptionStart}, period: :"1 week", resetPeriod: :YEAR, usageLimit: -9007199254740991, weeklyResetPeriodConfiguration: {accordingTo: :SubscriptionStart}, yearlyResetPeriodConfiguration: {accordingTo: :SubscriptionStart} } ] ) puts(promotional_entitlement) - lang: C# source: >- using System; using Stigg.Client; using Stigg.Client.Models.V1.Customers.PromotionalEntitlements; StiggClient client = new(); PromotionalEntitlementCreateParams parameters = new() { ID = "x", PromotionalEntitlements = [ new() { CustomEndDate = DateTimeOffset.Parse("2019-12-27T18:11:19.117Z"), EnumValues = [ "string" ], FeatureID = "featureId", HasSoftLimit = true, HasUnlimitedUsage = true, IsVisible = true, MonthlyResetPeriodConfiguration = new( AccordingTo.SubscriptionStart ), Period = Period.V1Week, ResetPeriod = ResetPeriod.Year, UsageLimit = -9007199254740991, WeeklyResetPeriodConfiguration = new( WeeklyResetPeriodConfigurationAccordingTo.SubscriptionStart ), YearlyResetPeriodConfiguration = new( YearlyResetPeriodConfigurationAccordingTo.SubscriptionStart ), }, ], }; var promotionalEntitlement = await client.V1.Customers.PromotionalEntitlements.Create(parameters); Console.WriteLine(promotionalEntitlement); - lang: CLI source: |- stigg v1:customers:promotional-entitlements create \ --api-key 'My API Key' \ --id x \ --promotional-entitlement "{customEndDate: '2019-12-27T18:11:19.117Z', enumValues: [string], featureId: featureId, hasSoftLimit: true, hasUnlimitedUsage: true, isVisible: true, monthlyResetPeriodConfiguration: {accordingTo: SubscriptionStart}, period: 1 week, resetPeriod: YEAR, usageLimit: -9007199254740991, weeklyResetPeriodConfiguration: {accordingTo: SubscriptionStart}, yearlyResetPeriodConfiguration: {accordingTo: SubscriptionStart}}" components: schemas: GrantPromotionalEntitlementsRequestDto: type: object properties: promotionalEntitlements: type: array items: type: object properties: featureId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: The unique identifier of the entitlement feature usageLimit: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: The usage limit of the entitlement nullable: true hasSoftLimit: type: boolean description: Whether the entitlement has a soft limit nullable: true hasUnlimitedUsage: type: boolean description: Whether the entitlement has an unlimited usage nullable: true customEndDate: type: string format: date-time description: The custom end date of the promotional entitlement nullable: true period: type: string enum: - 1 week - 1 month - 6 month - 1 year - lifetime - custom description: The grant period of the promotional entitlement isVisible: type: boolean description: Whether the entitlement is visible nullable: true yearlyResetPeriodConfiguration: type: object properties: accordingTo: type: string enum: - SubscriptionStart description: Reset anchor (SubscriptionStart) required: - accordingTo title: YearlyResetPeriodConfig description: >- The yearly reset period configuration of the entitlement, defined when reset period is yearly nullable: true monthlyResetPeriodConfiguration: type: object properties: accordingTo: type: string enum: - SubscriptionStart - StartOfTheMonth description: Reset anchor (SubscriptionStart or StartOfTheMonth) required: - accordingTo title: MonthlyResetPeriodConfig description: >- The monthly reset period configuration of the entitlement, defined when reset period is monthly nullable: true weeklyResetPeriodConfiguration: type: object properties: accordingTo: type: string enum: - SubscriptionStart - EverySunday - EveryMonday - EveryTuesday - EveryWednesday - EveryThursday - EveryFriday - EverySaturday description: Reset anchor (SubscriptionStart or specific day) required: - accordingTo title: WeeklyResetPeriodConfig description: >- The weekly reset period configuration of the entitlement, defined when reset period is weekly nullable: true resetPeriod: type: string enum: - YEAR - MONTH - WEEK - DAY - HOUR nullable: true description: The reset period of the entitlement enumValues: type: array items: type: string maxLength: 255 description: The enum values of the entitlement maxItems: 255 nullable: true description: The enum values of the entitlement required: - featureId - usageLimit - hasSoftLimit - hasUnlimitedUsage - customEndDate - period - isVisible - yearlyResetPeriodConfiguration - monthlyResetPeriodConfiguration - weeklyResetPeriodConfiguration - resetPeriod - enumValues additionalProperties: false title: GrantPromotionalEntitlementRequest description: Single entitlement grant config minItems: 1 description: Promotional entitlements to grant required: - promotionalEntitlements additionalProperties: false title: GrantPromotionalEntitlementsRequest description: Grant promotional entitlements to a customer for a specified period. PromotionalEntitlementsResponseDto: type: object properties: data: type: array items: type: object properties: id: type: string format: uuid description: Unique identifier for the entity description: type: string maxLength: 255 description: The description of the entitlement nullable: true featureId: type: string format: uuid description: The unique identifier of the entitlement feature 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 startDate: type: string format: date-time description: The start date of the entitlement endDate: type: string format: date-time description: The end date of the promotional entitlement nullable: true isVisible: type: boolean description: Whether the entitlement is visible usageLimit: type: number description: The usage limit of the entitlement nullable: true hasSoftLimit: type: boolean description: Whether the entitlement has a soft limit nullable: true hasUnlimitedUsage: type: boolean description: Whether the entitlement has an unlimited usage nullable: true status: type: string enum: - Active - Expired - Paused description: The status of the entitlement period: type: string enum: - 1 week - 1 month - 6 month - 1 year - lifetime - custom description: The grant period of the promotional entitlement resetPeriod: type: string enum: - YEAR - MONTH - WEEK - DAY - HOUR nullable: true description: The reset period of the entitlement resetPeriodConfiguration: oneOf: - type: object properties: accordingTo: type: string enum: - SubscriptionStart description: Reset anchor (SubscriptionStart) required: - accordingTo title: YearlyResetPeriodConfig description: Yearly reset configuration - type: object properties: accordingTo: type: string enum: - SubscriptionStart - StartOfTheMonth description: Reset anchor (SubscriptionStart or StartOfTheMonth) required: - accordingTo title: MonthlyResetPeriodConfig description: Monthly reset configuration - type: object properties: accordingTo: type: string enum: - SubscriptionStart - EverySunday - EveryMonday - EveryTuesday - EveryWednesday - EveryThursday - EveryFriday - EverySaturday description: Reset anchor (SubscriptionStart or specific day) required: - accordingTo title: WeeklyResetPeriodConfig description: Weekly reset configuration nullable: true description: The reset period configuration of the entitlement environmentId: type: string format: uuid description: The unique identifier for the environment enumValues: type: array items: type: string maxLength: 255 description: The enum values of the entitlement nullable: true description: The enum values of the entitlement featureGroupIds: type: array items: type: string maxLength: 255 description: Feature group IDs associated with this entitlement nullable: true description: Feature group IDs associated with this entitlement required: - id - description - featureId - createdAt - updatedAt - startDate - endDate - isVisible - usageLimit - hasSoftLimit - hasUnlimitedUsage - status - period - resetPeriod - resetPeriodConfiguration - environmentId - enumValues - featureGroupIds title: PromotionalEntitlement description: Granted feature entitlement 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 ````