--- title: purchase-credits product: vercel url: /docs/rest-api/billing/purchase-credits type: reference prerequisites: [] related: - /docs/rest-api summary: Learn about purchase-credits on Vercel. install_vercel_plugin: npx plugins add vercel/vercel-plugin --- # Purchase credits ```http POST /v1/billing/buy ``` Purchases credits for a Vercel team using the default payment method on file. The purchase is charged immediately via Stripe invoice. Supported credit types are `v0`, `gateway`, and `agent`. The `amount` field specifies the number of credits to purchase and must be a positive integer. An optional `source` query parameter can be provided to identify the caller. Defaults to `api` if not specified. This is only available for Owner, Member, Developer, Security, and Billing roles for the supplied team. ## Authentication **bearerToken**: HTTP bearer ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `source` | string | No | The source of the purchase request. Defaults to `api` if not specified. | | `teamId` | string | No | The Team identifier to perform the request on behalf of. | | `slug` | string | No | The Team slug to perform the request on behalf of. | ## Request body Required: Yes Content-Type: `application/json` ```json { "type": "object", "required": [ "item" ], "properties": { "item": { "type": "object", "required": [ "type", "creditType", "amount" ], "properties": { "type": { "type": "string", "description": "The type of item to purchase.", "enum": [ "credits" ] }, "creditType": { "type": "string", "description": "The type of credits to purchase.", "enum": [ "v0", "gateway", "agent" ] }, "amount": { "type": "integer", "description": "The amount of credits to purchase.", "minimum": 1 } } } } } ``` ## Responses ### 200: No description Content-Type: `application/json` ```json { "oneOf": [ { "type": "object", "required": [ "checkoutSessionId", "checkoutSessionUrl" ], "properties": { "checkoutSessionId": { "type": "string" }, "checkoutSessionUrl": { "type": "string" } } }, { "type": "object", "required": [ "purchaseIntent" ], "properties": { "purchaseIntent": { "type": "object", "description": "The created purchase intent", "required": [ "configuration", "createdAt", "currency", "id", "ownerId", "provider", "status", "subtotal", "tax", "total", "updatedAt" ], "properties": { "id": { "type": "string", "description": "The unique ID of a Purchase Intent. Uses the format `pur_*`" }, "configuration": { "oneOf": [ { "type": "object", "description": "The configuration for a credit purchase", "required": [ "options", "output", "type" ], "properties": { "options": { "type": "object", "description": "Purchase configuration specific options", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "description": "The amount of currency to buy" }, "currency": { "type": "string", "description": "The currency being purchased", "enum": [ "copper_test_units", "ai_credits", "ai_gateway_credits", "v0_user_credits", "vercel_agent_credits" ] }, "expirationDate": { "type": "string", "description": "The expiration date of the credits being purchased" } } }, "output": { "nullable": true }, "type": { "type": "string", "enum": [ "credit_topup" ] } } }, { "type": "object", "description": "The configuration for a credit purchase", "required": [ "options", "output", "type" ], "properties": { "options": { "type": "object", "required": [ "items", "orderId" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "name", "subtotal", "type", "years" ], "properties": { "name": { "type": "string" }, "subtotal": { "type": "string", "description": "The subtotal of the domain name purchase" }, "type": { "type": "string", "enum": [ "purchase", "renewal", "transfer" ] }, "years": { "type": "number", "description": "The number of years to purchase" } } } }, "orderId": { "type": "string", "description": "The order ID of the domain name purchase" } } }, "output": { "nullable": true }, "type": { "type": "string", "enum": [ "domain_name" ] } } }, { "type": "object", "description": "The configuration for a credit purchase", "required": [ "options", "output", "type" ], "properties": { "options": { "type": "object", "required": [ "effectiveDate", "orbSubscriptionId" ], "properties": { "effectiveDate": { "oneOf": [ { "type": "object", "description": "The effective date of the plan change" }, { "type": "string", "enum": [ "immediate", "end_of_subscription_term" ] } ] }, "orbSubscriptionId": { "type": "string", "description": "The ID of the Orb subscription to change" }, "alignBillingWithPlanChangeDate": { "type": "boolean", "description": "Whether or not to reset the billing cycle", "enum": [ false, true ] }, "couponRedemptionCode": { "type": "string", "description": "The coupon redemption code to apply to the plan change" }, "externalPlanId": { "type": "string", "description": "The ID of the external plan to change to" }, "replacePrices": { "type": "array", "description": "The prices to replace in the subscription", "items": { "type": "object", "description": "The prices to replace in the subscription", "required": [ "fixedPriceQuantity", "replacesPriceId" ], "properties": { "fixedPriceQuantity": { "type": "number", "description": "The quantity for the fixed price" }, "replacesPriceId": { "type": "string", "description": "The ID of the price to replace" } } } } } }, "output": { "type": "object", "required": [ "pendingSubscriptionChangeId" ], "properties": { "pendingSubscriptionChangeId": { "type": "string", "description": "The ID of the pending subscription change" } } }, "type": { "type": "string", "enum": [ "orb_plan_change" ] } } }, { "type": "object", "description": "The configuration for a credit purchase", "required": [ "options", "output", "type" ], "properties": { "options": { "type": "object" }, "output": { "type": "object", "required": [ "pendingSubscriptionChangeId" ], "properties": { "pendingSubscriptionChangeId": { "type": "string", "description": "The ID of the pending subscription change" } } }, "type": { "type": "string", "enum": [ "orb_price_interval" ] } } }, { "type": "object", "description": "The configuration for a credit purchase", "required": [ "options", "output", "type" ], "properties": { "options": { "type": "object", "required": [ "externalPlanId" ], "properties": { "externalPlanId": { "type": "string", "description": "The external plan ID of the Orb plan to subscribe to" }, "addPrices": { "type": "array", "description": "The prices to add to the subscription", "items": { "oneOf": [ { "type": "object", "description": "The prices to add to the subscription", "required": [ "priceId" ], "properties": { "priceId": { "type": "string", "description": "The ID of the price to add" } } }, { "type": "object", "description": "The prices to add to the subscription" } ] } }, "alignBillingWithSubscriptionStartDate": { "type": "boolean", "description": "Whether to align the subscription start date with the billing subscription start date", "enum": [ false, true ] }, "couponRedemptionCode": { "type": "string", "description": "The coupon redemption code to apply to the subscription" }, "initialPhaseOrder": { "type": "number", "description": "The initial phase order to use for the subscription" }, "metadata": { "type": "object", "description": "Optional metadata to associate with the subscription", "additionalProperties": { "type": "string", "description": "Optional metadata to associate with the subscription", "nullable": true } }, "removePrices": { "type": "array", "description": "The prices to remove in the subscription", "items": { "type": "object", "description": "The prices to remove in the subscription", "required": [ "priceId" ], "properties": { "priceId": { "type": "string", "description": "The ID of the price to remove" } } } }, "replacePrices": { "type": "array", "description": "The prices to replace in the subscription", "items": { "type": "object", "description": "The prices to replace in the subscription", "required": [ "fixedPriceQuantity", "replacesPriceId" ], "properties": { "fixedPriceQuantity": { "type": "number", "description": "The quantity for the fixed price" }, "replacesPriceId": { "type": "string", "description": "The ID of the price to replace" } } } }, "startDate": { "type": "string", "description": "The start date of the subscription" } } }, "output": { "type": "object", "required": [ "pendingSubscriptionChangeId" ], "properties": { "pendingSubscriptionChangeId": { "type": "string", "description": "The ID of the pending subscription change" } } }, "type": { "type": "string", "enum": [ "orb_subscription" ] } } }, { "type": "object", "description": "The configuration for a credit purchase", "required": [ "options", "output", "type" ], "properties": { "options": { "type": "object", "required": [ "orbCustomerId", "orbExternalCustomerId", "orbExternalPlanId", "orbPendingSubscriptionChangeId", "orbPlanId", "orbSubscriptionId" ], "properties": { "orbCustomerId": { "type": "string", "description": "The ID of the Orb customer to create" }, "orbExternalCustomerId": { "type": "string", "description": "The external ID of the Orb customer to create" }, "orbExternalPlanId": { "type": "string", "description": "The external ID of the Orb plan to create" }, "orbPendingSubscriptionChangeId": { "type": "string", "description": "The ID of the pending subscription change" }, "orbPlanId": { "type": "string", "description": "The ID of the Orb plan to create" }, "orbSubscriptionId": { "type": "string", "description": "The ID of the Orb subscription to create" }, "lineItems": { "type": "array", "description": "The line items that make up the Purchase Intent.", "items": { "type": "object", "description": "The line items that make up the Purchase Intent.", "required": [ "description", "id", "name", "productId", "quantity", "unitAmount" ], "properties": { "id": { "type": "string", "description": "The ID of the line item" }, "description": { "type": "string", "description": "The description of the line item" }, "name": { "type": "string", "description": "The name of the line item" }, "productId": { "type": "string", "description": "The ID of the product being purchased" }, "quantity": { "type": "string", "description": "The quantity of the line item" }, "unitAmount": { "type": "string", "description": "The unit amount of the line item" }, "metadata": { "type": "object", "description": "Optional metadata for the line item", "additionalProperties": { "type": "string" } }, "productAlias": { "type": "string", "description": "The alias of the product being purchased" }, "refund": { "type": "string", "description": "The amount of the line item that has been refunded" } } } } } }, "output": { "type": "object", "required": [ "pendingSubscriptionChangeId" ], "properties": { "pendingSubscriptionChangeId": { "type": "string", "description": "The ID of the pending subscription change" } } }, "type": { "type": "string", "enum": [ "orb_subscription_intent" ] } } } ] }, "createdAt": { "type": "string", "description": "The datetime when the Purchase Intent was created." }, "currency": { "type": "string", "description": "The currency for the purchase intent", "enum": [ "usd", "miu" ] }, "ownerId": { "type": "string", "description": "The ID of the owner of the Purchase Intent." }, "provider": { "type": "object", "required": [ "resourceId", "type" ], "properties": { "resourceId": { "type": "string", "description": "Provider resource id" }, "type": { "type": "string", "description": "The type of the purchase provider", "enum": [ "stripe_elements", "stripe_hosted", "stripe_invoice_deferred", "stripe_invoice_immediate", "stripe_invoice_elements", "tackle_aws_marketplace", "orb_ledger", "apple_in_app_purchase" ] }, "currencyConversionRate": { "type": "string", "description": "The currency conversion rate used by the provider" }, "stripeSharedPaymentTokenUsed": { "type": "boolean", "description": "Whether a Stripe Shared Payment Token was used for this purchase. Only applicable when type is stripe_invoice_immediate.", "enum": [ false, true ] } } }, "status": { "type": "string", "description": "The status of the Purchase Intent.", "enum": [ "pending", "succeeded", "failed" ] }, "subtotal": { "type": "string", "description": "The subtotal of the Purchase Intent." }, "tax": { "type": "string", "description": "The tax due on the Purchase Intent." }, "total": { "type": "string", "description": "The total balance due on the Purchase Intent." }, "updatedAt": { "type": "string", "description": "The datetime when the Purchase Intent was last updated." }, "dispute": { "type": "object", "description": "The dispute details, if any.", "required": [ "amount", "createdAt", "currency", "id", "providerId", "reason", "status", "updatedAt" ], "properties": { "id": { "type": "string", "description": "The unique ID of the dispute entity." }, "amount": { "type": "string", "description": "The disputed amount." }, "createdAt": { "type": "string", "description": "When the dispute was first recorded." }, "currency": { "type": "string", "description": "The dispute currency." }, "providerId": { "type": "string", "description": "The external provider dispute ID (e.g. Stripe dispute ID)." }, "reason": { "type": "string", "description": "The dispute reason.", "nullable": true }, "status": { "type": "string", "description": "The dispute status." }, "updatedAt": { "type": "string", "description": "When the dispute was last updated." } } }, "lineItems": { "type": "array", "description": "The line items that make up the Purchase Intent.", "items": { "type": "object", "description": "The line items that make up the Purchase Intent.", "required": [ "description", "id", "name", "productId", "quantity", "unitAmount" ], "properties": { "id": { "type": "string", "description": "The ID of the line item" }, "description": { "type": "string", "description": "The description of the line item" }, "name": { "type": "string", "description": "The name of the line item" }, "productId": { "type": "string", "description": "The ID of the product being purchased" }, "quantity": { "type": "string", "description": "The quantity of the line item" }, "unitAmount": { "type": "string", "description": "The unit amount of the line item" }, "metadata": { "type": "object", "description": "Optional metadata for the line item", "additionalProperties": { "type": "string" } }, "productAlias": { "type": "string", "description": "The alias of the product being purchased" }, "refund": { "type": "string", "description": "The amount of the line item that has been refunded" } } } }, "metadata": { "type": "object", "description": "Optional metadata associated with the purchase intent", "additionalProperties": { "type": "string" } }, "refund": { "type": "string", "description": "The amount of the purchase intent that has been refunded" }, "returnUrl": { "type": "string", "description": "The URL to redirect to after the purchase is complete" } } } } }, { "type": "object", "required": [ "orbSubscriptionIntent" ], "properties": { "orbSubscriptionIntent": { "type": "object", "required": [ "configuration", "createdAt", "id", "orbSubscriptionId", "ownerId", "status", "updatedAt" ], "properties": { "id": { "type": "string", "description": "The ID of the Orb subscription intent with the format `orbsubint_`." }, "configuration": { "oneOf": [ { "type": "object", "description": "Configuration for the Orb subscription intent.", "required": [ "options", "output", "type" ], "properties": { "options": { "type": "object", "description": "Configuration input options for setting plan item quantity.", "required": [ "productAlias", "quantity" ], "properties": { "productAlias": { "type": "string", "description": "The alias of the product to set quantity for." }, "quantity": { "type": "number", "description": "The quantity to set for the plan item." }, "resourceIds": { "type": "array", "description": "The resource IDs for the plan item. Only set if SKU requires resource entitlements.", "items": { "type": "string" } } } }, "output": { "type": "object", "description": "Output returned after configuring an OrbSubscriptionIntent.", "required": [ "orbPriceId", "productId" ], "properties": { "orbPriceId": { "type": "string", "description": "The Orb price ID for the subscription item being modified." }, "productId": { "type": "string", "description": "The product ID associated with this intent." }, "changedResources": { "type": "array", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "items": { "oneOf": [ { "type": "object", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "required": [ "productAlias", "productId", "quantity", "type" ], "properties": { "productAlias": { "type": "string", "description": "The alias of the product that was changed." }, "productId": { "type": "string", "description": "The ID of the product that was changed." }, "quantity": { "type": "number", "description": "The resulting quantity after this change." }, "type": { "type": "string", "enum": [ "set_plan_item_quantity" ] }, "resourceIds": { "type": "array", "description": "The full set of resource IDs after the set operation.", "items": { "type": "string" } } } }, { "type": "object", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "required": [ "productAlias", "productId", "quantity", "resourceIds", "type" ], "properties": { "productAlias": { "type": "string", "description": "The alias of the product that was changed." }, "productId": { "type": "string", "description": "The ID of the product that was changed." }, "quantity": { "type": "number", "description": "The resulting quantity after this change." }, "resourceIds": { "type": "array", "description": "Resource IDs that were added.", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "increase_plan_item_quantity" ] } } }, { "type": "object", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "required": [ "productAlias", "productId", "quantity", "resourceIds", "type" ], "properties": { "productAlias": { "type": "string", "description": "The alias of the product that was changed." }, "productId": { "type": "string", "description": "The ID of the product that was changed." }, "quantity": { "type": "number", "description": "The resulting quantity after this change." }, "resourceIds": { "type": "array", "description": "Resource IDs that were removed.", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "decrease_plan_item_quantity" ] } } }, { "type": "object", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "required": [ "addedResourceIds", "productAlias", "productId", "quantity", "removedResourceIds", "type" ], "properties": { "addedResourceIds": { "type": "array", "description": "Resource IDs that were added.", "items": { "type": "string" } }, "productAlias": { "type": "string", "description": "The alias of the product that was changed." }, "productId": { "type": "string", "description": "The ID of the product that was changed." }, "quantity": { "type": "number", "description": "The resulting quantity after this change." }, "removedResourceIds": { "type": "array", "description": "Resource IDs that were removed.", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "adjust_plan_item_quantity" ] } } } ] } }, "metadata": { "type": "object", "description": "Optional metadata associated with the intent to update the Orb subscription with.", "additionalProperties": { "type": "string" } }, "pendingSubscriptionChangeId": { "type": "string", "description": "The ID of the pending subscription change if there is one." } } }, "type": { "type": "string", "enum": [ "set_plan_item_quantity" ] } } }, { "type": "object", "description": "Configuration for the Orb subscription intent.", "required": [ "options", "output", "type" ], "properties": { "options": { "type": "object", "description": "Configuration input options for increasing plan item quantity.", "required": [ "productAlias", "resourceIds" ], "properties": { "productAlias": { "type": "string", "description": "The alias of the product to increase quantity for." }, "resourceIds": { "type": "array", "description": "The resource IDs to incrementally add. The quantity of the plan item will be increased by the number of resource IDs.", "items": { "type": "string" } } } }, "output": { "type": "object", "description": "Output returned after configuring an OrbSubscriptionIntent.", "required": [ "orbPriceId", "productId" ], "properties": { "orbPriceId": { "type": "string", "description": "The Orb price ID for the subscription item being modified." }, "productId": { "type": "string", "description": "The product ID associated with this intent." }, "changedResources": { "type": "array", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "items": { "oneOf": [ { "type": "object", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "required": [ "productAlias", "productId", "quantity", "type" ], "properties": { "productAlias": { "type": "string", "description": "The alias of the product that was changed." }, "productId": { "type": "string", "description": "The ID of the product that was changed." }, "quantity": { "type": "number", "description": "The resulting quantity after this change." }, "type": { "type": "string", "enum": [ "set_plan_item_quantity" ] }, "resourceIds": { "type": "array", "description": "The full set of resource IDs after the set operation.", "items": { "type": "string" } } } }, { "type": "object", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "required": [ "productAlias", "productId", "quantity", "resourceIds", "type" ], "properties": { "productAlias": { "type": "string", "description": "The alias of the product that was changed." }, "productId": { "type": "string", "description": "The ID of the product that was changed." }, "quantity": { "type": "number", "description": "The resulting quantity after this change." }, "resourceIds": { "type": "array", "description": "Resource IDs that were added.", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "increase_plan_item_quantity" ] } } }, { "type": "object", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "required": [ "productAlias", "productId", "quantity", "resourceIds", "type" ], "properties": { "productAlias": { "type": "string", "description": "The alias of the product that was changed." }, "productId": { "type": "string", "description": "The ID of the product that was changed." }, "quantity": { "type": "number", "description": "The resulting quantity after this change." }, "resourceIds": { "type": "array", "description": "Resource IDs that were removed.", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "decrease_plan_item_quantity" ] } } }, { "type": "object", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "required": [ "addedResourceIds", "productAlias", "productId", "quantity", "removedResourceIds", "type" ], "properties": { "addedResourceIds": { "type": "array", "description": "Resource IDs that were added.", "items": { "type": "string" } }, "productAlias": { "type": "string", "description": "The alias of the product that was changed." }, "productId": { "type": "string", "description": "The ID of the product that was changed." }, "quantity": { "type": "number", "description": "The resulting quantity after this change." }, "removedResourceIds": { "type": "array", "description": "Resource IDs that were removed.", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "adjust_plan_item_quantity" ] } } } ] } }, "metadata": { "type": "object", "description": "Optional metadata associated with the intent to update the Orb subscription with.", "additionalProperties": { "type": "string" } }, "pendingSubscriptionChangeId": { "type": "string", "description": "The ID of the pending subscription change if there is one." } } }, "type": { "type": "string", "enum": [ "increase_plan_item_quantity" ] } } }, { "type": "object", "description": "Configuration for the Orb subscription intent.", "required": [ "options", "output", "type" ], "properties": { "options": { "type": "object", "description": "Configuration input options for decreasing plan item quantity.", "required": [ "productAlias", "resourceIds" ], "properties": { "productAlias": { "type": "string", "description": "The alias of the product to decrease quantity for." }, "resourceIds": { "type": "array", "description": "The resource IDs to decrementally remove. The quantity of the plan item will be decreased by the number of resource IDs.", "items": { "type": "string" } } } }, "output": { "type": "object", "description": "Output returned after configuring an OrbSubscriptionIntent.", "required": [ "orbPriceId", "productId" ], "properties": { "orbPriceId": { "type": "string", "description": "The Orb price ID for the subscription item being modified." }, "productId": { "type": "string", "description": "The product ID associated with this intent." }, "changedResources": { "type": "array", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "items": { "oneOf": [ { "type": "object", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "required": [ "productAlias", "productId", "quantity", "type" ], "properties": { "productAlias": { "type": "string", "description": "The alias of the product that was changed." }, "productId": { "type": "string", "description": "The ID of the product that was changed." }, "quantity": { "type": "number", "description": "The resulting quantity after this change." }, "type": { "type": "string", "enum": [ "set_plan_item_quantity" ] }, "resourceIds": { "type": "array", "description": "The full set of resource IDs after the set operation.", "items": { "type": "string" } } } }, { "type": "object", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "required": [ "productAlias", "productId", "quantity", "resourceIds", "type" ], "properties": { "productAlias": { "type": "string", "description": "The alias of the product that was changed." }, "productId": { "type": "string", "description": "The ID of the product that was changed." }, "quantity": { "type": "number", "description": "The resulting quantity after this change." }, "resourceIds": { "type": "array", "description": "Resource IDs that were added.", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "increase_plan_item_quantity" ] } } }, { "type": "object", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "required": [ "productAlias", "productId", "quantity", "resourceIds", "type" ], "properties": { "productAlias": { "type": "string", "description": "The alias of the product that was changed." }, "productId": { "type": "string", "description": "The ID of the product that was changed." }, "quantity": { "type": "number", "description": "The resulting quantity after this change." }, "resourceIds": { "type": "array", "description": "Resource IDs that were removed.", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "decrease_plan_item_quantity" ] } } }, { "type": "object", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "required": [ "addedResourceIds", "productAlias", "productId", "quantity", "removedResourceIds", "type" ], "properties": { "addedResourceIds": { "type": "array", "description": "Resource IDs that were added.", "items": { "type": "string" } }, "productAlias": { "type": "string", "description": "The alias of the product that was changed." }, "productId": { "type": "string", "description": "The ID of the product that was changed." }, "quantity": { "type": "number", "description": "The resulting quantity after this change." }, "removedResourceIds": { "type": "array", "description": "Resource IDs that were removed.", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "adjust_plan_item_quantity" ] } } } ] } }, "metadata": { "type": "object", "description": "Optional metadata associated with the intent to update the Orb subscription with.", "additionalProperties": { "type": "string" } }, "pendingSubscriptionChangeId": { "type": "string", "description": "The ID of the pending subscription change if there is one." } } }, "type": { "type": "string", "enum": [ "decrease_plan_item_quantity" ] } } }, { "type": "object", "description": "Configuration for the Orb subscription intent.", "required": [ "options", "output", "type" ], "properties": { "options": { "type": "object", "description": "Configuration input options for adjusting plan item quantity.", "required": [ "addedResourceIds", "productAlias", "removedResourceIds" ], "properties": { "addedResourceIds": { "type": "array", "description": "The resource IDs to incrementally add. The quantity of the plan item will be increased by the number of resource IDs.", "items": { "type": "string" } }, "productAlias": { "type": "string", "description": "The alias of the product to adjust quantity for." }, "removedResourceIds": { "type": "array", "description": "The resource IDs to incrementally remove. The quantity of the plan item will be decreased by the number of resource IDs.", "items": { "type": "string" } } } }, "output": { "type": "object", "description": "Output returned after configuring an OrbSubscriptionIntent.", "required": [ "orbPriceId", "productId" ], "properties": { "orbPriceId": { "type": "string", "description": "The Orb price ID for the subscription item being modified." }, "productId": { "type": "string", "description": "The product ID associated with this intent." }, "changedResources": { "type": "array", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "items": { "oneOf": [ { "type": "object", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "required": [ "productAlias", "productId", "quantity", "type" ], "properties": { "productAlias": { "type": "string", "description": "The alias of the product that was changed." }, "productId": { "type": "string", "description": "The ID of the product that was changed." }, "quantity": { "type": "number", "description": "The resulting quantity after this change." }, "type": { "type": "string", "enum": [ "set_plan_item_quantity" ] }, "resourceIds": { "type": "array", "description": "The full set of resource IDs after the set operation.", "items": { "type": "string" } } } }, { "type": "object", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "required": [ "productAlias", "productId", "quantity", "resourceIds", "type" ], "properties": { "productAlias": { "type": "string", "description": "The alias of the product that was changed." }, "productId": { "type": "string", "description": "The ID of the product that was changed." }, "quantity": { "type": "number", "description": "The resulting quantity after this change." }, "resourceIds": { "type": "array", "description": "Resource IDs that were added.", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "increase_plan_item_quantity" ] } } }, { "type": "object", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "required": [ "productAlias", "productId", "quantity", "resourceIds", "type" ], "properties": { "productAlias": { "type": "string", "description": "The alias of the product that was changed." }, "productId": { "type": "string", "description": "The ID of the product that was changed." }, "quantity": { "type": "number", "description": "The resulting quantity after this change." }, "resourceIds": { "type": "array", "description": "Resource IDs that were removed.", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "decrease_plan_item_quantity" ] } } }, { "type": "object", "description": "Resources that were changed as part of this intent. Tracks all logical changes including the primary change and any side effects.", "required": [ "addedResourceIds", "productAlias", "productId", "quantity", "removedResourceIds", "type" ], "properties": { "addedResourceIds": { "type": "array", "description": "Resource IDs that were added.", "items": { "type": "string" } }, "productAlias": { "type": "string", "description": "The alias of the product that was changed." }, "productId": { "type": "string", "description": "The ID of the product that was changed." }, "quantity": { "type": "number", "description": "The resulting quantity after this change." }, "removedResourceIds": { "type": "array", "description": "Resource IDs that were removed.", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "adjust_plan_item_quantity" ] } } } ] } }, "metadata": { "type": "object", "description": "Optional metadata associated with the intent to update the Orb subscription with.", "additionalProperties": { "type": "string" } }, "pendingSubscriptionChangeId": { "type": "string", "description": "The ID of the pending subscription change if there is one." } } }, "type": { "type": "string", "enum": [ "adjust_plan_item_quantity" ] } } } ] }, "createdAt": { "type": "string", "description": "The ISO 8601 date-time that the intent was created." }, "orbSubscriptionId": { "type": "string", "description": "The Orb subscription ID this intent is associated with." }, "ownerId": { "type": "string", "description": "The owner ID for this intent (e.g., team or user ID)." }, "status": { "type": "string", "description": "The status of the Orb subscription intent.", "enum": [ "pending", "succeeded", "failed" ] }, "updatedAt": { "type": "string", "description": "The ISO 8601 date-time that the intent was last updated." }, "purchaseIntentId": { "type": "string", "description": "Optional purchase intent ID if this is associated with a purchase." } } } } } ] } ``` ### 400: One of the provided values in the request query is invalid. ### 401: The request is not authorized. ### 402: No description ### 403: You do not have permission to access this resource. ### 404: No description ### 500: No description --- ## Related - [billing endpoints](/docs/rest-api#billing) - [REST API overview](/docs/rest-api) - [OpenAPI spec](https://openapi.vercel.sh/) (machine-readable, all endpoints) --- [View full sitemap](/docs/sitemap)