> ## 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 Customer > Creates a new customer and optionally provisions an initial subscription in a single operation. ## OpenAPI ````yaml POST /api/v1/customers 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/customers: post: tags: - Customers summary: Provision customer description: >- Creates a new customer and optionally provisions an initial subscription in a single operation. operationId: CustomerController_provisionCustomer 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/ProvisionCustomerRequestDto' responses: '201': description: The newly created customer object. content: application/json: schema: $ref: '#/components/schemas/CustomerResponseDto' examples: default: value: data: createdAt: '2025-10-26T10:00:00.000Z' updatedAt: '2025-10-26T10:00:00.000Z' archivedAt: null name: John Doe email: john@example.com billingId: cus_MIhJJFnJL24HFH id: customer-6e24b4 billingCurrency: usd metadata: {} integrations: [] defaultPaymentMethod: type: CARD billingId: pm_1Q0PsIJvEtkwdCNYMSaVuRz6 cardLast4Digits: '1234' cardExpiryMonth: 12 cardExpiryYear: 2025 couponId: coupon-6e24b4 timezone: null language: en passthrough: stripe: invoiceCustomFields: {} zuora: {} '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: Customer 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 customerResponse = await client.v1.customers.provision({ id: 'id' }); console.log(customerResponse.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 ) customer_response = client.v1.customers.provision( id="id", ) print(customer_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\tcustomerResponse, err := client.V1.Customers.Provision(context.TODO(), stigg.V1CustomerProvisionParams{\n\t\tID: \"id\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", customerResponse.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.CustomerProvisionParams; import io.stigg.models.v1.customers.CustomerResponse; public final class Main { private Main() {} public static void main(String[] args) { StiggClient client = StiggOkHttpClient.fromEnv(); CustomerProvisionParams params = CustomerProvisionParams.builder() .id("id") .build(); CustomerResponse customerResponse = client.v1().customers().provision(params); } } - lang: Ruby source: |- require "stigg" stigg = Stigg::Client.new(api_key: "My API Key") customer_response = stigg.v1.customers.provision(id: "id") puts(customer_response) - lang: C# source: >- using System; using Stigg.Client; using Stigg.Client.Models.V1.Customers; StiggClient client = new(); CustomerProvisionParams parameters = new() { ID = "id" }; var customerResponse = await client.V1.Customers.Provision(parameters); Console.WriteLine(customerResponse); - lang: CLI source: |- stigg v1:customers provision \ --api-key 'My API Key' \ --id id components: schemas: ProvisionCustomerRequestDto: type: object properties: name: type: string maxLength: 255 description: The name of the customer nullable: true email: type: string format: email maxLength: 255 description: The email of the customer nullable: true billingId: type: string maxLength: 255 description: The unique identifier for the entity in the billing provider nullable: true id: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$ description: Customer slug billingCurrency: type: string enum: - usd - aed - all - amd - ang - aud - awg - azn - bam - bbd - bdt - bgn - bif - bmd - bnd - bsd - bwp - byn - bzd - brl - cad - cdf - chf - cny - czk - dkk - dop - dzd - egp - etb - eur - fjd - gbp - gel - gip - gmd - gyd - hkd - hrk - htg - idr - ils - inr - isk - jmd - jpy - kes - kgs - khr - kmf - krw - kyd - kzt - lbp - lkr - lrd - lsl - mad - mdl - mga - mkd - mmk - mnt - mop - mro - mvr - mwk - mxn - myr - mzn - nad - ngn - nok - npr - nzd - pgk - php - pkr - pln - qar - ron - rsd - rub - rwf - sar - sbd - scr - sek - sgd - sle - sll - sos - szl - thb - tjs - top - try - ttd - tzs - uah - uzs - vnd - vuv - wst - xaf - xcd - yer - zar - zmw - clp - djf - gnf - ugx - pyg - xof - xpf title: Currency description: The billing currency of the customer nullable: true metadata: type: object additionalProperties: type: string description: Additional metadata integrations: type: array items: type: object properties: vendorIdentifier: type: string enum: - AUTH0 - ZUORA - STRIPE - HUBSPOT - AWS_MARKETPLACE - SNOWFLAKE - SALESFORCE - BIG_QUERY - OPEN_FGA - APP_STORE - RECEIVED - PREQUEL - AIRWALLEX description: The vendor identifier of integration syncedEntityId: type: string maxLength: 255 description: Synced entity id nullable: true id: type: string maxLength: 255 description: Integration details required: - vendorIdentifier - syncedEntityId - id title: CustomerIntegration description: External billing or CRM integration link description: List of integrations defaultPaymentMethod: type: object properties: billingId: type: string maxLength: 255 description: The default payment method id nullable: true type: type: string enum: - CARD - BANK - CASH_APP description: The default payment method type cardLast4Digits: type: string maxLength: 255 description: The last 4 digits of the default payment method nullable: true cardExpiryMonth: type: number description: The expiration month of the default payment method nullable: true cardExpiryYear: type: number description: The expiration year of the default payment method nullable: true required: - billingId - type - cardLast4Digits - cardExpiryMonth - cardExpiryYear title: PaymentMethod description: The default payment method details nullable: true couponId: oneOf: - type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Customer level coupon - type: string enum: - '' description: Customer level coupon nullable: true timezone: type: string maxLength: 255 description: Timezone to use for this customer nullable: true language: type: string maxLength: 255 description: Language to use for this customer nullable: true passthrough: type: object properties: stripe: type: object properties: customerName: type: string maxLength: 255 description: Customer name billingAddress: type: object properties: city: type: string description: City name country: type: string description: Country code or name line1: type: string description: Street address line 1 line2: type: string description: Street address line 2 postalCode: type: string description: Postal or ZIP code state: type: string description: State or province additionalProperties: false title: Address description: Physical address shippingAddress: type: object properties: city: type: string description: City name country: type: string description: Country code or name line1: type: string description: Street address line 1 line2: type: string description: Street address line 2 postalCode: type: string description: Postal or ZIP code state: type: string description: State or province additionalProperties: false title: Address description: Physical address paymentMethodId: type: string maxLength: 255 description: >- Billing provider payment method id, attached to this customer taxIds: type: array items: type: object properties: type: type: string maxLength: 255 description: The type of tax exemption identifier, such as VAT. value: type: string maxLength: 255 description: The actual tax identifier value required: - type - value additionalProperties: false title: TaxExemptInput description: >- Tax identifier with type and value for customer tax exemptions. description: Tax IDs invoiceCustomFields: type: object additionalProperties: type: string description: Invoice custom fields metadata: type: object additionalProperties: type: string description: Additional metadata additionalProperties: false title: StripeCustomerPassthrough description: Stripe-specific billing fields for the customer. zuora: type: object properties: billingAddress: type: object properties: city: type: string description: City name country: type: string description: Country code or name line1: type: string description: Street address line 1 line2: type: string description: Street address line 2 postalCode: type: string description: Postal or ZIP code state: type: string description: State or province additionalProperties: false title: Address description: Physical address currency: type: string enum: - usd - aed - all - amd - ang - aud - awg - azn - bam - bbd - bdt - bgn - bif - bmd - bnd - bsd - bwp - byn - bzd - brl - cad - cdf - chf - cny - czk - dkk - dop - dzd - egp - etb - eur - fjd - gbp - gel - gip - gmd - gyd - hkd - hrk - htg - idr - ils - inr - isk - jmd - jpy - kes - kgs - khr - kmf - krw - kyd - kzt - lbp - lkr - lrd - lsl - mad - mdl - mga - mkd - mmk - mnt - mop - mro - mvr - mwk - mxn - myr - mzn - nad - ngn - nok - npr - nzd - pgk - php - pkr - pln - qar - ron - rsd - rub - rwf - sar - sbd - scr - sek - sgd - sle - sll - sos - szl - thb - tjs - top - try - ttd - tzs - uah - uzs - vnd - vuv - wst - xaf - xcd - yer - zar - zmw - clp - djf - gnf - ugx - pyg - xof - xpf description: Customers selected currency paymentMethodId: type: string maxLength: 255 description: >- Billing provider payment method id, attached to this customer metadata: type: object additionalProperties: type: string description: Additional metadata additionalProperties: false title: ZuoraCustomerPassthrough description: Zuora-specific billing fields for the customer. additionalProperties: false title: CustomerPassthrough description: Vendor-specific billing passthrough fields. required: - id additionalProperties: false title: ProvisionCustomerRequest description: Provisions a new customer with unique ID, optional name and email. CustomerResponseDto: type: object properties: data: type: object properties: 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 name: type: string maxLength: 255 description: The name of the customer nullable: true email: type: string format: email maxLength: 255 description: The email of the customer nullable: true billingId: type: string maxLength: 255 description: The unique identifier for the entity in the billing provider nullable: true id: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$ description: Customer slug billingCurrency: type: string enum: - usd - aed - all - amd - ang - aud - awg - azn - bam - bbd - bdt - bgn - bif - bmd - bnd - bsd - bwp - byn - bzd - brl - cad - cdf - chf - cny - czk - dkk - dop - dzd - egp - etb - eur - fjd - gbp - gel - gip - gmd - gyd - hkd - hrk - htg - idr - ils - inr - isk - jmd - jpy - kes - kgs - khr - kmf - krw - kyd - kzt - lbp - lkr - lrd - lsl - mad - mdl - mga - mkd - mmk - mnt - mop - mro - mvr - mwk - mxn - myr - mzn - nad - ngn - nok - npr - nzd - pgk - php - pkr - pln - qar - ron - rsd - rub - rwf - sar - sbd - scr - sek - sgd - sle - sll - sos - szl - thb - tjs - top - try - ttd - tzs - uah - uzs - vnd - vuv - wst - xaf - xcd - yer - zar - zmw - clp - djf - gnf - ugx - pyg - xof - xpf title: Currency description: The billing currency of the customer nullable: true metadata: type: object additionalProperties: type: string description: Additional metadata integrations: type: array items: type: object properties: vendorIdentifier: type: string enum: - AUTH0 - ZUORA - STRIPE - HUBSPOT - AWS_MARKETPLACE - SNOWFLAKE - SALESFORCE - BIG_QUERY - OPEN_FGA - APP_STORE - RECEIVED - PREQUEL - AIRWALLEX description: The vendor identifier of integration syncedEntityId: type: string maxLength: 255 description: Synced entity id nullable: true id: type: string maxLength: 255 description: Integration details required: - vendorIdentifier - syncedEntityId - id title: CustomerIntegration description: External billing or CRM integration link description: List of integrations defaultPaymentMethod: type: object properties: billingId: type: string maxLength: 255 description: The default payment method id nullable: true type: type: string enum: - CARD - BANK - CASH_APP description: The default payment method type cardLast4Digits: type: string maxLength: 255 description: The last 4 digits of the default payment method nullable: true cardExpiryMonth: type: number description: The expiration month of the default payment method nullable: true cardExpiryYear: type: number description: The expiration year of the default payment method nullable: true required: - billingId - type - cardLast4Digits - cardExpiryMonth - cardExpiryYear title: PaymentMethod description: The default payment method details nullable: true couponId: oneOf: - type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Customer level coupon - type: string enum: - '' description: Customer level coupon nullable: true timezone: type: string maxLength: 255 description: Timezone to use for this customer nullable: true language: type: string maxLength: 255 description: Language to use for this customer nullable: true passthrough: type: object properties: stripe: type: object properties: customerName: type: string maxLength: 255 description: Customer name billingAddress: type: object properties: city: type: string description: City name country: type: string description: Country code or name line1: type: string description: Street address line 1 line2: type: string description: Street address line 2 postalCode: type: string description: Postal or ZIP code state: type: string description: State or province additionalProperties: false title: Address description: Physical address shippingAddress: type: object properties: city: type: string description: City name country: type: string description: Country code or name line1: type: string description: Street address line 1 line2: type: string description: Street address line 2 postalCode: type: string description: Postal or ZIP code state: type: string description: State or province additionalProperties: false title: Address description: Physical address paymentMethodId: type: string maxLength: 255 description: >- Billing provider payment method id, attached to this customer taxIds: type: array items: type: object properties: type: type: string maxLength: 255 description: The type of tax exemption identifier, such as VAT. value: type: string maxLength: 255 description: The actual tax identifier value required: - type - value additionalProperties: false title: TaxExemptInput description: >- Tax identifier with type and value for customer tax exemptions. description: Tax IDs invoiceCustomFields: type: object additionalProperties: type: string description: Invoice custom fields metadata: type: object additionalProperties: type: string description: Additional metadata additionalProperties: false title: StripeCustomerPassthrough description: Stripe-specific billing fields for the customer. zuora: type: object properties: billingAddress: type: object properties: city: type: string description: City name country: type: string description: Country code or name line1: type: string description: Street address line 1 line2: type: string description: Street address line 2 postalCode: type: string description: Postal or ZIP code state: type: string description: State or province additionalProperties: false title: Address description: Physical address currency: type: string enum: - usd - aed - all - amd - ang - aud - awg - azn - bam - bbd - bdt - bgn - bif - bmd - bnd - bsd - bwp - byn - bzd - brl - cad - cdf - chf - cny - czk - dkk - dop - dzd - egp - etb - eur - fjd - gbp - gel - gip - gmd - gyd - hkd - hrk - htg - idr - ils - inr - isk - jmd - jpy - kes - kgs - khr - kmf - krw - kyd - kzt - lbp - lkr - lrd - lsl - mad - mdl - mga - mkd - mmk - mnt - mop - mro - mvr - mwk - mxn - myr - mzn - nad - ngn - nok - npr - nzd - pgk - php - pkr - pln - qar - ron - rsd - rub - rwf - sar - sbd - scr - sek - sgd - sle - sll - sos - szl - thb - tjs - top - try - ttd - tzs - uah - uzs - vnd - vuv - wst - xaf - xcd - yer - zar - zmw - clp - djf - gnf - ugx - pyg - xof - xpf description: Customers selected currency paymentMethodId: type: string maxLength: 255 description: >- Billing provider payment method id, attached to this customer metadata: type: object additionalProperties: type: string description: Additional metadata additionalProperties: false title: ZuoraCustomerPassthrough description: Zuora-specific billing fields for the customer. additionalProperties: false title: CustomerPassthrough description: Vendor-specific billing passthrough fields. required: - createdAt - updatedAt - archivedAt - id title: Customer description: A customer can be either an organization or an individual 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 ````