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

# Create subscription

> Creates a new subscription.



## OpenAPI

````yaml post /subscriptions
openapi: 3.0.1
info:
  title: Plude
  description: Headless subscription management and recurring billing.
  termsOfService: https://plude.com/terms
  contact:
    name: Corporate Contact
    url: https://plude.com/contact
  license:
    name: License
    url: https://plude.com/license
  version: v4.2024.7.1
servers: []
security:
  - Bearer: []
paths:
  /subscriptions:
    post:
      tags:
        - Subscriptions
      summary: Create subscription
      description: Creates a new subscription.
      parameters:
        - name: x-environment
          in: header
          description: >-
            Configure which environment the request will handle. If the provided
            credentials do not allow access to this specified environment, a 403
            Forbidden response is returned.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Internal Server Error
components:
  schemas:
    CreateSubscriptionRequest:
      required:
        - currency
        - customerId
        - start
      type: object
      properties:
        description:
          type: string
          description: A description, meant to be displayable to the customer.
          nullable: true
        currency:
          type: string
          description: >-
            Three-letter ISO currency code, in lowercase. Must be a supported
            currency (https://go.plude.io/h11101).
          nullable: true
        customerId:
          type: string
          description: Id of the customer to subscribe.
          format: uuid
        start:
          type: string
          description: Start of the current term of the subscription.
          format: date
        end:
          type: string
          description: "End of the current term of the subscription. If null the subscription is evergreen. \r\nAt the end of term the subscription will automatically renew if 'autoRenewal' is set to true."
          format: date
          nullable: true
        autoRenewal:
          type: boolean
          description: >-
            If true, the subscription will automatically renew at the end of the
            term. 'End' must be set.
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/CreateSubscriptionItemRequest'
          description: >-
            A list of up to 20 subscription items, each with an attached price
            and product.
          nullable: true
        metaData:
          type: object
          additionalProperties:
            type: string
          description: >-
            Set of key-value pairs that you can freely use to store additional
            information about your subscription.
          nullable: true
        bookAndSettle:
          $ref: '#/components/schemas/BookAndSettleOptions'
      additionalProperties: false
    Subscription:
      type: object
      properties:
        id:
          type: string
          description: Id of subscription.
          format: uuid
        handle:
          type: string
          description: A unique handle of the subscription.
          nullable: true
        currency:
          type: string
          description: Currency of the subscription.
          format: currency
          example: USD
        term:
          $ref: '#/components/schemas/DatePeriod'
        autoRenewal:
          type: boolean
          description: >-
            For termed subscription, auto renewal is optional and will
            automatically renew the subscription.
        items:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionItem'
          description: Items of the subscription.
          nullable: true
        createdAt:
          type: string
          format: date-time
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    CreateSubscriptionItemRequest:
      required:
        - priceId
        - productId
      type: object
      properties:
        quantity:
          type: number
          description: >-
            Quantity of the item to be added to the subscription item. Default
            0.
          format: double
        productId:
          type: string
          description: Id of product to attach to the subscription item.
          format: uuid
        priceId:
          type: string
          description: Id of the price to attach to the subscription item.
          format: uuid
        billAt:
          type: string
          description: >-
            Sets the next billing date of the item. You should optionally set
            the start date of the billing period.
          format: date-time
          nullable: true
        periodFrom:
          type: string
          description: "Sets the start of the item period.\r\nIf specified, the item period is calculated from this date. Otherwise 'billAt' is used. \r\nItem period applies to invoice item upon billing."
          format: date
          nullable: true
        prorate:
          $ref: '#/components/schemas/ProrationOptions'
      additionalProperties: false
    BookAndSettleOptions:
      type: object
      properties:
        book:
          $ref: '#/components/schemas/BookAsEnum'
      additionalProperties: false
    DatePeriod:
      type: object
      properties:
        start:
          type: string
          format: date
        end:
          type: string
          format: date
          nullable: true
      additionalProperties: false
    SubscriptionItem:
      type: object
      properties:
        id:
          type: string
          description: Id of the subscription item.
          format: uuid
        billAt:
          type: string
          description: >-
            Date and time when to bill the subscription item. Items that bill on
            the same time is grouped on the same invoice.
          format: date-time
          nullable: true
        period:
          $ref: '#/components/schemas/DatePeriod'
        quantity:
          type: number
          description: The quantity or count of units to be billed. Precision to 4.
          format: double
        product:
          $ref: '#/components/schemas/SubscriptionItemProduct'
        price:
          $ref: '#/components/schemas/SubscriptionItemPrice'
      additionalProperties: false
    ProrationOptions:
      type: object
      properties:
        strategy:
          $ref: '#/components/schemas/ProrationStrategy'
        fromDate:
          type: string
          description: The date to prorate from.
          format: date
      additionalProperties: false
    BookAsEnum:
      enum:
        - draft
        - invoice
        - ammendment
      type: string
    SubscriptionItemProduct:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          nullable: true
      additionalProperties: false
    SubscriptionItemPrice:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          nullable: true
      additionalProperties: false
    ProrationStrategy:
      enum:
        - no_proration
        - remaining_period
        - full_period
      type: string
  securitySchemes:
    Bearer:
      type: http
      description: "JWT Authorization header using the Bearer scheme. \r\n\r\n Enter 'Bearer' [space] and then your token in the text input below.\r\n\r\nExample: \"Bearer 12345abcdef\""
      scheme: Bearer

````