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

# Create Subscription



## OpenAPI

````yaml https://app.flowglad.com/api/openapi post /api/v1/subscriptions
openapi: 3.1.0
info:
  title: Flowglad API
  version: 0.0.1
servers:
  - url: https://app.flowglad.com
security: []
externalDocs:
  url: https://docs.flowglad.com
paths:
  /api/v1/subscriptions:
    post:
      tags:
        - Subscriptions
      summary: Create Subscription
      operationId: subscriptions-create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                customerId:
                  description: >-
                    The internal ID of the customer. If not provided,
                    customerExternalId is required.
                  type: string
                customerExternalId:
                  description: >-
                    The external ID of the customer. If not provided, customerId
                    is required.
                  type: string
                priceId:
                  description: >-
                    The id of the price to subscribe to. If not provided,
                    priceSlug is required. Used to determine whether the
                    subscription is usage-based or not, and set other defaults
                    such as trial period and billing intervals.
                  type: string
                priceSlug:
                  description: >-
                    The slug of the price to subscribe to. If not provided,
                    priceId is required. Price slugs are scoped to the
                    customer's pricing model. Used to determine whether the
                    subscription is usage-based or not, and set other defaults
                    such as trial period and billing intervals.
                  type: string
                quantity:
                  description: >-
                    The quantity of the price purchased. If not provided,
                    defaults to 1.
                  type: number
                startDate:
                  description: >-
                    The time when the subscription starts. If not provided,
                    defaults to current time.
                  type: string
                interval:
                  description: >-
                    The interval of the subscription. If not provided, defaults
                    to the interval of the price provided by `priceId` or
                    `priceSlug`.
                  type: string
                  enum:
                    - day
                    - week
                    - month
                    - year
                intervalCount:
                  description: >-
                    The number of intervals that each billing period will last.
                    If not provided, defaults to 1
                  type: number
                trialEnd:
                  description: >-
                    Epoch time in milliseconds of when the trial ends. If not
                    provided, defaults to startDate + the associated price's
                    trialPeriodDays
                  type: number
                metadata:
                  $ref: '#/components/schemas/Metadata'
                name:
                  description: >-
                    The name of the subscription. If not provided, defaults to
                    the name of the product associated with the price provided
                    by 'priceId' or 'priceSlug'.
                  type: string
                defaultPaymentMethodId:
                  description: >-
                    The default payment method to use when attempting to run
                    charges for the subscription.If not provided, the customer's
                    default payment method will be used. If no default payment
                    method is present, charges will not run. If no default
                    payment method is provided and there is a trial period for
                    the subscription, the subscription will enter 'trial_ended'
                    status at the end of the trial period.
                  type: string
                backupPaymentMethodId:
                  description: >-
                    The payment method to try if charges for the subscription
                    fail with the default payment method.
                  type: string
                doNotCharge:
                  description: >-
                    If true, the subscription item's unitPrice will be set to 0,
                    resulting in no charges. The original price.unitPrice value
                    in the price record remains unchanged.
                  default: false
                  type: boolean
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscription:
                    $ref: '#/components/schemas/SubscriptionClientSelectSchema'
                required:
                  - subscription
                additionalProperties: false
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.BAD_REQUEST'
        '401':
          description: Authorization not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.UNAUTHORIZED'
        '403':
          description: Insufficient access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.FORBIDDEN'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    Metadata:
      description: JSON object
      type: object
      propertyNames:
        type: string
      additionalProperties:
        anyOf:
          - type: string
            maxLength: 500
          - type: number
          - type: boolean
    SubscriptionClientSelectSchema:
      oneOf:
        - $ref: '#/components/schemas/StandardSubscriptionRecord'
        - $ref: '#/components/schemas/NonRenewingSubscriptionRecord'
      type: object
      discriminator:
        propertyName: renews
        mapping:
          'true':
            $ref: '#/components/schemas/StandardSubscriptionRecord'
          'false':
            $ref: '#/components/schemas/NonRenewingSubscriptionRecord'
    error.BAD_REQUEST:
      title: Invalid input data error (400)
      description: The error information
      example:
        code: BAD_REQUEST
        message: Invalid input data
        issues: []
      type: object
      properties:
        message:
          description: The error message
          example: Invalid input data
          type: string
        code:
          description: The error code
          example: BAD_REQUEST
          type: string
        issues:
          description: An array of issues that were responsible for the error
          example: []
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
              - message
            additionalProperties: false
      required:
        - message
        - code
      additionalProperties: false
    error.UNAUTHORIZED:
      title: Authorization not provided error (401)
      description: The error information
      example:
        code: UNAUTHORIZED
        message: Authorization not provided
        issues: []
      type: object
      properties:
        message:
          description: The error message
          example: Authorization not provided
          type: string
        code:
          description: The error code
          example: UNAUTHORIZED
          type: string
        issues:
          description: An array of issues that were responsible for the error
          example: []
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
              - message
            additionalProperties: false
      required:
        - message
        - code
      additionalProperties: false
    error.FORBIDDEN:
      title: Insufficient access error (403)
      description: The error information
      example:
        code: FORBIDDEN
        message: Insufficient access
        issues: []
      type: object
      properties:
        message:
          description: The error message
          example: Insufficient access
          type: string
        code:
          description: The error code
          example: FORBIDDEN
          type: string
        issues:
          description: An array of issues that were responsible for the error
          example: []
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
              - message
            additionalProperties: false
      required:
        - message
        - code
      additionalProperties: false
    error.INTERNAL_SERVER_ERROR:
      title: Internal server error error (500)
      description: The error information
      example:
        code: INTERNAL_SERVER_ERROR
        message: Internal server error
        issues: []
      type: object
      properties:
        message:
          description: The error message
          example: Internal server error
          type: string
        code:
          description: The error code
          example: INTERNAL_SERVER_ERROR
          type: string
        issues:
          description: An array of issues that were responsible for the error
          example: []
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
              - message
            additionalProperties: false
      required:
        - message
        - code
      additionalProperties: false
    StandardSubscriptionRecord:
      type: object
      properties:
        id:
          type: string
        createdAt:
          description: Epoch milliseconds.
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        updatedAt:
          description: Epoch milliseconds.
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        livemode:
          type: boolean
        startDate:
          description: Epoch milliseconds.
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        customerId:
          type: string
        organizationId:
          type: string
        status:
          type: string
          enum:
            - trialing
            - active
            - past_due
            - unpaid
            - cancellation_scheduled
            - incomplete
            - incomplete_expired
            - canceled
            - paused
        defaultPaymentMethodId:
          anyOf:
            - type: string
            - type: 'null'
        backupPaymentMethodId:
          anyOf:
            - type: string
            - type: 'null'
        trialEnd:
          anyOf:
            - description: Epoch milliseconds.
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        currentBillingPeriodStart:
          anyOf:
            - description: Epoch milliseconds.
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        currentBillingPeriodEnd:
          anyOf:
            - description: Epoch milliseconds.
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        metadata:
          anyOf:
            - $ref: '#/components/schemas/Metadata'
            - type: 'null'
        canceledAt:
          anyOf:
            - description: Epoch milliseconds.
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        cancelScheduledAt:
          anyOf:
            - description: Epoch milliseconds.
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        cancellationReason:
          anyOf:
            - type: string
            - type: 'null'
        replacedBySubscriptionId:
          anyOf:
            - type: string
            - type: 'null'
        isFreePlan:
          anyOf:
            - type: boolean
            - type: 'null'
        doNotCharge:
          anyOf:
            - type: boolean
            - type: 'null'
        priceId:
          type: string
        runBillingAtPeriodStart:
          anyOf:
            - type: boolean
            - type: 'null'
        interval:
          type: string
          enum:
            - day
            - week
            - month
            - year
        intervalCount:
          description: A positive integer
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
        billingCycleAnchorDate:
          anyOf:
            - description: Epoch milliseconds.
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        name:
          anyOf:
            - type: string
            - type: 'null'
        renews:
          type: boolean
          const: true
        pricingModelId:
          type: string
        scheduledAdjustmentAt:
          anyOf:
            - description: Epoch milliseconds.
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        current:
          description: >-
            Whether the subscription is current (statuses "active", "trialing",
            "past_due", or "cancellation_scheduled")
          type: boolean
      required:
        - id
        - createdAt
        - updatedAt
        - livemode
        - startDate
        - customerId
        - organizationId
        - status
        - defaultPaymentMethodId
        - backupPaymentMethodId
        - cancellationReason
        - replacedBySubscriptionId
        - isFreePlan
        - doNotCharge
        - priceId
        - runBillingAtPeriodStart
        - interval
        - intervalCount
        - name
        - renews
        - pricingModelId
        - current
      additionalProperties: false
    NonRenewingSubscriptionRecord:
      type: object
      properties:
        id:
          type: string
        createdAt:
          description: Epoch milliseconds.
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        updatedAt:
          description: Epoch milliseconds.
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        livemode:
          type: boolean
        startDate:
          description: Epoch milliseconds.
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        customerId:
          type: string
        organizationId:
          type: string
        status:
          type: string
          enum:
            - active
            - canceled
            - credit_trial
        defaultPaymentMethodId:
          anyOf:
            - type: string
            - type: 'null'
        backupPaymentMethodId:
          anyOf:
            - type: string
            - type: 'null'
        trialEnd:
          description: Omitted.
          type: 'null'
        currentBillingPeriodStart:
          description: Omitted.
          type: 'null'
        currentBillingPeriodEnd:
          description: Omitted.
          type: 'null'
        metadata:
          anyOf:
            - $ref: '#/components/schemas/Metadata'
            - type: 'null'
        canceledAt:
          anyOf:
            - description: Epoch milliseconds.
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        cancelScheduledAt:
          anyOf:
            - description: Epoch milliseconds.
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        cancellationReason:
          anyOf:
            - type: string
            - type: 'null'
        replacedBySubscriptionId:
          anyOf:
            - type: string
            - type: 'null'
        isFreePlan:
          anyOf:
            - type: boolean
            - type: 'null'
        doNotCharge:
          anyOf:
            - type: boolean
            - type: 'null'
        priceId:
          type: string
        runBillingAtPeriodStart:
          anyOf:
            - type: boolean
            - type: 'null'
        interval:
          description: Omitted.
          type: 'null'
        intervalCount:
          description: Omitted.
          type: 'null'
        billingCycleAnchorDate:
          description: Omitted.
          type: 'null'
        name:
          anyOf:
            - type: string
            - type: 'null'
        renews:
          type: boolean
          const: false
        pricingModelId:
          type: string
        scheduledAdjustmentAt:
          anyOf:
            - description: Epoch milliseconds.
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        current:
          description: >-
            Whether the subscription is current (statuses "active", "trialing",
            "past_due", "cancellation_scheduled", or "credit_trial")
          type: boolean
      required:
        - id
        - createdAt
        - updatedAt
        - livemode
        - startDate
        - customerId
        - organizationId
        - status
        - defaultPaymentMethodId
        - backupPaymentMethodId
        - trialEnd
        - currentBillingPeriodStart
        - currentBillingPeriodEnd
        - cancellationReason
        - replacedBySubscriptionId
        - isFreePlan
        - doNotCharge
        - priceId
        - runBillingAtPeriodStart
        - interval
        - intervalCount
        - billingCycleAnchorDate
        - name
        - renews
        - pricingModelId
        - current
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````