> ## 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. # Upsert entity entitlements > Batched create-or-update of entity entitlements. Existing entity entitlements matched by (entityId, featureId or currencyId, scopeEntityIds) are updated; new ones are created. On update, omitted fields (usageLimit, cadence) are preserved; on create both are required. ## OpenAPI ````yaml /openapi/stigg-api.documented.yml put /api/v1/customers/{id}/entities/entitlements openapi: 3.0.0 info: title: Stigg API description: Stigg API documentation version: 8.177.5 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}/entities/entitlements: put: tags: - Governance Entity Entitlements summary: Upsert entity entitlements description: >- Batched create-or-update of entity entitlements. Existing entity entitlements matched by (entityId, featureId or currencyId, scopeEntityIds) are updated; new ones are created. On update, omitted fields (usageLimit, cadence) are preserved; on create both are required. operationId: EntityEntitlementController_upsertEntityEntitlements parameters: - name: id required: true in: path description: The customer identifier (owner) the entity entitlements belong to schema: minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$ 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/UpsertEntityEntitlementsRequestDto' examples: default: value: entityEntitlements: - entityId: workspace-001 featureId: compute-minutes usageLimit: 1000 cadence: P1M - entityId: workspace-002 currencyId: cred-type-tokens usageLimit: 2000 cadence: P1M parentId: workspace-001 scopeEntityIds: - user-1 responses: '200': description: Entity entitlements after upsert. content: application/json: schema: $ref: '#/components/schemas/UpsertEntityEntitlementsResponseDto' examples: default: value: data: - id: 6f6b9c39-3a14-4a5e-9c6c-2a4f8d8d2f3f entityId: workspace-001 featureId: feature-compute-minutes scopeEntityIds: [] parentId: null usageLimit: 1000 cadence: P1M createdAt: '2026-05-18T10:00:00.000Z' updatedAt: '2026-05-18T10:00:00.000Z' '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' '404': description: EntityEntitlement not found. content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponseDto' '429': description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsErrorResponseDto' components: schemas: UpsertEntityEntitlementsRequestDto: type: object properties: entityEntitlements: type: array items: type: object properties: entityId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: The entity ID this entity entitlement is attached to featureId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: >- Feature ID this entity entitlement grants. Mutually exclusive with `currencyId`. currencyId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: >- Currency ID this entity entitlement grants (credit limits). Mutually exclusive with `featureId`. scopeEntityIds: type: array items: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: >- Dimension-scoped sub-limit: the set of entity IDs this limit applies to (order-insensitive). Omit or leave empty for the node-wide limit. parentId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: >- Parent entity ID in the hierarchy. Omit to leave the current parent untouched (a new node defaults to a root); `null` detaches to a root; an ID sets or changes the parent. Reparenting or detaching an existing node is leaf-only; place a parent before its children, or in the same batch. nullable: true usageLimit: type: number minimum: 0 description: >- Maximum usage allowed within one cadence window (required on create) nullable: true cadence: type: string maxLength: 255 pattern: ^(?:P[1-9]\d*[YMWD]|PT[1-9]\d*[HMS])$ description: >- Usage-reset cadence (required on create) as an ISO-8601 single-unit duration, e.g. `P1M`, `P30D`, `PT1M`. required: - entityId additionalProperties: false title: UpsertEntityEntitlement description: >- A single entity entitlement to create or update. Identify the feature or currency with exactly one of `featureId` or `currencyId`. The natural key is the `(entityId, featureId or currencyId, scopeEntityIds)` triple. On create both `usageLimit` and `cadence` are required; on update they may be omitted individually to preserve the existing value. minItems: 1 maxItems: 100 description: Entity entitlements to upsert (1–100 per request) required: - entityEntitlements additionalProperties: false title: UpsertEntityEntitlementsRequest description: >- Request body for creating or updating entity entitlements in bulk for a single customer UpsertEntityEntitlementsResponseDto: type: object properties: data: type: array items: type: object properties: id: type: string format: uuid description: >- Synthetic UUID identifier — also the cursor anchor for paginated lists entityId: type: string maxLength: 255 description: The entity ID this entity entitlement is attached to featureId: type: string maxLength: 255 description: >- Feature ID this entity entitlement grants (present when it grants a feature). currencyId: type: string maxLength: 255 description: >- Currency ID this entity entitlement grants (present when it grants a credit currency). scopeEntityIds: type: array items: type: string maxLength: 255 description: >- Dimension-scoped sub-limit key: the set of entity IDs this limit applies to. Empty is the node-wide limit that always matches; a non-empty set only applies when every listed entity is present in the resolved set (order-insensitive). description: >- Dimension-scoped sub-limit key: the set of entity IDs this limit applies to. Empty is the node-wide limit that always matches; a non-empty set only applies when every listed entity is present in the resolved set (order-insensitive). parentId: type: string maxLength: 255 description: Parent entity ID in the hierarchy, or `null` for a root. nullable: true usageLimit: type: number minimum: 0 description: Maximum usage allowed within one cadence window nullable: true cadence: type: string maxLength: 255 pattern: ^(?:P[1-9]\d*[YMWD]|PT[1-9]\d*[HMS])$ description: >- Usage-reset cadence as an ISO-8601 single-unit duration, e.g. `P1M`, `P30D`, `PT1M`. 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 required: - id - entityId - scopeEntityIds - parentId - usageLimit - cadence - createdAt - updatedAt title: EntityEntitlement description: >- An entity entitlement for an entity belonging to a customer. Defines how much of the feature or currency the entity may consume (`usageLimit`) and how often the counter resets (`cadence`). required: - data title: UpsertEntityEntitlementsResponse description: Entity entitlements after upsert. BadInputErrorResponseDto: type: object properties: message: type: string code: type: string enum: - BadUserInput - EnvironmentMismatch - BillingContractOperationRejected - 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 - CannotUpdateMeterOfFeatureInUse - CannotEditPackageInNonDraftMode - CannotAddOverrideEntitlementToPlan - MissingEntityIdError - NoProductsAvailable - PromotionCodeNotForCustomer - PromotionCodeNotActive - PromotionCodeMaxRedemptionsReached - PromotionCodeMinimumAmountNotReached - PromotionCodeCustomerNotFirstPurchase - AddonWithDraftCannotBeDeletedError - CannotReportUsageForEntitlementWithMeterError - RecalculateEntitlementsError - ImportSubscriptionsBulkError - InvalidMetadataError - CannotUpsertToPackageThatHasDraft - IntegrationValidationError - AwsMarketplaceIntegrationValidationError - AwsMarketplaceIntegrationError - DataExportIntegrationError - HubspotIntegrationError - DuplicateProductValidationError - AmountTooLarge - CustomerHasNoEmailAddress - MergeEnvironmentValidationError - 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 - FeatureNotEnabled - InvalidTaxId - ObjectAlreadyBeingUsedByAnotherRequestError - TooManySubscriptionsPerCustomer - TooManyCustomCurrencies - StripeError - SchedulingAtEndOfBillingPeriod - ApiKeyExpired - ApiKeyHasExpiry - OveragePriceNotSupportedOnAddon - OveragePriceRequiresUsageLimit - InvalidCreditOverageBillingModel - CreditOveragePriceCurrencyNotFound - InvoicePreviewNotAvailableForDraftContract nullable: true reason: type: string maxLength: 255 description: >- The billing side's machine-readable code for a billing-contract refusal. Present only when the code is BillingContractOperationRejected and the refusal carried one. 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 - EntitlementLimitExceededError - GovernanceNotEnabled nullable: true required: - message - code NotFoundErrorResponseDto: type: object properties: message: type: string code: type: string enum: - CustomerNotFound - CustomCurrencyNotFound - CreditGrantNotFound - ReservationNotFound - ContractNotFound - InvoiceNotFound - MemberNotFound - PackageGroupNotFound - AddonNotFound - AddonsNotFound - EnvironmentMissing - IntegrationNotFound - VendorIsNotSupported - CouponNotFound - FutureUpdateNotFound - CustomerNoBillingId - SubscriptionNoBillingId - StripeCustomerIsDeleted - InitStripePaymentMethodError - PreparePaymentMethodFormError - AccountNotFoundError - ExperimentNotFoundError - NoDraftOfferFound - PromotionCodeNotFound - FailedToCreateCheckoutSessionError - PaymentMethodNotFoundError - ProductNotFoundError - ProductNotPublishedError - MissingBillingInvoiceError - BillingInvoiceStatusError - FeatureGroupNotFoundError - CannotArchiveFeatureGroupError - OfferNotFound - CustomerResourceNotFound - FeatureNotFound - PriceNotFound - NoActiveSubscriptionForCustomer - PlanNotFound - PromotionalEntitlementNotFoundError - SubscriptionNotFound - ApiKeyNotFound 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 ```` ## Related topics - [Upsert entities](https://docs.stigg.io/api-reference/governance-entities/upsert-entities.md) - [Upsert entity types](https://docs.stigg.io/api-reference/governance-entity-types/upsert-entity-types.md) - [Get a list of entity entitlements](https://docs.stigg.io/api-reference/governance-entity-entitlements/get-a-list-of-entity-entitlements.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.