Skip to content

Create Subscriptions

Request

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.

Calling this endpoint again with the same iccid uses the existing top-up path and updates customer_email and tags on the current subscription. metadata is only written when the subscription is first created; a new value sent during top-up is ignored. Each tags write replaces the complete existing map rather than merging with it.

Validation failures identify the invalid field. For example, an invalid email returns customer_email: Invalid email address instead of the generic Validation error message.

Security
ApiKeyAuth
Bodyapplication/json
iccidstring

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"
metadatastringrequired
Example:"usa recurring plan"
plan_idstringrequired
Example:"0a3ee1d6-fe5e-4561-91a0-d4649aaf0754"
customer_emailstring, (email)

Optional email address associated with the customer.

Example:"customer@example.com"
tagsobject

Optional flat string-to-string map associated with the subscription. On every write, this map fully replaces any existing tags.

Example:
{
  "order_ref": "SHOP-98213",
  "source": "web_checkout",
  "customer_name": "John Doe"
}
active_periodobject or 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 plan.
  • 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 end is provided for a recurring plan, it is ignored.
  • 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.
POST
/v3/subscription
curl -i -X POST \
  'https://api.tellisim.com/v3/subscription?key=YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "plan_id": "0a3ee1d6-fe5e-4561-91a0-d4649aaf0754",
    "metadata": "usa recurring plan"
  }'

Responses

Subscription created successfully

Bodyapplication/json
subscription_idstringrequired

The unique identifier for the created subscription

Example:"a3b60fe5-a6ae-4b33-b5b0-9fae1832aa64"
created_atstringrequired

Timestamp indicating when the subscription was created

Example:"2025-08-08T11:05:57.703Z"
activation_atstring or null, (date-time)

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_atstring or null, (date-time)

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"
metadatastringrequired

The metadata provided in the request

Example:"usa recurring plan"
customer_emailstring or null, (email)

The customer email provided in the request, or null if not set

Example:"customer@example.com"
tagsobject or null

The flat string-to-string tags map provided in the request, or null if not set

Example:
{
  "order_ref": "SHOP-98213",
  "source": "web_checkout",
  "customer_name": "John Doe"
}
esimdataobjectrequired

An object containing details about the eSIM or Physical SIM

Response
{
  "subscription_id": "a3b60fe5-a6ae-4b33-b5b0-9fae1832aa64",
  "created_at": "2025-08-08T11:05:57.703Z",
  "activation_at": "2025-12-10T15:03:28.533603Z",
  "expiration_at": "2025-12-20T15:03:28.533603Z",
  "metadata": "usa recurring plan",
  "customer_email": "customer@example.com",
  "tags": {
    "order_ref": "SHOP-98213",
    "source": "web_checkout",
    "customer_name": "John Doe"
  },
  "esimdata": {
    "esim_id": "65a89dca-349e-4278-95fb-a8fe2e9b281f",
    "iccid": "8937103400004164763",
    "label": "blue",
    "lpa_string": "LPA:1$rsp-eu.redteamobile.com$0F222CA0C9B2F3A99457DADC94A4958C"
  }
}