> ## 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. # Update a subscription > Updates an active subscription's properties including billing period, add-ons, unit quantities, and discounts. This is a partial update — only the fields present in the request body change. Object fields such as `metadata` are replaced wholesale rather than merged, and list fields such as `addons` and `priceOverrides` must be sent in full: any existing item that isn't included in the array is removed from the subscription. Changes classified as a downgrade may be scheduled for the end of the current billing period instead of applying immediately, depending on your update scheduling configuration. ## OpenAPI ````yaml /openapi/stigg-api.documented.yml patch /api/v1/subscriptions/{id} openapi: 3.0.0 info: title: Stigg API description: Stigg API documentation version: 8.64.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/subscriptions/{id}: patch: tags: - Subscriptions summary: Update a subscription description: >- Updates an active subscription's properties including billing period, add-ons, unit quantities, and discounts. This is a partial update — only the fields present in the request body change. Object fields such as `metadata` are replaced wholesale rather than merged, and list fields such as `addons` and `priceOverrides` must be sent in full: any existing item that isn't included in the array is removed from the subscription. Changes classified as a downgrade may be scheduled for the end of the current billing period instead of applying immediately, depending on your update scheduling configuration. operationId: SubscriptionController_patchSubscription 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/PatchSubscriptionRequestDto' responses: '200': description: The updated subscription object. content: application/json: schema: $ref: '#/components/schemas/SubscriptionResponseDto' '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: Subscription 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 subscription = await client.v1.subscriptions.update('x'); console.log(subscription.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 ) subscription = client.v1.subscriptions.update( id="x", ) print(subscription.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\tsubscription, err := client.V1.Subscriptions.Update(\n\t\tcontext.TODO(),\n\t\t\"x\",\n\t\tstigg.V1SubscriptionUpdateParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", subscription.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.subscriptions.Subscription; import io.stigg.models.v1.subscriptions.SubscriptionUpdateParams; public final class Main { private Main() {} public static void main(String[] args) { StiggClient client = StiggOkHttpClient.fromEnv(); Subscription subscription = client.v1().subscriptions().update("x"); } } - lang: Ruby source: |- require "stigg" stigg = Stigg::Client.new(api_key: "My API Key") subscription = stigg.v1.subscriptions.update("x") puts(subscription) - lang: C# source: |- using System; using Stigg.Client; using Stigg.Client.Models.V1.Subscriptions; StiggClient client = new(); SubscriptionUpdateParams parameters = new() { ID = "x" }; var subscription = await client.V1.Subscriptions.Update(parameters); Console.WriteLine(subscription); - lang: CLI source: |- stigg v1:subscriptions update \ --api-key 'My API Key' \ --id x components: schemas: PatchSubscriptionRequestDto: type: object properties: metadata: type: object additionalProperties: type: string description: >- Additional metadata for the subscription, stored as an arbitrary flat key-value object. charges: type: array items: type: object properties: type: type: string enum: - FEATURE - CREDIT id: type: string maxLength: 255 description: Charge ID quantity: type: number minimum: 0 required: - type - id - quantity addons: type: array items: type: object properties: id: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Addon ID quantity: type: integer minimum: 0 description: Number of addon instances required: - id - quantity title: SubscriptionAddon description: Addon configuration trialEndDate: type: string format: date-time description: Subscription trial end date promotionCode: type: string maxLength: 255 description: Promotion code entitlements: type: array items: discriminator: propertyName: type oneOf: - type: object properties: type: type: string enum: - FEATURE description: SubscriptionFeatureEntitlementRequest id: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: The feature ID to attach the entitlement to usageLimit: type: integer minimum: 0 description: Maximum allowed usage for the feature hasUnlimitedUsage: type: boolean description: Whether usage is unlimited hasSoftLimit: type: boolean description: Whether the usage limit is a soft limit resetPeriod: type: string enum: - YEAR - MONTH - WEEK - DAY - HOUR description: Period at which usage resets yearlyResetPeriodConfiguration: type: object properties: accordingTo: type: string enum: - SubscriptionStart description: Reset anchor (SubscriptionStart) required: - accordingTo title: YearlyResetPeriodConfig description: Configuration for yearly reset period nullable: true monthlyResetPeriodConfiguration: type: object properties: accordingTo: type: string enum: - SubscriptionStart - StartOfTheMonth description: Reset anchor (SubscriptionStart or StartOfTheMonth) required: - accordingTo title: MonthlyResetPeriodConfig description: Configuration for monthly reset period 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: Configuration for weekly reset period nullable: true required: - type - id title: SubscriptionFeatureEntitlementRequest description: Feature entitlement configuration for a subscription - type: object properties: type: type: string enum: - CREDIT description: SubscriptionCreditEntitlementRequest id: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: The custom currency ID for the credit entitlement amount: type: number minimum: 0 description: Credit grant amount cadence: type: string enum: - MONTH - YEAR description: Credit grant cadence (MONTH or YEAR) hasSoftLimit: type: boolean description: Whether the credit balance is a soft limit required: - type - id - amount - cadence title: SubscriptionCreditEntitlementRequest description: Credit entitlement configuration for a subscription billingPeriod: type: string enum: - MONTHLY - ANNUALLY awaitPaymentConfirmation: type: boolean description: Await payment confirmation billingInformation: type: object properties: taxRateIds: type: array items: type: string couponId: type: string taxPercentage: type: number minimum: 0 maximum: 100 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 metadata: type: object additionalProperties: type: string description: >- Additional metadata for the subscription, stored as an arbitrary flat key-value object. chargeOnBehalfOfAccount: type: string isBackdated: type: boolean isInvoicePaid: type: boolean invoiceDaysUntilDue: type: number integrationId: type: string prorationBehavior: type: string enum: - INVOICE_IMMEDIATELY - CREATE_PRORATIONS - NONE taxIds: type: array items: type: object properties: type: type: string value: type: string required: - type - value scheduleStrategy: type: string enum: - END_OF_BILLING_PERIOD - END_OF_BILLING_MONTH - IMMEDIATE budget: type: object properties: limit: type: number description: Maximum spending limit hasSoftLimit: type: boolean description: Whether the budget is a soft limit required: - limit - hasSoftLimit additionalProperties: false nullable: true minimumSpend: type: object properties: amount: type: number description: The price amount currency: description: The price 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 title: Currency description: Minimum spend amount nullable: true priceOverrides: type: array items: type: object properties: amount: type: number description: The price amount currency: description: The price 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 title: Currency featureId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Feature ID currencyId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: >- The corresponding custom currency id of the recurring credits price addonId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Addon ID baseCharge: type: boolean description: Whether this is a base charge override appliedCoupon: type: object properties: couponId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Stigg coupon ID billingCouponId: type: string promotionCode: type: string nullable: true discount: type: object properties: name: type: string description: type: string durationInMonths: type: number minimum: 1 percentOff: type: number minimum: 1 maximum: 100 amountsOff: type: array items: type: object properties: amount: type: number description: The price amount currency: description: ISO 4217 currency code 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 required: - amount - currency title: Money description: Monetary amount with currency nullable: true configuration: type: object properties: startDate: type: string format: date-time description: Coupon start date billingCycleAnchor: type: string enum: - UNCHANGED - NOW cancellationDate: type: string format: date-time description: Subscription cancellation date nullable: true salesforceId: type: string maxLength: 255 description: Salesforce ID nullable: true additionalProperties: false title: PatchSubscriptionRequest description: >- Partially updates an existing subscription — only the fields included in the request body are changed; any field left out keeps its current value. Object fields such as `metadata` are replaced wholesale rather than merged key by key, so a request that includes `metadata` must repeat any existing keys it's supposed to keep (to clear metadata entirely, send `metadata: {}`). List fields such as `addons`, `priceOverrides`, and `entitlements` work the same way: the array you send becomes the field's complete new value, so an existing addon or entitlement that isn't included in the array is removed from the subscription, not left untouched. SubscriptionResponseDto: type: object properties: data: type: object properties: id: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Subscription ID customerId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$ description: Customer ID payingCustomerId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.@-]*$ description: Paying customer ID for delegated billing nullable: true resourceId: type: string maxLength: 255 description: Resource ID nullable: true billingId: type: string maxLength: 255 description: Billing ID nullable: true contractId: type: string maxLength: 255 description: The Stigg contract this subscription is linked to, when any nullable: true createdAt: type: string format: date-time description: Created at startDate: type: string format: date-time description: Subscription start date endDate: type: string format: date-time description: Subscription end date nullable: true effectiveEndDate: type: string format: date-time description: Subscription effective end date nullable: true cancellationDate: type: string format: date-time description: Subscription cancellation date nullable: true trialEndDate: type: string format: date-time description: Subscription trial end date nullable: true status: type: string enum: - PAYMENT_PENDING - ACTIVE - EXPIRED - IN_TRIAL - CANCELED - NOT_STARTED description: Subscription status cancelReason: type: string enum: - UPGRADE_OR_DOWNGRADE - CANCELLED_BY_BILLING - EXPIRED - DETACH_BILLING - TRIAL_ENDED - Immediate - TRIAL_CONVERTED - PENDING_PAYMENT_EXPIRED - ScheduledCancellation - CustomerArchived - AutoCancellationRule description: Subscription cancel reason nullable: true metadata: type: object additionalProperties: type: string description: >- Additional metadata for the subscription, stored as an arbitrary flat key-value object. currentBillingPeriodStart: type: string format: date-time description: Start of the current billing period nullable: true currentBillingPeriodEnd: type: string format: date-time description: End of the current billing period nullable: true pricingType: type: string enum: - FREE - PAID - CUSTOM description: Pricing type paymentCollection: type: string enum: - NOT_REQUIRED - PROCESSING - FAILED - ACTION_REQUIRED description: Payment collection paymentCollectionMethod: type: string enum: - CHARGE - INVOICE - NONE description: The method used to collect payments for a subscription nullable: true billingCycleAnchor: type: string format: date-time description: Billing cycle anchor date nullable: true planId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Plan ID prices: default: [] type: array items: type: object properties: amount: type: number description: The price amount currency: description: The price 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 title: Currency featureId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Feature identifier for the price override nullable: true addonId: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Addon identifier for the price override nullable: true baseCharge: type: boolean description: Whether this is a base charge override billingCountryCode: type: string maxLength: 255 description: >- ISO 3166-1 alpha-2 country code this price applies to, or "eu" for the European Union group you map countries into. Omit for the default price shown to all countries; set one or more country-specific price periods on the same currency to localize the amount by billing country. blockSize: type: number description: Block size for pricing tiers: type: array items: type: object properties: upTo: type: number description: The up to quantity of the price tier unitPrice: type: object properties: amount: type: number description: The price amount currency: description: ISO 4217 currency code 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 required: - amount - currency title: Money description: The unit price of the price tier flatPrice: type: object properties: amount: type: number description: The price amount currency: description: ISO 4217 currency code 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 required: - amount - currency title: Money description: The flat fee price of the price tier additionalProperties: false description: Pricing tiers configuration addons: default: [] type: array items: type: object properties: id: type: string maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9][a-zA-Z0-9_|.-]*$ description: Addon ID quantity: type: integer minimum: 0 description: Number of addon instances required: - id - quantity title: SubscriptionAddon description: Addon configuration coupons: default: [] type: array items: type: object properties: id: type: string maxLength: 255 description: Coupon ID name: type: string maxLength: 255 description: Coupon name status: type: string enum: - ACTIVE - EXPIRED - REMOVED description: Coupon status percentOff: type: number description: Percentage discount nullable: true amountsOff: type: array items: type: object properties: amount: type: number description: The price amount currency: description: The price 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 title: Currency nullable: true description: Fixed amount discounts by currency required: - id - name - status title: SubscriptionCouponResponse description: Coupon applied to a subscription description: Coupons applied to the subscription futureUpdates: default: [] type: array items: type: object properties: scheduledExecutionTime: type: string format: date-time description: Scheduled execution time subscriptionScheduleType: type: string enum: - DOWNGRADE - PLAN - BILLING_PERIOD - UNIT_AMOUNT - RECURRING_CREDITS - PRICE_OVERRIDE - ADDON - COUPON - MIGRATE_TO_LATEST - ADDITIONAL_META_DATA - BILLING_INFO_METADATA description: Type of scheduled change scheduleStatus: type: string enum: - PENDING_PAYMENT - SCHEDULED - CANCELED - DONE - FAILED description: Status of the scheduled update targetPackage: type: object properties: id: type: string maxLength: 255 description: Target package for the update required: - id nullable: true description: Target package for the update required: - scheduledExecutionTime - subscriptionScheduleType - scheduleStatus title: FutureUpdate description: Scheduled subscription update description: Scheduled future updates for the subscription budget: type: object properties: limit: type: number description: Maximum spending limit hasSoftLimit: type: boolean description: Whether the budget is a soft limit required: - limit - hasSoftLimit additionalProperties: false nullable: true description: Budget configuration minimumSpend: type: object properties: amount: type: number description: The price amount currency: description: The price 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 title: Currency description: Minimum spend configuration nullable: true subscriptionEntitlements: default: [] type: array items: type: object properties: type: type: string enum: - FEATURE - CREDIT description: Entitlement type (FEATURE or CREDIT) id: type: string maxLength: 255 description: Feature ID or currency ID required: - type - id title: SubscriptionEntitlementItem description: Subscription entitlement reference description: Entitlements associated with the subscription latestInvoice: type: object properties: billingId: type: string maxLength: 255 description: Invoice billing ID status: type: string enum: - OPEN - CANCELED - PAID description: Invoice status createdAt: type: string format: date-time description: Invoice creation date total: type: number description: Total amount nullable: true amountDue: type: number description: Amount due nullable: true currency: type: string maxLength: 255 description: Invoice currency nullable: true pdfUrl: type: string maxLength: 255 description: Invoice PDF URL nullable: true requiresAction: type: boolean description: Whether payment requires action billingReason: type: string enum: - BILLING_CYCLE - SUBSCRIPTION_CREATION - SUBSCRIPTION_UPDATE - MANUAL - MINIMUM_INVOICE_AMOUNT_EXCEEDED - OTHER nullable: true description: Billing reason required: - billingId - status - createdAt - requiresAction title: LatestInvoice description: Latest invoice for the subscription nullable: true trial: type: object properties: trialEndBehavior: type: string enum: - CONVERT_TO_PAID - CANCEL_SUBSCRIPTION description: Behavior when the trial ends required: - trialEndBehavior title: Trial description: Trial configuration nullable: true required: - id - customerId - billingId - createdAt - startDate - status - pricingType - paymentCollection - planId title: Subscription description: Customer subscription to a plan required: - data title: Response description: Response object 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 - 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 - 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 - GovernanceNotEnabled nullable: true required: - message - code NotFoundErrorResponseDto: type: object properties: message: type: string code: type: string enum: - CustomerNotFound - CustomCurrencyNotFound - CreditGrantNotFound - 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 - [Updating subscriptions](/documentation/managing-customers-and-subscriptions/subscriptions/updating-subscriptions.md) - [Subscription management](/api-and-sdks/integration/backend/subscriptions.md) - [Updates to subscriptions with usage-based pricing](/documentation/managing-customers-and-subscriptions/subscription-updates/updates-subscriptions-usage-based.md) - [Scheduled updates](/documentation/managing-customers-and-subscriptions/subscription-updates/scheduled-updates.md) - [Update a product](/api-reference/products/update-a-product.md)