> ## 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 entities > Creates or updates entities in bulk for the given customer. Existing entities matched by id are updated; new ids are created. ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/stigg/openapi.documented.yml put /api/v1-beta/customers/{id}/entities openapi: 3.0.0 info: title: Stigg API description: Stigg API documentation version: 7.80.3 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-beta/customers/{id}/entities: put: tags: - Beta - Entities summary: Upsert entities description: >- Creates or updates entities in bulk for the given customer. Existing entities matched by id are updated; new ids are created. operationId: EntityController_upsertEntities parameters: - name: id required: true in: path description: The customer identifier (owner) the entities 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/UpsertEntitiesRequestDto' examples: default: value: entities: - id: user-7f3a0c1d typeRefId: user metadata: email: jane@acme.com role: admin - id: user-c4d1b2e9 typeRefId: user metadata: email: john@acme.com responses: '200': description: The list of upserted entity objects. content: application/json: schema: $ref: '#/components/schemas/UpsertEntitiesResponseDto' examples: default: value: data: - id: user-7f3a0c1d typeId: user metadata: email: jane@acme.com role: admin createdAt: '2026-05-18T00:00:00.000Z' updatedAt: '2026-05-18T00:00:00.000Z' archivedAt: null - id: user-c4d1b2e9 typeId: user metadata: email: john@acme.com createdAt: '2026-05-18T00:00:00.000Z' updatedAt: '2026-05-18T00:00:00.000Z' archivedAt: null '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: Entity not found. content: application/json: schema: $ref: '#/components/schemas/NotFoundErrorResponseDto' '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 response = await client.v1Beta.customers.entities.upsert('id', { entities: [ { id: 'user-7f3a0c1d', typeRefId: 'user', metadata: { email: 'jane@acme.com', role: 'admin' }, }, { id: 'user-c4d1b2e9', typeRefId: 'user', metadata: { email: 'john@acme.com' }, }, ], }); console.log(response.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 ) response = client.v1_beta.customers.entities.upsert( id="id", entities=[{ "id": "user-7f3a0c1d", "type_ref_id": "user", "metadata": { "email": "jane@acme.com", "role": "admin", }, }, { "id": "user-c4d1b2e9", "type_ref_id": "user", "metadata": { "email": "john@acme.com" }, }], ) print(response.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\tresponse, err := client.V1Beta.Customers.Entities.Upsert(\n\t\tcontext.TODO(),\n\t\t\"id\",\n\t\tstigg.V1BetaCustomerEntityUpsertParams{\n\t\t\tEntities: []stigg.V1BetaCustomerEntityUpsertParamsEntity{{\n\t\t\t\tID: \"user-7f3a0c1d\",\n\t\t\t\tTypeRefID: stigg.String(\"user\"),\n\t\t\t\tMetadata: map[string]string{\n\t\t\t\t\t\"email\": \"jane@acme.com\",\n\t\t\t\t\t\"role\": \"admin\",\n\t\t\t\t},\n\t\t\t}, {\n\t\t\t\tID: \"user-c4d1b2e9\",\n\t\t\t\tTypeRefID: stigg.String(\"user\"),\n\t\t\t\tMetadata: map[string]string{\n\t\t\t\t\t\"email\": \"john@acme.com\",\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\", response.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.v1beta.customers.entities.EntityUpsertParams; import io.stigg.models.v1beta.customers.entities.EntityUpsertResponse; public final class Main { private Main() {} public static void main(String[] args) { StiggClient client = StiggOkHttpClient.fromEnv(); EntityUpsertParams params = EntityUpsertParams.builder() .id("id") .addEntity(EntityUpsertParams.Entity.builder() .id("user-7f3a0c1d") .build()) .addEntity(EntityUpsertParams.Entity.builder() .id("user-c4d1b2e9") .build()) .build(); EntityUpsertResponse response = client.v1Beta().customers().entities().upsert(params); } } - lang: Ruby source: >- require "stigg" stigg = Stigg::Client.new(api_key: "My API Key") response = stigg.v1_beta.customers.entities.upsert("id", entities: [{id: "user-7f3a0c1d"}, {id: "user-c4d1b2e9"}]) puts(response) - lang: C# source: >- using System; using System.Collections.Generic; using Stigg.Client; using Stigg.Client.Models.V1Beta.Customers.Entities; StiggClient client = new(); EntityUpsertParams parameters = new() { ID = "id", Entities = [ new() { ID = "user-7f3a0c1d", Metadata = new Dictionary() { { "email", "jane@acme.com" }, { "role", "admin" } }, TypeRefID = "user", }, new() { ID = "user-c4d1b2e9", Metadata = new Dictionary() { { "email", "john@acme.com" } }, TypeRefID = "user", }, ], }; var response = await client.V1Beta.Customers.Entities.Upsert(parameters); Console.WriteLine(response); - lang: CLI source: |- stigg v1-beta:customers:entities upsert \ --api-key 'My API Key' \ --id id \ --entity '{id: user-7f3a0c1d}' \ --entity '{id: user-c4d1b2e9}' components: schemas: UpsertEntitiesRequestDto: type: object properties: entities: type: array items: 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 typeRefId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: >- The entity type refId this entity instantiates. Required when creating a new entity; on a re-upsert may be omitted to preserve the existing type. Governance returns 400 if missing on create. metadata: type: object additionalProperties: type: string description: >- Free-form key/value metadata. Patch semantics: empty-string value removes a key, omitted keys are preserved. required: - id additionalProperties: false title: UpsertEntity description: A single entity to create or update. minItems: 1 maxItems: 100 description: List of entities to create or update (1-100 entries) required: - entities additionalProperties: false title: UpsertEntitiesRequest description: >- Request body for creating or updating entities in bulk for a single customer UpsertEntitiesResponseDto: type: object properties: data: type: array items: 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 typeId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: The entity type identifier this entity instantiates metadata: type: object additionalProperties: type: string description: Free-form key/value metadata attached to 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 archivedAt: type: string format: date-time description: Timestamp of when the record was deleted nullable: true required: - id - typeId - metadata - createdAt - updatedAt - archivedAt title: Entity description: >- A stored entity instance tracked by the governance service for a given customer required: - data title: UpsertEntitiesResponse description: List of entities created or updated by an upsert request 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 nullable: true required: - message - code NotFoundErrorResponseDto: type: object properties: message: type: string code: type: string enum: - CustomerNotFound - CustomCurrencyNotFound - CreditGrantNotFound - 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 ````