--- title: "Change subscription" method: POST path: "/api/billing-subscriptions/{sid}/change" tags: ["billing_subscriptions"] --- # Change subscription `POST /api/billing-subscriptions/{sid}/change` ## Request - Base URL: `https://beta.getsales.io/id/v1` - URL: `https://beta.getsales.io/id/v1/api/billing-subscriptions/{sid}/change` - Auth: HTTP bearer and API key in header `Team-SID` Commit a change of the composition: the LinkedIn accounts, the inbox packages, the credits a month, each part the whole new value (an omitted part stays). DANGEROUS: up to three Paddle calls, the decreases and free restorations first (nothing billed), then the credits top-up (a one-time charge), then the prorated LinkedIn and added packages, so a refused card stops only the last step (409 payment_declined). Call preview_billing_subscription_change first. Removing every line is a cancel (409 use_cancel); a pool below the sum of its shares is refused (409 allocated_exceeds_pool: lower the shares first; a standard account's one share follows the plan down); a credits change while a top-up is unpaid is 409 change_pending; an invoiced subscription is not re-priced here. The renewal date never moves. Owner only. Contract: - MCP tool `change_billing_subscription`, registry package `mcp.id/billing_subscriptions`, mount `id.billing`. - Operation `action`, response envelope `action`. - Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API. ## Path parameters - `sid` string, required: Billing subscription sid (bl_sb_...). ## Request body - ChangeBillingSubscriptionRequest: Request body of `change_billing_subscription`. - `linkedin` object: The LinkedIn line's target; omit to keep it. - `accounts` integer, required: The new count of LinkedIn accounts. - `email` object: The email line's target packages, every size named; omit to keep it. - `packages` object, required: How many packages of each size, 0 to 1,000 each; the capacity is their sum. - `100` integer: Packages of 100 inboxes. - `500` integer: Packages of 500 inboxes. - `2000` integer: Packages of 2,000 inboxes. - `10000` integer: Packages of 10,000 inboxes. - `data` object: The data line's target; omit to keep it. - `credits` integer, required: The new credits a month: 0, or from 1,000. ## Response `200` `action` success envelope. - ChangeBillingSubscriptionResponse - `success` true, required - `operation` 'action', required - `action` string, required: kebab-case verb; matches the route segment. - `item` object, nullable, required - `sid` string, required: Subscription sid (bl_sb_...). - `owner_user_sid` string, required: The buyer (us_mb_...): the one who manages the pool. - `team_sid` string, nullable, required: Always null on this product: a subscription floats and allocations bind workspaces to it. - `paddle_subscription_id` string, nullable, required: Paddle's id (sub_...); null on an internal sentinel (the trial). - `status` 'active' | 'past_due' | 'paused' | 'canceled', required: active; past_due (a failed renewal: LinkedIn and email run 3 more days); paused; canceled (terminal). - `collection_mode` 'automatic' | 'manual', required: automatic = the card is charged; manual = invoiced (a sales deal) or the trial sentinel. - `price_sid` string, required: The first line's price (bl_pc_...); the lines include says what each line is. - `quantity` integer, required: 1 on a resource subscription: a line is one item of quantity 1. - `addons` object[], required: The other lines of the order, one item each. - `product_sid` string, required: The line's product (bl_pr_...). - `price_sid` string, required: The line's price (bl_pc_...), a non-catalog price of this order. - `paddle_item_id` string, nullable, required: Paddle's item id on the subscription; null on a sentinel. - `quantity` integer, required: Always 1 on a resource subscription: a line is one item. - `status` 'active' | 'canceled', required: canceled = the line grants nothing any more. - `currency` string, required: ISO 4217: USD, EUR or GBP. - `current_period_starts_at` string, nullable, required: ISO 8601 UTC. - `current_period_ends_at` string, nullable, required: ISO 8601 UTC; the trial's end on the sentinel. - `next_billed_at` string, nullable, required: ISO 8601 UTC; null when nothing is billed next. - `paused_at` string, nullable, required: ISO 8601 UTC; null unless paused. - `scheduled_resume_at` string, nullable, required: ISO 8601 UTC; null unless a resume is scheduled. - `scheduled_change` object, nullable, required: A cancel, pause or resume waiting for the period end; null = none. - `action` 'cancel' | 'pause' | 'resume', required: What happens at effective_at. - `effective_at` string, required: ISO 8601 UTC. - `resume_at` string, nullable, required: For a scheduled pause: when it resumes; null = open-ended. - `canceled_at` string, nullable, required: ISO 8601 UTC; null unless canceled. - `canceled_by` object, nullable, required: Who canceled; null unless canceled by a person. - `actor_type` 'user' | 'support' | 'api_key' | 'system' | 'agent', required - `actor_sid` string, nullable, required - `team_sid` string, required - `actor_name` string, nullable: The OAuth client that acted ("Claude", "n8n"); null for a user, an API key or a system job. - `oauth_client_sid` string, nullable: The acting OAuth client (id_oc_*); null off the OAuth path. - `reason` string, nullable: Why a system actor wrote the row (snapshot_capture_job, ...); null otherwise. - `permissions` object, required: Internal audit context: the grant set the actor held at write time. Not a contract. - `cluster_id` integer, nullable: Internal audit context: the cluster that served the write. - `trace_id` string, nullable: Internal audit context: the trace id of the request that wrote the row. - `created_at` string, required: ISO 8601 UTC. - `updated_at` string, required: ISO 8601 UTC. - `deleted_at` string, nullable, required: ISO 8601 UTC; null = live. - `result` object, required - `currency` string, required: USD | EUR | GBP, the subscription's. - `period` string, required: monthly | annual, the subscription's. - `steps` object[], required: One per line that moves: line, kind (increase | decrease | restore), applies (now | next_period), charge_minor, charge_exact (false = Paddle's proration preview), from, to; a paid data increase carries credits_now. - `due_now_minor` integer, required: What the card is charged now, before tax. - `next_payment` object, required: amount_minor and at: the target's recurring invoice on the unchanged renewal date. - `capacity_after` object, required: The pool after the change: linkedin_sender_profiles, email_inboxes, credits_per_month, whitelabel. - `quote_after` object, required: The quote of the target composition. - `currency` string, required: USD | EUR | GBP, the order's. - `period` string, required: monthly | annual, the order's. - `book` string, required: The price book version the figures came from. - `lines` object[], required: One per resource ordered: line (linkedin | email | data), its count or packages, capacity, rate_minor, monthly_minor and invoice_minor (the amount per billing period). - `monthly_minor` integer, required: The recurring lines a month, before 12 + 2. - `recurring_invoice_minor` integer, required: The recurring invoice: the monthly sum, times 12 on annual. - `one_time_minor` integer, required: The one-time credits line, paid once. - `due_now_minor` integer, required: The first payment before tax and coupons: the recurring invoice plus the one-time line. - `has_recurring` boolean, required: false = one-time credits alone, which make no subscription. - `service_months` integer, nullable, required: 1, or 14 for 12 + 2; null when nothing recurs. - `grant_count` integer, required: How many monthly credit grants the period pays for (1, or 14). - `credit_expiry_days` integer, nullable, required: Days a granted lot lives: null = the credits live with the plan and burn when the workspace leaves it (an order that buys a plan, or credits bought alone under one); 90 for credits bought alone with no paid plan. - `capacity` object, required: What the order grants a workspace: linkedin_sender_profiles, email_inboxes, credits_per_month, whitelabel. - `service` object, required: level (free | paid | business | enterprise), next_level, next_threshold_minor and gap_minor a month to it; White label is part of Business. - `linkedin_next_tier` object, nullable, required: The next LinkedIn volume tier: accounts, add, capacity, total_minor, per_account_minor, savings_minor (negative = costlier in total); null at the package and above. - `applied` true, required: The Paddle calls went through; the webhook confirms the row. - `meta` object, required - `trace_id` string, required: UUID v7; same 128-bit value as the X-Trace-Id header. - `span_id` string, required: 16 hex chars, root span of this request. - `timestamp` string, required: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. - `duration_ms` integer, required: Server-side wall clock. - `team_sid` string, nullable: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. - `actor_type` string, nullable: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. ## Other responses - `4XX`: MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented. - `5XX`: MCP error envelope with `error.code` internal_error or service_unavailable. --- [API](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id.md) - [All operations](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id/llms.txt) - [OpenAPI document](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id/revisions/95e48541fe85?raw)