> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getsales.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Pause subscription

> Pause the subscription at the next billing period: billing stops, every workspace drawing from it is held (automation paused, data kept). DANGEROUS state change; no charge. The committed status arrives by webhook. resume_billing_subscription undoes it. Owner only.

Contract:
- MCP tool `pause_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.



## OpenAPI

````yaml /api-reference/id/openapi.yaml post /api/billing-subscriptions/{sid}/pause
openapi: 3.0.3
info:
  title: 'GetSales public contract: gs.service.id'
  description: >-
    The identity service: the signed-in account, its workspaces and their
    members, the sessions and the gtm-api workspaces a team reaches; the API
    keys, OAuth clients and standing consents; the Paddle billing of the pool a
    buyer holds (catalog, subscriptions, transactions, payment methods); the
    partner's surface (white label brands, their clients, the shares handed to
    workspaces, the certificates behind the brand domains); and the notification
    feed.


    GENERATED. This document is projected from the Zod MCP tool registry in
    `product/mcp/gs.mcp` (one tool per public endpoint, 1:1). Do not edit it by
    hand; edit the tool definition and regenerate with `pnpm openapi:public`.


    Surface: the public `/api` contract of `gs.service.id`, 88 operations. This
    is the only OpenAPI document the platform publishes. Internal (`/internal`)
    and health endpoints are deliberately absent: they are not part of any
    contract, they can change without notice, and the service source is their
    only description.


    Conventions:

    - Auth is a bearer JWT, optionally narrowed by the `Team-SID` header.

    - Every success body is an MCP envelope: `success: true` plus one typed
    `operation` shape (`search`, `get`, `create`, `update`, `delete`, `metrics`,
    `group_by`, `action`), and a `meta` block with `trace_id` for support.

    - Every failure is the same `McpError` envelope with a code from a fixed
    16-code taxonomy, so a client maps errors once.

    - Lists page with `page_size` (0 to 500, default 50) plus an opaque forward
    `cursor`; `page_size: 0` returns counts only.

    - On `GET` and `DELETE`, object-valued query parameters (`filter`, `sort`)
    travel as JSON text and array-valued ones repeat as `name[]=value`.

    - The MCP-only `_meta` field (usage analytics) never reaches the backend and
    is not part of this contract.
  version: '1.0'
  contact:
    name: GetSales
    url: https://getsales.io
    email: support@getsales.io
  license:
    name: Proprietary
    url: https://getsales.io/terms
servers:
  - url: https://beta.getsales.io/id/v1
    description: >-
      Production (the gateway path on the beta ring; the origin is provisioned
      per DEPLOY_MAP.md)
security:
  - BearerJwt: []
    TeamSid: []
tags:
  - name: api_keys
    description: Registry package `mcp.id/api_keys`, served on MCP mount `id.access`.
  - name: billing_payment_methods
    description: >-
      Registry package `mcp.id/billing_payment_methods`, served on MCP mount
      `id.billing`.
  - name: billing_products
    description: >-
      Registry package `mcp.id/billing_products`, served on MCP mount
      `id.billing`.
  - name: billing_subscriptions
    description: >-
      Registry package `mcp.id/billing_subscriptions`, served on MCP mount
      `id.billing`.
  - name: billing_transactions
    description: >-
      Registry package `mcp.id/billing_transactions`, served on MCP mount
      `id.billing`.
  - name: credit_lots
    description: Registry package `mcp.id/credit_lots`, served on MCP mount `id.billing`.
  - name: credit_transactions
    description: >-
      Registry package `mcp.id/credit_transactions`, served on MCP mount
      `id.billing`.
  - name: gtm_connections
    description: >-
      Registry package `mcp.id/gtm_connections`, served on MCP mount
      `id.identity`.
  - name: notifications
    description: >-
      Registry package `mcp.id/notifications`, served on MCP mount
      `id.notifications`.
  - name: oauth_authorizations
    description: >-
      Registry package `mcp.id/oauth_authorizations`, served on MCP mount
      `id.access`.
  - name: oauth_clients
    description: Registry package `mcp.id/oauth_clients`, served on MCP mount `id.access`.
  - name: sessions
    description: Registry package `mcp.id/sessions`, served on MCP mount `id.identity`.
  - name: ssl_certificates
    description: >-
      Registry package `mcp.id/ssl_certificates`, served on MCP mount
      `id.partner`.
  - name: subscription_allocations
    description: >-
      Registry package `mcp.id/subscription_allocations`, served on MCP mount
      `id.partner`.
  - name: team_members
    description: Registry package `mcp.id/team_members`, served on MCP mount `id.identity`.
  - name: teams
    description: Registry package `mcp.id/teams`, served on MCP mount `id.identity`.
  - name: user_profiles
    description: >-
      Registry package `mcp.id/user_profiles`, served on MCP mount
      `id.identity`.
  - name: users
    description: Registry package `mcp.id/users`, served on MCP mount `id.identity`.
  - name: whitelabel_clients
    description: >-
      Registry package `mcp.id/whitelabel_clients`, served on MCP mount
      `id.partner`.
  - name: whitelabels
    description: Registry package `mcp.id/whitelabels`, served on MCP mount `id.partner`.
  - name: workspace_profiles
    description: >-
      Registry package `mcp.id/workspace_profiles`, served on MCP mount
      `id.identity`.
paths:
  /api/billing-subscriptions/{sid}/pause:
    post:
      tags:
        - billing_subscriptions
      summary: Pause subscription
      description: >-
        Pause the subscription at the next billing period: billing stops, every
        workspace drawing from it is held (automation paused, data kept).
        DANGEROUS state change; no charge. The committed status arrives by
        webhook. resume_billing_subscription undoes it. Owner only.


        Contract:

        - MCP tool `pause_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.
      operationId: pause_billing_subscription
      parameters:
        - name: sid
          in: path
          required: true
          description: Billing subscription sid (bl_sb_...).
          schema:
            type: string
            minLength: 18
            maxLength: 18
            pattern: ^bl_sb_
            description: Billing subscription sid (bl_sb_...).
      responses:
        '200':
          description: '`action` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PauseBillingSubscriptionResponse'
        4XX:
          $ref: '#/components/responses/McpClientError'
        5XX:
          $ref: '#/components/responses/McpServerError'
components:
  schemas:
    PauseBillingSubscriptionResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        operation:
          type: string
          enum:
            - action
        action:
          type: string
          description: kebab-case verb; matches the route segment.
        item:
          type: object
          nullable: true
          properties:
            sid:
              type: string
              description: Subscription sid (bl_sb_...).
            owner_user_sid:
              type: string
              description: 'The buyer (us_mb_...): the one who manages the pool.'
            team_sid:
              type: string
              nullable: true
              description: >-
                Always null on this product: a subscription floats and
                allocations bind workspaces to it.
            paddle_subscription_id:
              type: string
              nullable: true
              description: Paddle's id (sub_...); null on an internal sentinel (the trial).
            status:
              type: string
              enum:
                - active
                - past_due
                - paused
                - canceled
              description: >-
                active; past_due (a failed renewal: LinkedIn and email run 3
                more days); paused; canceled (terminal).
            collection_mode:
              type: string
              enum:
                - automatic
                - manual
              description: >-
                automatic = the card is charged; manual = invoiced (a sales
                deal) or the trial sentinel.
            price_sid:
              type: string
              description: >-
                The first line's price (bl_pc_...); the lines include says what
                each line is.
            quantity:
              type: integer
              description: '1 on a resource subscription: a line is one item of quantity 1.'
            addons:
              type: array
              items:
                type: object
                properties:
                  product_sid:
                    type: string
                    description: The line's product (bl_pr_...).
                  price_sid:
                    type: string
                    description: >-
                      The line's price (bl_pc_...), a non-catalog price of this
                      order.
                  paddle_item_id:
                    type: string
                    nullable: true
                    description: Paddle's item id on the subscription; null on a sentinel.
                  quantity:
                    type: integer
                    description: 'Always 1 on a resource subscription: a line is one item.'
                  status:
                    type: string
                    enum:
                      - active
                      - canceled
                    description: canceled = the line grants nothing any more.
                required:
                  - product_sid
                  - price_sid
                  - paddle_item_id
                  - quantity
                  - status
              description: The other lines of the order, one item each.
            currency:
              type: string
              description: 'ISO 4217: USD, EUR or GBP.'
            current_period_starts_at:
              type: string
              nullable: true
              description: ISO 8601 UTC.
            current_period_ends_at:
              type: string
              nullable: true
              description: ISO 8601 UTC; the trial's end on the sentinel.
            next_billed_at:
              type: string
              nullable: true
              description: ISO 8601 UTC; null when nothing is billed next.
            paused_at:
              type: string
              nullable: true
              description: ISO 8601 UTC; null unless paused.
            scheduled_resume_at:
              type: string
              nullable: true
              description: ISO 8601 UTC; null unless a resume is scheduled.
            scheduled_change:
              type: object
              nullable: true
              properties:
                action:
                  type: string
                  enum:
                    - cancel
                    - pause
                    - resume
                  description: What happens at effective_at.
                effective_at:
                  type: string
                  description: ISO 8601 UTC.
                resume_at:
                  type: string
                  nullable: true
                  description: 'For a scheduled pause: when it resumes; null = open-ended.'
              required:
                - action
                - effective_at
                - resume_at
              description: >-
                A cancel, pause or resume waiting for the period end; null =
                none.
            canceled_at:
              type: string
              nullable: true
              description: ISO 8601 UTC; null unless canceled.
            canceled_by:
              type: object
              nullable: true
              properties:
                actor_type:
                  type: string
                  enum:
                    - user
                    - support
                    - api_key
                    - system
                    - agent
                actor_sid:
                  type: string
                  nullable: true
                team_sid:
                  type: string
                actor_name:
                  type: string
                  nullable: true
                  description: >-
                    The OAuth client that acted ("Claude", "n8n"); null for a
                    user, an API key or a system job.
                oauth_client_sid:
                  type: string
                  nullable: true
                  description: The acting OAuth client (id_oc_*); null off the OAuth path.
                reason:
                  type: string
                  nullable: true
                  description: >-
                    Why a system actor wrote the row (snapshot_capture_job,
                    ...); null otherwise.
                permissions:
                  type: object
                  additionalProperties: {}
                  description: >-
                    Internal audit context: the grant set the actor held at
                    write time. Not a contract.
                cluster_id:
                  type: integer
                  nullable: true
                  description: 'Internal audit context: the cluster that served the write.'
                trace_id:
                  type: string
                  nullable: true
                  description: >-
                    Internal audit context: the trace id of the request that
                    wrote the row.
              required:
                - actor_type
                - actor_sid
                - team_sid
                - permissions
              description: Who canceled; null unless canceled by a person.
            created_at:
              type: string
              description: ISO 8601 UTC.
            updated_at:
              type: string
              description: ISO 8601 UTC.
            deleted_at:
              type: string
              nullable: true
              description: ISO 8601 UTC; null = live.
          required:
            - sid
            - owner_user_sid
            - team_sid
            - paddle_subscription_id
            - status
            - collection_mode
            - price_sid
            - quantity
            - addons
            - currency
            - current_period_starts_at
            - current_period_ends_at
            - next_billed_at
            - paused_at
            - scheduled_resume_at
            - scheduled_change
            - canceled_at
            - canceled_by
            - created_at
            - updated_at
            - deleted_at
        result:
          type: object
          additionalProperties: {}
        meta:
          type: object
          properties:
            trace_id:
              type: string
              description: UUID v7; same 128-bit value as the X-Trace-Id header.
            span_id:
              type: string
              pattern: ^[0-9a-f]{16}$
              description: 16 hex chars, root span of this request.
            timestamp:
              type: string
              description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
            duration_ms:
              type: integer
              minimum: 0
              description: Server-side wall clock.
            team_sid:
              type: string
              nullable: true
              description: >-
                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:
              type: string
              nullable: true
              description: >-
                user | agent | api_key | system. Null when unauthenticated;
                absent from pre-2026-08-20 backends.
          required:
            - trace_id
            - span_id
            - timestamp
            - duration_ms
      required:
        - success
        - operation
        - action
        - item
        - result
        - meta
    McpError:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - 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
                - internal_error
                - service_unavailable
                - not_implemented
            message:
              type: string
            recoverable:
              type: boolean
            suggestion:
              type: string
            field_errors:
              type: object
              additionalProperties:
                type: array
                items:
                  type: object
                  properties:
                    rule:
                      type: string
                    message:
                      type: string
                  required:
                    - rule
                    - message
            blockers:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: >-
                      Machine-readable blocker type (active_flow, pending_tasks,
                      …).
                  severity:
                    type: string
                    enum:
                      - hard
                      - soft
                    description: >-
                      hard = external action required; soft = acknowledge is
                      enough.
                  description:
                    type: string
                  entity_sid:
                    type: string
                    nullable: true
                  count:
                    type: integer
                  resolution:
                    type: string
                    description: 'Hard: tool name to call. Soft: code for acknowledge[].'
                  resolution_hint:
                    type: string
                required:
                  - type
                  - severity
                  - description
                  - entity_sid
                  - resolution
                  - resolution_hint
            context:
              type: object
              additionalProperties: {}
          required:
            - code
            - message
            - recoverable
        meta:
          type: object
          properties:
            trace_id:
              type: string
              description: UUID v7; same 128-bit value as the X-Trace-Id header.
            span_id:
              type: string
              pattern: ^[0-9a-f]{16}$
              description: 16 hex chars, root span of this request.
            timestamp:
              type: string
              description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
            duration_ms:
              type: integer
              minimum: 0
              description: Server-side wall clock.
            team_sid:
              type: string
              nullable: true
              description: >-
                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:
              type: string
              nullable: true
              description: >-
                user | agent | api_key | system. Null when unauthenticated;
                absent from pre-2026-08-20 backends.
          required:
            - trace_id
            - span_id
            - timestamp
            - duration_ms
      required:
        - success
        - error
  responses:
    McpClientError:
      description: >-
        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.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
    McpServerError:
      description: >-
        MCP error envelope with `error.code` internal_error or
        service_unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
  securitySchemes:
    BearerJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token issued by gs.service.id. Its `access_identity` claim
        carries `team_sid`, `actor_sid` and `actor_type`, and that team scope is
        authoritative.
    TeamSid:
      type: apiKey
      in: header
      name: Team-SID
      description: >-
        Team scope for tokens that do not carry one. Ignored when the token
        already names a team.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.