Packages

Order a package

Orders a package for an eSIM. Each package plan is specific to a region and has a recurring setting (one-time or auto-renewing).

post/profiles/{profileReference}/esims/{esimReference}/packages

Authorization

Authorization: Bearer {token} — an OAuth2 access token from the client-credentials flow. How authentication works

Path parameters

profileReferencestringrequired

The eSIM's profile reference (16-digit numeric string)

esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

Headers

X-Idempotency-Keystring

Optional idempotency key for mutating requests (POST, PATCH). If provided, duplicate requests with the same key within 48 hours will return the cached original response without duplicating side effects.

Behavior:

Same key + same request body → returns cached response (prevents duplicate operations)
Same key + different request body → returns 422 error
Same key + in-flight request → returns 409 error with Retry-After header
Keys expire after 48 hours

Request Body Matching: Request bodies are compared using a deterministic fingerprint. The fingerprint is computed by canonicalizing the JSON (sorting object keys recursively) and hashing with SHA-256. This means:

{"a":1,"b":2} and {"b":2,"a":1} are treated as identical ✓
Whitespace differences are ignored ✓
URL parameters and headers are NOT included in the fingerprint

Best Practices:

Use UUIDs or client-generated unique strings
Store keys on your side to support retries
Don't reuse keys across different operations

Request body

application/json · required

planReferencestringrequired

Plan reference identifier (14-character opaque token)

externalTransactionIdstring

Optional client-provided external transaction ID to associate with this package.

Responses

200Package ordered successfullyapplication/json

Show response body

dataobject

Show properties

packageReferencestring

Package reference identifier (23-character opaque token)

externalTransactionIdstring | null

The client's external transaction ID if provided

profileReferencestring

externalProfileIdstring | null

The client's external profile ID if provided

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstring

planReferencestring

Plan reference identifier (14-character opaque token)

typestring

Package type: data for mobile data, sms for text messaging, voice for calls

Optionsdatasmsvoice

countryCodestring

statusstring

Optionsactivethrottledexhaustedexpiredremoved

recurringboolean

Whether this package will auto-renew

activatedAtstring | null · date-time

expiresAtstring | null · date-time

400Invalid request or package cannot be ordered for this regionapplication/problem+json

Show response body

typestring · urirequired

URI reference to error documentation

titlestringrequired

Short, consistent error summary

statusintegerrequired

HTTP status code

detailstringrequired

Human-readable explanation specific to this occurrence

401Unauthorized - missing or invalid API key 403Forbidden - client does not have access to this resource 404Resource not found 409Request with this idempotency key is still being processed 422Idempotency key was previously used with a different request body 429Rate limit exceeded 500Internal server error 503Service temporarily unavailable. Safe to retry.

Request

curl 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages' \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '{
  "planReference": "C123456XYZDUSR",
  "externalTransactionId": "order-12345"
}'

fetch('https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'X-Idempotency-Key': '<x-idempotency-key>'
  },
  body: JSON.stringify({
    planReference: 'C123456XYZDUSR',
    externalTransactionId: 'order-12345'
  })
})

requests.post(
    "https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
      "X-Idempotency-Key": "<x-idempotency-key>"
    },
    json={
      "planReference": "C123456XYZDUSR",
      "externalTransactionId": "order-12345"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json',
    'X-Idempotency-Key' => '<x-idempotency-key>'
  ],
  'json' => [
    'planReference' => 'C123456XYZDUSR',
    'externalTransactionId' => 'order-12345'
  ]
]);

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://connect.firsty.app/api/v3/profiles/%7BprofileReference%7D/esims/%7BesimReference%7D/packages"

	payload := strings.NewReader(`{
  "planReference": "C123456XYZDUSR",
  "externalTransactionId": "order-12345"
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

curl 'https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages' \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '{
  "planReference": "C123456XYZDUSR",
  "externalTransactionId": "order-12345"
}'

fetch('https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'X-Idempotency-Key': '<x-idempotency-key>'
  },
  body: JSON.stringify({
    planReference: 'C123456XYZDUSR',
    externalTransactionId: 'order-12345'
  })
})

requests.post(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
      "X-Idempotency-Key": "<x-idempotency-key>"
    },
    json={
      "planReference": "C123456XYZDUSR",
      "externalTransactionId": "order-12345"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json',
    'X-Idempotency-Key' => '<x-idempotency-key>'
  ],
  'json' => [
    'planReference' => 'C123456XYZDUSR',
    'externalTransactionId' => 'order-12345'
  ]
]);

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://connect.test.firsty.app/api/v3/profiles/%7BprofileReference%7D/esims/%7BesimReference%7D/packages"

	payload := strings.NewReader(`{
  "planReference": "C123456XYZDUSR",
  "externalTransactionId": "order-12345"
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Response

{
  "data": {
    "packageReference": "C123456XYZDUSR_A1B2C3D4",
    "externalTransactionId": "order-12345",
    "profileReference": "string",
    "externalProfileId": "my-customer-123",
    "esimReference": "123456000000000001",
    "iccid": "string",
    "planReference": "C123456XYZDUSR",
    "type": "data",
    "countryCode": "string",
    "status": "active",
    "recurring": true,
    "activatedAt": "2026-01-15T09:30:00Z",
    "expiresAt": "2026-01-15T09:30:00Z"
  }
}

{
  "type": "https://developers.firsty.app/errors/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "eSIM not found"
}

{
  "type": "https://developers.firsty.app/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing bearer token"
}