# Create Subscriptions

This endpoint allows users to create a new subscription for a SIM. By sending a POST request to the specified URL, users can initiate the subscription process with the necessary parameters.
The optional active_period field controls when the subscription becomes active and (optionally) when it expires.

Endpoint: POST /v3/subscription
Version: 1.0.0
Security: ApiKeyAuth

## Request fields (application/json):

  - `iccid` (string)
    ICCID of the SIM (eSIM or Physical SIM). If not provided, the API will automatically select a free eSIM for the specified plan label. If no free eSIM is available for that label, a 404 error will be returned.
    Example: "8948010000031324502"

  - `metadata` (string, required)
    Example: "usa recurring plan"

  - `plan_id` (string, required)
    Example: "0a3ee1d6-fe5e-4561-91a0-d4649aaf0754"

  - `active_period` (object,null)
    Optional activation window for the subscription.

Non‑recurring plans

- active_period is optional.
- When active_period is provided, both start and end
  are required.
- The start and end values are used as the start and end
  date and time for the active period of the package and
  override any validity period configured in the
  package template.
- When active_period is not provided, the package uses
  the default behavior: activation at first use.

Recurring plans

- active_period is optional.
- When active_period is provided, start is required and
  end is optional.
- If active_period is not provided, the recurring
  subscription also uses the default behavior: activation at
  first use.

When a Start date is provided for a recurring plan:

- Start date in the past (maximum 24 hours): the first
  subscriber package is created immediately.
- Start date in the future but within the next 12 hours: the
  first subscriber package is also created immediately.
- Start date more than 12 hours in the future: no subscriber
  package is created immediately; the first subscriber package
  will be created by the system 12 hours before its
  activation time.

  - `active_period.start` (string)
    Desired activation start time (ISO 8601, UTC).
- Non‑recurring plans: required when active_period
  is provided and must be sent together with end.
- Recurring plans: required when active_period is
  provided. You may send only start without end.
    Example: "2025-12-10T15:03:28.533603"

  - `active_period.end` (string,null)
    Desired expiration time (ISO 8601, UTC).
- Non‑recurring plans: required when active_period
  is provided.
- Recurring plans: optional. If omitted, the recurring
  package uses the plan’s configured validity and default
  activation behavior.
    Example: "2025-12-20T15:03:28.533603"

## Response 201 fields (application/json):

  - `subscription_id` (string, required)
    The unique identifier for the created subscription
    Example: "a3b60fe5-a6ae-4b33-b5b0-9fae1832aa64"

  - `created_at` (string, required)
    Timestamp indicating when the subscription was created
    Example: "2025-08-08T11:05:57.703Z"

  - `activation_at` (string,null)
    Present only when active_period was provided in the request.
The value reflects the actual activation time reported by the underlying system when available. If the underlying system does not return an activation timestamp, the API falls back to active_period.start.
This field is omitted entirely if active_period was not sent.
    Example: "2025-12-10T15:03:28.533603Z"

  - `expiration_at` (string,null)
    Present only when active_period was provided in the request.
The value reflects the actual expiration time reported by the underlying system when available. If the underlying system does not return an expiration timestamp, the API falls back to active_period.end when provided; otherwise it remains null.
This field is omitted entirely if active_period was not sent.
    Example: "2025-12-20T15:03:28.533603Z"

  - `metadata` (string, required)
    The metadata provided in the request
    Example: "usa recurring plan"

  - `esimdata` (object, required)
    An object containing details about the eSIM or Physical SIM

  - `esimdata.esim_id` (string, required)
    The unique identifier for the eSIM
    Example: "65a89dca-349e-4278-95fb-a8fe2e9b281f"

  - `esimdata.iccid` (string, required)
    The Integrated Circuit Card Identifier for the eSIM
    Example: "8937103400004164763"

  - `esimdata.label` (string, required)
    A label associated with the eSIM
    Example: "blue"

  - `esimdata.lpa_string` (string,null)
    The LPA string associated with the eSIM
    Example: "LPA:1$rsp-eu.redteamobile.com$0F222CA0C9B2F3A99457DADC94A4958C"

## Response 401 fields (application/json):

  - `error` (boolean, required)
    Indicates whether an error occurred during the request
    Example: true

  - `message` (string, required)
    Error message describing the unauthorized access
    Example: "Unauthorized: API key is missing"

## Response 404 fields (application/json):

  - `error` (boolean, required)
    Example: true

  - `message` (string, required)
    Example: "No available eSIM record found for the specified plan label"