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

# Create a subscription

> Creates a mobile plan subscription with the given plan.



## OpenAPI

````yaml /openapi.yaml post /v1/subscriptions
openapi: 3.1.0
info:
  title: Bondio API
  version: '1.0'
  description: Bondio's REST API for eSIM provisioning, plans, subscriptions, and billing.
servers:
  - url: https://api.bondio.co
    description: prod
security:
  - BearerAuth: []
tags:
  - name: Plan
  - name: Esim
  - name: Subscription
  - name: Addon Attachment
paths:
  /v1/subscriptions:
    post:
      tags:
        - Subscription
      summary: Create a subscription
      description: Creates a mobile plan subscription with the given plan.
      operationId: create-a-asubscription
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - planId
              properties:
                planId:
                  type: string
                  x-stoplight:
                    id: 8z3qf9eojknxf
                  description: >-
                    The unique id of a plan. The plan must not be archived or an
                    addon.
                plan:
                  type: object
                  x-stoplight:
                    id: 6zg0uyhr8tp0z
                  properties:
                    coverageId:
                      type: string
                      x-stoplight:
                        id: qhkxw3zwxaxmc
                    dataMBs:
                      type: integer
                      x-stoplight:
                        id: yh7uffjzbzkx7
                    periodDays:
                      type: integer
                      x-stoplight:
                        id: uynetxeflk86p
            examples:
              Example 1:
                value:
                  planId: plan.id1
        description: Exactly one of the `plan` or `planId` must be provided.
      responses:
        '200':
          description: Returns the created subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
              examples: {}
        '412':
          description: >
            The request couldn't be processed. The possible reasons are -

            1. The planId is invalid. Either it doesn't exist or is archived or
            is an addon plan.

            2. There is no suitable eSIM left in your account to be assigned to
            this subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Subscription:
      title: Subscription
      x-stoplight:
        id: ytddekchv3vcj
      type: object
      x-extension-1: null
      examples:
        - id: sub.id1
          esimIccid: 891004234814455936F
          planId: plan_id1
          createdAt: 1707752560
          activatedAt: 1707778560
          expireAt: 1707799560
          purchasedAllowance:
            dataBytes: 102400001024
            voiceSeconds: 3660
            smsMessages: 100
          remainingAllownace:
            dataBytes: 1024
            voiceSeconds: 1800
            smsMessages: 50
          state: active
          metadata:
            devDefinedKey: someValue
          plan:
            name: Australia 1GB 7d recurring throttled
            dataMegaBytes: 1024
            periodDays: 1
            periodIterations: 7
            throttledSpeedKbps: 128
            label: sigma
            coverageProfileId: cvpr_dhl3zq9r
      required:
        - id
        - esimIccid
        - planId
        - plan
        - createdAt
        - activatedAt
        - expireAt
        - purchasedAllowance
        - remainingAllownace
        - state
        - metadata
      properties:
        id:
          type: string
          x-stoplight:
            id: o1nsg5f7izt82
        esimIccid:
          type: string
          x-stoplight:
            id: 3my975v0nfnkq
        planId:
          type: string
          x-stoplight:
            id: 93arprmverd34
          deprecated: true
        plan:
          $ref: '#/components/schemas/PlanForAttachment'
          x-stoplight:
            id: k0x1vkzw1pkj1
        createdAt:
          type: integer
          x-stoplight:
            id: v8guw2wy9im1t
        activatedAt:
          type:
            - integer
            - 'null'
          x-stoplight:
            id: g2rqdnefb38r2
        expireAt:
          type:
            - integer
            - 'null'
          x-stoplight:
            id: v6g6f0wqm62ap
        purchasedAllowance:
          $ref: '#/components/schemas/Allowance'
          x-stoplight:
            id: bxnnhkoqzanhs
        remainingAllownace:
          $ref: '#/components/schemas/Allowance'
          x-stoplight:
            id: kd24rhmpg022a
        state:
          x-stoplight:
            id: 3i29zhfc0fowz
          enum:
            - active
            - expired
            - ready
        metadata:
          type: object
          x-stoplight:
            id: zcgtfk8ulf58c
          additionalProperties:
            x-stoplight:
              id: b1yvb77uyd8o8
            type: string
    Error:
      type: object
      x-examples:
        Example 1:
          object: error
          code: invalidICCID
          details:
            - object: propertyErrorDetail
              code: propertyRequired
              message: Invalid value for property.
              property: property1
              suggestion: alternative_value
          documentation:
            - >-
              https://developers.gigs.com/docs/api/ZG9jOjExMTYzMDU0-error-handling
          hint: Parameter iccid must match /^([0-9]{19}F?|[0-9]{20})$/i
          message: Invalid ICCID format.
          type: invalid
      examples:
        - code: outOfInventory
          message: >-
            New subscription could not be created because the account is out of
            inventory
          docsUrl: https://bondio.stoplight.io/docs/bondio-api
      required:
        - code
        - message
        - docsUrl
      properties:
        code:
          type: string
          description: |-
            A machine-readable description of the error.

            Example: `outOfInventory`
        message:
          type: string
          description: A human readable description of the error
        docsUrl:
          type:
            - string
            - 'null'
          description: >-
            A URL to the docs page providing further information to resolve the
            error.
    PlanForAttachment:
      title: PlanForAttachment
      x-stoplight:
        id: odujx98nt7wac
      type: object
      examples:
        - name: Australia 1GB 7d
          dataMegaBytes: 1024
          periodDays: 1
          periodIterations: 7
          throttledSpeedKbps: 128
          label: alpha
          coverageProfileId: cvpr_ybrs38es
      x-internal: false
      properties:
        name:
          type: string
          deprecated: true
        dataMegaBytes:
          type: integer
        periodDays:
          type: integer
          description: Plan validity in days
        periodIterations:
          type: integer
          description: |
            Number of times the periodDays should be repeated.
          default: 1
        throttledSpeedKbps:
          type: integer
          description: >-
            Speed after allocated data is used up. The default zero means no
            usage allowed afterwards.
          default: 0
        label:
          type: string
          description: The plan-esim compatibility label
        coverageProfileId:
          type: string
          x-stoplight:
            id: 08gh0d0gwjx1r
    Allowance:
      title: Allowance
      x-stoplight:
        id: xprozbv6umr33
      type: object
      examples:
        - dataBytes: 1024
          voiceSeconds: 60
          smsMessages: 100
      properties:
        dataBytes:
          type:
            - integer
            - 'null'
          x-stoplight:
            id: cjcvtodo08pjs
          format: int64
          minimum: 0
        voiceSeconds:
          type:
            - integer
            - 'null'
          x-stoplight:
            id: 5lrv0ke2wi39u
        smsMessages:
          type:
            - integer
            - 'null'
          x-stoplight:
            id: 17ms5p0dzfm0m
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````