> ## 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 new subscription



## OpenAPI

````yaml /openapi.yaml post /v2/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:
  /v2/subscriptions:
    post:
      tags:
        - SubscriptionV2
      summary: Create a new subscription
      operationId: post-v2-subscriptions
      parameters:
        - schema:
            type: string
          in: query
          name: expand
          description: can be used to fetch full esim object with `expand=esim`
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - planParams
              properties:
                planParams:
                  type: object
                  x-stoplight:
                    id: poqh72rbzjvon
                  required:
                    - activationType
                  properties:
                    planId:
                      type: string
                      x-stoplight:
                        id: zxwc7g1hrj2vm
                      description: Id of the plan to be attached to this subscription
                    plan:
                      type: object
                      x-stoplight:
                        id: y162heyjf2kw9
                      required:
                        - dataMBs
                        - periodDays
                        - coverageId
                      properties:
                        dataMBs:
                          type: integer
                          x-stoplight:
                            id: q36neqpnfzm37
                        periodDays:
                          type: integer
                          x-stoplight:
                            id: ozsotr4sd8eta
                        coverageId:
                          type: string
                          x-stoplight:
                            id: idcg7c0lzs0sk
                        periodIterations:
                          type: integer
                          x-stoplight:
                            id: lc58itz2f7sps
                          minimum: 1
                        throttledSpeedKbps:
                          x-stoplight:
                            id: 7sqihkfr4yt13
                          type: integer
                          description: >-
                            Acceptable values are 128, 256, 384, 512, 1024,
                            3072, 5120, 7680, 10240, 20480
                    activationType:
                      x-stoplight:
                        id: uys6wxo4zjmk8
                      enum:
                        - NOW
                        - FIRST_USAGE
                        - SCHEDULED
                    activationAt:
                      type: number
                      x-stoplight:
                        id: xqdmipbuo75xv
                      description: >-
                        Unix timestamp at which the plan should be activated.
                        Only required when activation type is SCHEDULED.
                esim:
                  type: string
                  x-stoplight:
                    id: y4ye5flr4r7w6
                  description: |
                    ICCID of the preferred esim which is unused
                metadata:
                  type: string
                  x-stoplight:
                    id: 0j2z9hll4u1pt
                  description: |
                    Any string metadata you want to provide
        description: Exactly one of the planId or plan should be provided
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionV2'
components:
  schemas:
    SubscriptionV2:
      title: SubscriptionV2
      x-stoplight:
        id: 42fsx0aepeykb
      type: object
      examples:
        - id: sub2_wyr3ios2
          esim:
            id: esim_iddfsdf1
            iccid: 891004234814455936F
            activationCode: LPA:1$smdp.bondio.com$23LKL-32340MX-20349LIH
            msisdn: '449898978234'
            label: alpha
          createdAt: 123143243
          metadata: tag1
      required:
        - id
        - esim
        - createdAt
        - metadata
      properties:
        id:
          type: string
          x-stoplight:
            id: onh9j4vuq17i4
        esim:
          x-stoplight:
            id: pv6dew9qsgk9l
          anyOf:
            - $ref: '#/components/schemas/Esim'
              x-stoplight:
                id: rtb5i2vo3h6hm
            - type: string
              x-stoplight:
                id: ta8rwiie5i1fr
              description: ICCID of the esim
        createdAt:
          type: integer
          x-stoplight:
            id: u0ow9hvyo6nxi
        metadata:
          type:
            - string
            - 'null'
          x-stoplight:
            id: pvg1jphh2w9q0
    Esim:
      title: Esim
      x-stoplight:
        id: wuubfexjvtk38
      type: object
      examples:
        - iccid: 891004234814455936F
          activationCode: LPA:1$smdp.bondio.com$23LKL-32340MX-20349LIH
          msisdn: '449898978234'
          label: alpha
      required:
        - iccid
        - msisdn
        - activationCode
        - label
      properties:
        iccid:
          type: string
          x-stoplight:
            id: 77c3kygb5y0ym
        msisdn:
          type: string
          x-stoplight:
            id: 5lsad34xx9dp2
        activationCode:
          type: string
          x-stoplight:
            id: 55rvmfcomwgh9
        label:
          type: string
          x-stoplight:
            id: 0xaawmb6yf9d8
          description: The plan-esim compatibility label
        availability:
          $ref: '#/components/schemas/Availability'
          x-stoplight:
            id: 214dmj7esx16g
    Availability:
      title: Availability
      x-stoplight:
        id: 9dike6s5qmy6j
      type: object
      examples:
        - gracePeriodFinishAction: LAPSE
          gracePeriodFinishAt: 1768481221
          currentState: ACTIVE
      required:
        - gracePeriodFinishAction
        - gracePeriodFinishAt
        - currentState
      properties:
        gracePeriodFinishAction:
          x-stoplight:
            id: zx89smtdjw4vv
          enum:
            - LAPSE
            - PRESERVE
          description: >-
            The action that would be taken by the system once the grace period
            is finished.
        gracePeriodFinishAt:
          type: integer
          x-stoplight:
            id: d9jtor8yynr7y
          description: Timestamp at which the grace period finishes.
        currentState:
          x-stoplight:
            id: o4y33otft632k
          enum:
            - ACTIVE
            - LAPSED
      x-internal: false
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````