Schematic
Schematic plans API

The plans API from Schematic — 14 operation(s) for plans.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.0
info:
  title: Schematic accesstokens plans API
  version: '0.1'
  description: Schematic API
  x-rules-engine-schema-version: v97288f60
servers:
- url: https://api.schematichq.com
security:
- ApiKeyAuth: []
tags:
- name: plans
paths:
  /company-plans/{company_plan_id}:
    put:
      operationId: updateCompanyPlans
      summary: Update company plans
      tags:
      - plans
      parameters:
      - name: company_plan_id
        in: path
        description: company_plan_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCompanyPlansRequestBody'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CompanyDetailResponseData'
                  params:
                    type: object
                    description: Input parameters
                    title: UpdateCompanyPlansParams
                required:
                - data
                - params
                title: UpdateCompanyPlansResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /custom-plan-billings:
    get:
      operationId: listCustomPlanBillings
      summary: List custom plan billings
      tags:
      - plans
      parameters:
      - name: company_id
        in: query
        description: Filter by company ID
        schema:
          type: string
          description: Filter by company ID
      - name: plan_id
        in: query
        description: Filter by plan ID
        schema:
          type: string
          description: Filter by plan ID
      - name: status
        in: query
        description: Filter by billing status
        schema:
          allOf:
          - $ref: '#/components/schemas/CustomPlanBillingStatus'
          description: Filter by billing status
      - name: statuses
        in: query
        description: Filter by multiple billing statuses
        schema:
          type: array
          description: Filter by multiple billing statuses
          items:
            $ref: '#/components/schemas/CustomPlanBillingStatus'
          maxItems: 10
      - name: limit
        in: query
        description: Page limit (default 100)
        schema:
          type: integer
          description: Page limit (default 100)
          format: int64
          example: '100'
      - name: offset
        in: query
        description: Page offset (default 0)
        schema:
          type: integer
          description: Page offset (default 0)
          format: int64
          example: '0'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomPlanBillingResponseData'
                    title: ListCustomPlanBillingsResponseData
                    maxItems: 250
                  params:
                    type: object
                    description: Input parameters
                    properties:
                      company_id:
                        type: string
                        description: Filter by company ID
                      limit:
                        type: integer
                        description: Page limit (default 100)
                        format: int64
                        example: '100'
                      offset:
                        type: integer
                        description: Page offset (default 0)
                        format: int64
                        example: '0'
                      plan_id:
                        type: string
                        description: Filter by plan ID
                      status:
                        allOf:
                        - $ref: '#/components/schemas/CustomPlanBillingStatus'
                        description: Filter by billing status
                      statuses:
                        type: array
                        description: Filter by multiple billing statuses
                        items:
                          $ref: '#/components/schemas/CustomPlanBillingStatus'
                        maxItems: 10
                    title: ListCustomPlanBillingsParams
                required:
                - data
                - params
                title: ListCustomPlanBillingsResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /custom-plan-billings/{custom_plan_billing_id}/retry:
    put:
      operationId: retryCustomPlanBilling
      summary: Retry custom plan billing
      tags:
      - plans
      parameters:
      - name: custom_plan_billing_id
        in: path
        description: custom_plan_billing_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetryCustomPlanBillingRequestBody'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CustomPlanBillingResponseData'
                  params:
                    type: object
                    description: Input parameters
                    title: RetryCustomPlanBillingParams
                required:
                - data
                - params
                title: RetryCustomPlanBillingResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /custom-plans:
    post:
      operationId: createCustomPlan
      summary: Create custom plan
      tags:
      - plans
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomPlanRequestBody'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PlanDetailResponseData'
                  params:
                    type: object
                    description: Input parameters
                    title: CreateCustomPlanParams
                required:
                - data
                - params
                title: CreateCustomPlanResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /plans:
    get:
      operationId: listPlans
      summary: List plans
      tags:
      - plans
      parameters:
      - name: company_id
        in: query
        schema:
          type: string
      - name: exclude_company_scoped
        in: query
        description: Exclude plans that are scoped to a company (custom plans assigned to a company)
        schema:
          type: boolean
          description: Exclude plans that are scoped to a company (custom plans assigned to a company)
      - name: for_fallback_plan
        in: query
        description: Filter for plans valid as fallback plans (not linked to billing)
        schema:
          type: boolean
          description: Filter for plans valid as fallback plans (not linked to billing)
      - name: for_initial_plan
        in: query
        description: Filter for plans valid as initial plans (not linked to billing, free, or auto-cancelling trial)
        schema:
          type: boolean
          description: Filter for plans valid as initial plans (not linked to billing, free, or auto-cancelling trial)
      - name: for_trial_expiry_plan
        in: query
        description: Filter for plans valid as trial expiry plans (not linked to billing or free)
        schema:
          type: boolean
          description: Filter for plans valid as trial expiry plans (not linked to billing or free)
      - name: has_product_id
        in: query
        description: Filter out plans that do not have a billing product ID
        schema:
          type: boolean
          description: Filter out plans that do not have a billing product ID
      - name: ids
        in: query
        schema:
          type: array
          items:
            type: string
          maxItems: 100
      - name: include_draft_versions
        in: query
        description: Include billing settings from draft versions for plans which have draft version
        schema:
          type: boolean
          description: Include billing settings from draft versions for plans which have draft version
      - name: plan_type
        in: query
        description: Filter by plan type
        schema:
          allOf:
          - $ref: '#/components/schemas/PlanType'
          description: Filter by plan type
      - name: q
        in: query
        schema:
          type: string
      - name: scoped_to_company_id
        in: query
        description: Filter plans scoped to a specific company (custom plans)
        schema:
          type: string
          description: Filter plans scoped to a specific company (custom plans)
      - name: without_entitlement_for
        in: query
        description: Filter out plans that already have a plan entitlement for the specified feature ID
        schema:
          type: string
          description: Filter out plans that already have a plan entitlement for the specified feature ID
      - name: without_paid_product_id
        in: query
        description: Filter out plans that have a paid billing product ID
        schema:
          type: boolean
          description: Filter out plans that have a paid billing product ID
      - name: limit
        in: query
        description: Page limit (default 100)
        schema:
          type: integer
          description: Page limit (default 100)
          format: int64
          example: '100'
      - name: offset
        in: query
        description: Page offset (default 0)
        schema:
          type: integer
          description: Page offset (default 0)
          format: int64
          example: '0'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PlanDetailResponseData'
                    title: ListPlansResponseData
                    maxItems: 250
                  params:
                    type: object
                    description: Input parameters
                    properties:
                      company_id:
                        type: string
                      exclude_company_scoped:
                        type: boolean
                        description: Exclude plans that are scoped to a company (custom plans assigned to a company)
                      for_fallback_plan:
                        type: boolean
                        description: Filter for plans valid as fallback plans (not linked to billing)
                      for_initial_plan:
                        type: boolean
                        description: Filter for plans valid as initial plans (not linked to billing, free, or auto-cancelling trial)
                      for_trial_expiry_plan:
                        type: boolean
                        description: Filter for plans valid as trial expiry plans (not linked to billing or free)
                      has_product_id:
                        type: boolean
                        description: Filter out plans that do not have a billing product ID
                      ids:
                        type: array
                        items:
                          type: string
                        maxItems: 100
                      include_draft_versions:
                        type: boolean
                        description: Include billing settings from draft versions for plans which have draft version
                      limit:
                        type: integer
                        description: Page limit (default 100)
                        format: int64
                        example: '100'
                      offset:
                        type: integer
                        description: Page offset (default 0)
                        format: int64
                        example: '0'
                      plan_type:
                        allOf:
                        - $ref: '#/components/schemas/PlanType'
                        description: Filter by plan type
                      q:
                        type: string
                      scoped_to_company_id:
                        type: string
                        description: Filter plans scoped to a specific company (custom plans)
                      without_entitlement_for:
                        type: string
                        description: Filter out plans that already have a plan entitlement for the specified feature ID
                      without_paid_product_id:
                        type: boolean
                        description: Filter out plans that have a paid billing product ID
                    title: ListPlansParams
                required:
                - data
                - params
                title: ListPlansResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      operationId: createPlan
      summary: Create plan
      tags:
      - plans
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePlanRequestBody'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PlanDetailResponseData'
                  params:
                    type: object
                    description: Input parameters
                    title: CreatePlanParams
                required:
                - data
                - params
                title: CreatePlanResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /plans/{plan_id}:
    get:
      operationId: getPlan
      summary: Get plan
      tags:
      - plans
      parameters:
      - name: plan_id
        in: path
        description: plan_id
        required: true
        schema:
          type: string
      - name: plan_version_id
        in: query
        description: Fetch billing settings for a specific plan version
        schema:
          type: string
          description: Fetch billing settings for a specific plan version
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PlanDetailResponseData'
                  params:
                    type: object
                    description: Input parameters
                    properties:
                      plan_version_id:
                        type: string
                        description: Fetch billing settings for a specific plan version
                    title: GetPlanParams
                required:
                - data
                - params
                title: GetPlanResponse
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    put:
      operationId: updatePlan
      summary: Update plan
      tags:
      - plans
      parameters:
      - name: plan_id
        in: path
        description: plan_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePlanRequestBody'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PlanDetailResponseData'
                  params:
                    type: object
                    description: Input parameters
                    title: UpdatePlanParams
                required:
                - data
                - params
                title: UpdatePlanResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      operationId: deletePlan
      summary: Delete plan
      tags:
      - plans
      parameters:
      - name: plan_id
        in: path
        description: plan_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DeleteResponse'
                  params:
                    type: object
                    description: Input parameters
                    title: DeletePlanParams
                required:
                - data
                - params
                title: DeletePlanResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /plans/{plan_id}/billing_products:
    put:
      operationId: upsertBillingProductPlan
      summary: Upsert billing product plan
      tags:
      - plans
      parameters:
      - name: plan_id
        in: path
        description: plan_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertBillingProductRequestBody'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BillingProductPlanResponseData'
                  params:
                    type: object
                    description: Input parameters
                    title: UpsertBillingProductPlanParams
                required:
                - data
                - params
                title: UpsertBillingProductPlanResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /plans/billing-linked:
    post:
      operationId: upsertPlanForBillingProduct
      summary: Upsert plan for billing product
      tags:
      - plans
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBillingLinkedPlanRequestBody'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/PlanDetailResponseData'
                  params:
                    type: object
                    description: Input parameters
                    title: UpsertPlanForBillingProductParams
                required:
                - data
                - params
                title: UpsertPlanForBillingProductResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /plans/billing-product-match-companies:
    get:
      operationId: listBillingProductMatchCompanies
      summary: List billing product match companies
      tags:
      - plans
      parameters:
      - name: plan_id
        in: query
        description: The plan ID to find billing product match companies for
        required: true
        schema:
          type: string
          description: The plan ID to find billing product match companies for
      - name: q
        in: query
        description: Search for companies by name, keys or string traits
        schema:
          type: string
          description: Search for companies by name, keys or string traits
          maxLength: 512
      - name: limit
        in: query
        description: Page limit (default 100)
        schema:
          type: integer
          description: Page limit (default 100)
          format: int64
          example: '100'
      - name: offset
        in: query
        description: Page offset (default 0)
        schema:
          type: integer
          description: Page offset (default 0)
          format: int64
          example: '0'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CompanyDetailResponseData'
                    title: ListBillingProductMatchCompaniesResponseData
                    maxItems: 250
                  params:
                    type: object
                    description: Input parameters
                    properties:
                      limit:
                        type: integer
                        description: Page limit (default 100)
                        format: int64
                        example: '100'
                      offset:
                        type: integer
                        description: Page offset (default 0)
                        format: int64
                        example: '0'
                      plan_id:
                        type: string
                        description: The plan ID to find billing product match companies for
                      q:
                        type: string
                        description: Search for companies by name, keys or string traits
                        maxLength: 512
                    title: ListBillingProductMatchCompaniesParams
                required:
                - data
                - params
                title: ListBillingProductMatchCompaniesResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /plans/billing-product-match-companies/count:
    get:
      operationId: countBillingProductMatchCompanies
      summary: Count billing product match companies
      tags:
      - plans
      parameters:
      - name: plan_id
        in: query
        description: The plan ID to find billing product match companies for
        required: true
        schema:
          type: string
          description: The plan ID to find billing product match companies for
      - name: q
        in: query
        description: Search for companies by name, keys or string traits
        schema:
          type: string
          description: Search for companies by name, keys or string traits
          maxLength: 512
      - name: limit
        in: query
        description: Page limit (default 100)
        schema:
          type: integer
          description: Page limit (default 100)
          format: int64
          example: '100'
      - name: offset
        in: query
        description: Page offset (default 0)
        schema:
          type: integer
          description: Page offset (default 0)
          format: int64
          example: '0'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CountResponse'
                  params:
                    type: object
                    description: Input parameters
                    properties:
                      limit:
                        type: integer
                        description: Page limit (default 100)
                        format: int64
                        example: '100'
                      offset:
                        type: integer
                        description: Page offset (default 0)
                        format: int64
                        example: '0'
                      plan_id:
                        type: string
                        description: The plan ID to find billing product match companies for
                      q:
                        type: string
                        description: Search for companies by name, keys or string traits
                        maxLength: 512
                    title: CountBillingProductMatchCompaniesParams
                required:
                - data
                - params
                title: CountBillingProductMatchCompaniesResponse
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /plans/count:
    get:
      operationId: countPlans
      summary: Count plans
      tags:
      - plans
      parameters:
      - name: company_id
        in: query
        schema:
          type: string
      - name: exclude_company_scoped
        in: query
        description: Exclude plans that are scoped to a company (custom plans assigned to a company)
        schema:
          type: boolean
          description: Exclude plans that are scoped to a company (custom plans assigned to a company)
      - name: for_fallback_plan
        in: query
        description: Filter for plans valid as fallback plans (not linked to billing)
        schema:
          type: boolean
          description: Filter for plans valid as fallback plans (not linked to billing)
      - name: for_initial_plan
        in: query
        description: Filter for plans valid as initial plans (not linked to billing, free, or auto-cancelling trial)
        schema:
          type: boolean
          description: Filter for plans valid as initial plans (not linked to billing, free, or auto-cancelling trial)
      - name: for_trial_expiry_plan
        in: query
        description: Filter for plans valid as trial expiry plans (not linked to billing or free)
        schema:
          type: boolean
          description: Filter for plans valid as trial expiry plans (not linked to billing or free)
      - name: has_product_id
        in: query
        description: Filter out plans that do not have a billing product ID
        schema:
          type: boolean
          description: Filter out plans that do not have a billing product ID
      - name: ids
        in: query
        schema:
          type: array
          items:
            type: string
          maxItems: 100
      - name: include_draft_versions
        in: query
        description: Include billing settings from draft versions for plans which have draft version
        schema:
          type: boolean
          description: Include billing settings from draft versions for plans which have draft version
      - name: plan_type
        in: query
        description: Filter by plan type
        schema:
          allOf:
          - $ref: '#/components/schemas/PlanType'
          description: Filter by plan type
      - name: q
        in: query
        schema:
          type: string
      - name: scoped_to_company_id
        in: query
        description: Filter plans scoped to a specific company (custom plans)
        schema:
          type: string
          description: Filter plans scoped to a specific company (custom plans)
      - name: without_entitlement_for
        in: query
        description: Filter out plans that already have a plan entitlement for the specified feature ID
        schema:
          type: string
          description: Filter out plans that already have a plan entitlement for the specified feature ID
      - name: without_paid_product_id
        in: query
        description: Filter out plans that have a paid billing product ID
        schema:
          type: boolean
          description: Filter out plans that have a paid billing product ID
      - name: limit
        in: query
        description: Page limit (default 100)
        schema:
          type: integer
          description: Page limit (default 100)
          format: int64
          example: '100'
      - name: offset
        in: query
        description: Page offset (default 0)
        schema:
          type: integer
          description: Page offset (default 0)
          format: int64
          example: '0'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/C

# --- truncated at 32 KB (105 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/schematic/refs/heads/main/openapi/schematic-plans-api-openapi.yml
Schematic plans API

Documentation

Specifications

SDKs

Schemas & Data

Other Resources

OpenAPI Specification
