--- title: "Preview subscription change" method: POST path: "/api/billing-subscriptions/{sid}/preview-change" tags: ["billing_subscriptions"] --- # Preview subscription change `POST /api/billing-subscriptions/{sid}/preview-change` ## Request - Base URL: `https://beta.getsales.io/id/v1` - URL: `https://beta.getsales.io/id/v1/api/billing-subscriptions/{sid}/preview-change` - Auth: HTTP bearer and API key in header `Team-SID` Read-only preview of a change of the composition before committing: the steps it runs as (LinkedIn prorated now both ways; an added inbox package prorated now, a removed one leaving at the period's end; credits raised now against a top-up charge, lowered from the next period), what is due now, the next payment and the pool after. Each part named is the whole new value; an omitted part stays. No state change, no charge: show it before change_billing_subscription. Contract: - MCP tool `preview_billing_subscription_change`, registry package `mcp.id/billing_subscriptions`, mount `id.billing`. - Operation `action`, response envelope `action`. - Flags: read only. ## Path parameters - `sid` string, required: Billing subscription sid (bl_sb_...). ## Request body - PreviewBillingSubscriptionChangeRequest: Request body of `preview_billing_subscription_change`. - `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. - PreviewBillingSubscriptionChangeResponse - `success` true, required - `operation` 'action', required - `action` string, required: kebab-case verb; matches the route segment. - `item` unknown, required - `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. - `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)