# Set whether a commitment renews `PUT /apis/cra.diagrid.io/v1beta1/billing/subscription/commitments/{CommitmentId}/auto-renew` Turn auto-renew on or off for one of the organization's prepaid annual commitments. Turning it off does not end coverage: the commitment runs to the end of its current term and lapses there, after which the regions it covers are billed monthly from the next billing period. Turning it on again before the term ends resumes renewal. Returns the updated billing subscription. ## Request ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `CommitmentId` | string | Yes | The prepaid annual commitment's identifier, as listed in the billing subscription's spec.commitments[].id. | ### Request body Required. `application/json` Whether a prepaid annual commitment renews at the end of its term. - `autoRenew` (boolean) — Required. True to renew the commitment for another term when the current one ends; false to let it lapse at the end of the current term. ## Responses ### 200 — [OK](https://jsonapi.org/format/#crud-updating-responses-200) `application/json` - `apiVersion` (string) - `kind` (string) - `metadata` (object) - `name` (string) - `uid` (string) - `resourceVersion` (integer) - `createdAt` (string) - `updatedAt` (string) - `deletedAt` (string) - `labels` (object) - `annotations` (object) - `spec` (object) — Required. BillingSubscriptionSpec is the desired, user-independent configuration of the subscription: which rail settles it, the billing cadence, and where the payment-method precondition is enforced. The line items are derived from the org's config (Status.Items), not authored here. - `rail` (string) — Required. Rail is the settlement rail the subscription is billed through: card, for self-serve billing against the org's vaulted card, or cloud_marketplace, for billing through the cloud provider's marketplace. One of: `card`, `cloud_marketplace`. - `commitment` (string) — Required. Commitment is the billing cadence, and it is always monthly. Annual capacity is bought as prepaid lots in Commitments, never as a cadence on the subscription itself. One of: `monthly`. - `paymentPolicy` (string) — Required. PaymentPolicy selects where the payment-method precondition sits: upfront (gates region create -> trialing) or after_trial (gates trialing -> active). One of: `upfront`, `after_trial`. - `entitlements` (object[]) — Entitlements are an admin-authored allowance: up to Quantity chargeable resources of a given (Kind, Descriptor) are discounted by DiscountPercent (100 = fully comped), oldest-provisioned-first, independent of Spec.Rail. It is the mechanism for a sales-negotiated deal (e.g. "org already paid externally for 2 dedicated_region at large/premium") to be represented, enforced, and observed on the subscription without a Stripe charge for the covered portion. Usage beyond the ceiling ("overage") is priced and gated normally: it requires a valid default payment method to create (regardless of PaymentPolicy) and, once billed, is subject to the ordinary dunning lifecycle — entitled (covered) resources are never blocked, suspended, or torn down by non-payment of the overage. Nil/empty means no ceiling: every subscription without Entitlements is completely unaffected (backward compatible with every card/cloud_marketplace subscription that predates this field). - `kind` (string) — Required. Kind is the chargeable kind this entitlement covers: dedicated_region, byoc_dedicated_region or private_region. - `descriptor` (string) — Descriptor is the variant within Kind. For a region kind it is "/" (e.g. "large/premium") — the size and the support plan purchased with the region together select a single price, so an entitlement comps a region AT a support level rather than the two separately. Must match a descriptor the price catalog actually prices; a row that matches nothing is rejected. - `quantity` (integer) — Required. Quantity is the number of matching resources this entitlement covers. Oldest-provisioned-first: the first Quantity live (Kind,Descriptor) resources (by createdAt) are covered; any beyond it are overage. - `discountPercent` (integer) — DiscountPercent (0-100) is applied to each covered item's catalog price; 100 means fully comped (AmountCents == 0 for that item). - `commitments` (object[]) — Commitments are the org's prepaid capacity lots: up to Quantity live regions matching (Kind, Descriptor) are fully covered for the term. Commitments are not Entitlements: an entitlement is a comp for a deal paid for elsewhere, with no term and no charge; a commitment is termed, renewing, and Diagrid took money for it, on either Rail. - `id` (string) — Required. ID is the stable lot identifier, server-generated. Status rows and renewal notices key off it. - `kind` (string) — Required. Kind / Descriptor are the covered chargeable, in the same vocabulary an entitlement is authored against — for a region kind the compound "/". - `descriptor` (string) — Required. - `quantity` (integer) — Required. Quantity is how many matching regions this lot covers. Today it is always 1: a lot is created only by a self-serve purchase at region create, which buys one region's worth of capacity. It counts REGIONS, never dollars — the unit count a metered prepay was settled at is a settlement detail, in Status. - `termStart` (string) — TermStart / TermEnd bound coverage. TermStart is the purchase instant, or trial end when bought while trialing, on either rail. - `termEnd` (string) - `boughtTermEnd` (string) — BoughtTermEnd is the term end the customer originally bought, and it is present ONLY where the term was CUT SHORT. Its presence is the signal: it means "this term was ended early, and this is where it was going to end", so the months between it and TermEnd are what the customer lost. A healthy lot does not carry it, because TermEnd already IS what was bought. Read status.commitments[].lapseCause for why the term was cut short. - `autoRenew` (boolean) — AutoRenew defaults true: at term end the lot renews for another term and is charged for again. - `status` (object) — BillingSubscriptionStatus is the server-owned lifecycle state exposed to the UI: the phase, the Diagrid-owned trial clock, the derived items and total, and the rail-scoped settlement references. - `status` (string) — Status is the current processing status of the resource. - `updatedAt` (string) — UpdatedAt is the time of the last status update. - `messages` (object[]) — Messages contains any status messages, such as error details. - `message` (string) - `phase` (string) — Phase is the lifecycle state. One of: `pending_payment_method`, `trialing`, `active`, `past_due`, `suspended`, `canceled`. - `trialStartedAt` (string) — TrialStartedAt / TrialEndsAt are the Diagrid-owned trial clock; TrialEndsAt is the moment charging begins (anchoring region createdAt + trial duration). - `trialEndsAt` (string) - `graceEndsAt` (string) — GraceEndsAt is the deadline by which the org must fix payment before its regions are removed; set while in pending_payment_method / past_due / suspended, absent otherwise. The billing UI renders a countdown against it. - `cancelAtPeriodEnd` (boolean) — CancelAtPeriodEnd reports a cancellation that is scheduled but has not taken effect yet: the regions the subscription bills for keep running until the end of the period that has been paid for, and the items and amount below are still being charged for that remainder. Read it together with paidThroughAt, which is the date the cancellation takes effect. It does not imply any particular phase — a cancellation can be scheduled while the phase is still active — so a pending cancellation must be read from this field rather than inferred from phase. - `paidThroughAt` (string) — PaidThroughAt is the end of the billing period already paid for. While cancelAtPeriodEnd is set it is the date the cancellation takes effect and the regions are removed; it is also the date a new subscription created before then starts billing from, so a period already paid for is never charged twice. - `items` (object[]) — Items are the kind-agnostic line items derived from the org's chargeable configuration. Today only dedicated_region items are emitted. - `kind` (string) — Kind is the chargeable kind (e.g. dedicated_region; future: seat, addon...). - `refId` (string) — RefID is the charged thing's id (e.g. the region id). - `descriptor` (string) — Descriptor is the variant within the kind. For a region kind it is "/" (e.g. "large/premium") — the size and the support plan purchased with the region together select a single price. - `product` (string) — Product is the user-facing product bucket this line item bills for, derived from Kind: "dedicated_cloud" for a Diagrid-hosted dedicated region, and "byoc" for a bring-your-own-cloud dedicated region or a private region (both run on the customer's own infrastructure). It lets clients group and label line items by product without knowing the finer-grained kinds. One of: `dedicated_cloud`, `byoc`. - `quantity` (integer) — Quantity is the number of units billed for this item; today always 1. - `priceId` (string) — PriceID is the concrete Stripe Price billed for this item. - `amountCents` (integer) — AmountCents is the amount billed for this item, after DiscountPercent. - `salesLed` (boolean) — SalesLed reports whether this line is excluded from self-serve card settlement: true means it must never be sent to the card rail for charging, even if the org has a valid default payment method for its other (self-serve) lines. It is derived from this line's own Kind — every line bills a region, so there is no line whose sales-led status is inherited from another. - `discountPercent` (integer) — DiscountPercent (0-100) is the entitlement discount applied to this item's catalog price (see Spec.Entitlements), 0 meaning none and 100 meaning fully comped. AmountCents already reflects it (display/audit); this is what the settlement rail reads to make the ACTUAL charge match: PriceID always stays the full, undiscounted catalog Price — a rail must itself apply the discount (e.g. a per-item Stripe coupon) or omit a fully comped item entirely, or the customer is billed in full regardless of AmountCents. - `coveredByCommitmentId` (string) — CoveredByCommitmentID / CoveredUntil say which prepaid annual commitment is covering this line, and until when. Both are absent on a line that is covered by something other than a commitment, or not covered at all. Which line a commitment covers can change as regions come and go, so read these off the current subscription rather than remembering them. - `coveredUntil` (string) - `amountCents` (integer) — AmountCents is the display/audit total; == sum of Items[i].AmountCents. - `currency` (string) — Currency is the single currency all items resolve to. - `salesLed` (boolean) — SalesLed reports the sales-led (no self-serve payment rail) trial motion, derived at read time from deployment config. Serialized without omitempty so a concrete false is always sent and clients can distinguish it from absent. - `settlement` (object) — BillingSubscriptionSettlement holds rail-scoped settlement references. Spec.Rail identifies which rail is ACTIVE and therefore which sub-record is authoritative; both may be populated at once, so a reader must not infer the rail from whichever one is set. Card is written by W5; Marketplace by the cloud_marketplace rail. Both coexist while an org migrates between rails, and an empty Card record is allocatable on a marketplace-rail org (see HasArrangement). Ask the arm for Spec.Rail, or use the per-arm predicates. - `card` (object) — BillingSubscriptionCardSettlement are the Stripe references for the card rail. - `stripeSubscriptionId` (string) — StripeSubscriptionID is the id of the Stripe Subscription bound to the org's default vaulted card, with trial_end = Status.TrialEndsAt. - `currentPeriodEnd` (string) — CurrentPeriodEnd is the end of the current Stripe billing period. - `latestInvoiceStatus` (string) — LatestInvoiceStatus mirrors the latest Stripe invoice status (e.g. paid, open, uncollectible) so Sync can reconcile the phase. - `hostedInvoiceUrl` (string) — HostedInvoiceURL is the Stripe-hosted page for the latest unpaid invoice, captured from invoice.* events. When a charge fails — a hard decline or an off-session charge that needs SCA authentication — this page is where the customer authenticates, pays, or updates their card, so dunning links here instead of the console root. Cleared on invoice.paid; empty when no invoice event has carried one. - `marketplace` (object) — BillingSubscriptionMarketplaceSettlement holds the settlement references for the cloud_marketplace rail: who usage is reported against, and how far it has been reported. - `provider` (string) — Provider is the marketplace cloud (aws | azure), mirroring CloudMarketplaceRef.Provider. - `fulfillmentRef` (string) — FulfillmentRef ties this settlement back to the projected PaymentMethod (the clazarBuyerId for the Clazar backend); it is that resource's name. - `customerIdentifier` (string) — CustomerIdentifier is the marketplace-native buyer id usage is reported against, resolved at registration. - `licenseArn` (string) — LicenseArn is the per-agreement licence the marketplace requires on each usage record (AWS only; empty for a provider that needs none). - `planId` (string) — PlanID is the marketplace plan usage is reported under, when the provider requires one on the record (Azure only; empty for a provider that needs none). - `planChangedAt` (string) — PlanChangedAt is when the buyer last moved to a different plan, and is empty for a subscription whose plan has never changed. - `meteredThrough` (string) — MeteredThrough is the metering watermark: usage up to this instant has been successfully reported to the marketplace. It only ever moves forward. - `carryCents` (integer) — CarryCents is the sub-unit remainder carried into the next reporting period. - `pendingPrepayCents` (integer) — PendingPrepayCents is the amount of prepaid-commitment money still to be reported as usage on this rail. It is added to by a purchase, a renewal or a commitment upgrade, and cleared when the metering hour that carried it is confirmed. - `lastReportedAt` (string) — LastReportedAt is when usage was last successfully reported, and LastReportError the reason the most recent attempt failed (empty when the last attempt succeeded). - `lastReportError` (string) - `commitments` (object[]) — Commitments is the server-owned state of each of the organization's prepaid annual commitments, keyed by the same id as spec.commitments[]: how far the purchase has settled, and when it renews. - `id` (string) - `phase` (string) — Phase: pending_start | active | lapsed. A lot whose charge has not settled stays pending_start on either rail. Phase is a SETTLEMENT state, not a coverage state — coverage is decided by the term window alone. - `lapseCause` (string) — LapseCause says WHY the lot lapsed, and is set with the phase itself: subscription_canceled | term_ended | charge_refused | prepay_unsettled. Only term_ended means the lot ran the full term it was paid for; subscription_canceled means the remainder of that term was forfeited, and the two unpaid causes mean the term was cut short for want of a charge. Absent while the lot is pending_start or active. - `lapsedAt` (string) — LapsedAt is when the lot was stamped lapsed, which is the moment its coverage stopped. For a term cut short that is NOT the term end the customer was told: spec.commitments[].boughtTermEnd is the boundary they bought. - `stripePriceID` (string) — StripePriceID is the annual catalog Price the lot was bought or last renewed at, so a later reprice stays auditable against what was paid. - `stripeInvoiceID` (string) — StripeInvoiceID is the one-off invoice that settled the lot on the CARD rail. Empty on the marketplace rail. - `prepayPeriodStart` (string) — PrepayPeriodStart / PrepayUnits record how a lot was settled on the MARKETPLACE rail: the metering hour its prepay was folded into, and the unit count reported for it. - `prepayUnits` (integer) - `unsettledPrepayCents` (integer) — UnsettledPrepayCents is this commitment's share of the marketplace prepay still to be reported: the cents raised for it that no metering hour has carried yet. Zero on the card rail, and zero once its prepay has settled. - `purchasedAt` (string) — PurchasedAt is when the commitment was bought, as distinct from termStart, which is when its coverage begins: a commitment bought during a trial starts covering when the trial ends. It never moves; a renewal extends the term of the same commitment rather than buying a new one. - `renewalNoticeStage` (string) — RenewalNoticeStage is the send-once marker for the T-60/T-30/T-7 renewal notices. - `renewalInvoicedTermEnd` (string) — RenewalInvoicedTermEnd is the term end at which the lot's most recent renewal was charged; the renewed term begins there. Unset until the lot's first renewal. - `upgradeInvoiceID` (string) — UpgradeInvoiceID and UpgradeInvoiceTarget name the ONE commitment-upgrade invoice that was raised for this lot and has not been collected, together with the "kind/descriptor" it was raised for. Both are set together and cleared together, and they outlive the revert that puts a declined upgrade back — the lot stays at the size it covers today, and this pair is the record of the larger one that was asked for and refused. Paying that invoice does not by itself resize anything. The upgrade is applied when the same resize is requested again, which collects this invoice rather than raising a second one — and applies at no further charge if the invoice has been paid in the meantime. - `upgradeInvoiceTarget` (string) - `lastInvoiceStatus` (string) — LastInvoiceStatus is the last outcome reported for the invoice that settles this commitment — the one that bought it, the one that last renewed it, or an upgrade that applied: `paid`, or `payment_failed`, and absent while no outcome has been reported yet. It is empty for a commitment bought through a cloud marketplace, where no invoice is raised. It is the only field that says whether the money for a commitment ARRIVED. `phase` is a settlement state that advances when the term starts whether or not it did, and `stripeInvoiceID` names the invoice without saying what became of it — an invoice exists from the moment one is raised, a declined card included. So this is the field to read before presenting prepaid time as forfeited: only a collected charge makes it so. A declined commitment-upgrade invoice keeps its own outcome and is never reported here. - `renewsAt` (string) — RenewsAt is the date this commitment renews and is charged again, present only while auto-renew is on. Its absence is the useful signal: it means coverage simply ends at the commitment's term end, and the regions it covers return to monthly billing from the next billing period. It is served rather than left to be derived so that every surface states the same date. A client must not compute it from termEnd itself: whether a commitment renews is a property of the commitment, and reading it off a date alone would show a renewal for a commitment the customer has already cancelled. ### 400 — The request body did not say whether to renew. `application/json` In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object. - `code` (string) — Required. This is the same as the HTTP status of the response. - `message` (string) — Required. A short description of the error. - `status` (object) — Required. A status code that indicates the error type. - `details` (object) — Additional details about the errors. - `@type` (string) — The type of error. - `reason` (string) — A reason for the error. - `domain` (string) — The domain in which the error occurred. - `metadata` (object) — Additional metadata about the error. `application/vnd.api+json` JSONAPI.org specification error response wrapper for UI. - `error` (object) — In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object. - `code` (string) — Required. This is the same as the HTTP status of the response. - `message` (string) — Required. A short description of the error. - `status` (object) — Required. A status code that indicates the error type. - `details` (object) — Additional details about the errors. - `@type` (string) — The type of error. - `reason` (string) — A reason for the error. - `domain` (string) — The domain in which the error occurred. - `metadata` (object) — Additional metadata about the error. - `meta` (object) — Link members related to the primary data. - One of: - **string (uri-reference)** — A string containing the link's URL. - **object** - `href` (string (uri-reference)) — Required. A string containing the link's URL. - `meta` (object) — Non-standard meta-information that can not be represented as an attribute or relationship. - `links` (object) — Non-standard meta-information that can not be represented as an attribute or relationship. ### 404 — [Not found](https://jsonapi.org/format/#fetching-resources-responses-404) `application/json` In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object. - `code` (string) — Required. This is the same as the HTTP status of the response. - `message` (string) — Required. A short description of the error. - `status` (object) — Required. A status code that indicates the error type. - `details` (object) — Additional details about the errors. - `@type` (string) — The type of error. - `reason` (string) — A reason for the error. - `domain` (string) — The domain in which the error occurred. - `metadata` (object) — Additional metadata about the error. `application/vnd.api+json` JSONAPI.org specification error response wrapper for UI. - `error` (object) — In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object. - `code` (string) — Required. This is the same as the HTTP status of the response. - `message` (string) — Required. A short description of the error. - `status` (object) — Required. A status code that indicates the error type. - `details` (object) — Additional details about the errors. - `@type` (string) — The type of error. - `reason` (string) — A reason for the error. - `domain` (string) — The domain in which the error occurred. - `metadata` (object) — Additional metadata about the error. - `meta` (object) — Link members related to the primary data. - One of: - **string (uri-reference)** — A string containing the link's URL. - **object** - `href` (string (uri-reference)) — Required. A string containing the link's URL. - `meta` (object) — Non-standard meta-information that can not be represented as an attribute or relationship. - `links` (object) — Non-standard meta-information that can not be represented as an attribute or relationship. ### default — Unexpected error. `application/json` In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object. - `code` (string) — Required. This is the same as the HTTP status of the response. - `message` (string) — Required. A short description of the error. - `status` (object) — Required. A status code that indicates the error type. - `details` (object) — Additional details about the errors. - `@type` (string) — The type of error. - `reason` (string) — A reason for the error. - `domain` (string) — The domain in which the error occurred. - `metadata` (object) — Additional metadata about the error. `application/vnd.api+json` JSONAPI.org specification error response wrapper for UI. - `error` (object) — In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object. - `code` (string) — Required. This is the same as the HTTP status of the response. - `message` (string) — Required. A short description of the error. - `status` (object) — Required. A status code that indicates the error type. - `details` (object) — Additional details about the errors. - `@type` (string) — The type of error. - `reason` (string) — A reason for the error. - `domain` (string) — The domain in which the error occurred. - `metadata` (object) — Additional metadata about the error. - `meta` (object) — Link members related to the primary data. - One of: - **string (uri-reference)** — A string containing the link's URL. - **object** - `href` (string (uri-reference)) — Required. A string containing the link's URL. - `meta` (object) — Non-standard meta-information that can not be represented as an attribute or relationship. - `links` (object) — Non-standard meta-information that can not be represented as an attribute or relationship.