Packages

Get package details

Retrieves detailed information about a specific package including usage data. Usage reflects what the network has reported so far, so recent activity can take a while to appear.

get/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}

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)

packageReferencestringrequired

Package reference identifier (23-character opaque token)

Responses

200Package detailsapplication/json

Show response body

dataobjectoptional

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

packagePlanobject

Show properties

planReferencestring

Unique plan reference. Format: {C/S}{6 chars}{3 random}{type}{country}{renewable}. C = client-specific, S = shared. Type: D = data, M = SMS, V = voice. Last char: R = recurring, N = non-recurring.

namestring

typestring

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

Examplesdatasmsvoice

capacityMbinteger | null

Data capacity in megabytes (for data packages, null for SMS/voice)

speedKbpsinteger | null

Speed cap in kilobits per second (for data packages, null for SMS/voice)

throttleCapacityMbinteger | null

Throttled data capacity in megabytes after main capacity is exhausted (null if no throttling)

throttleSpeedKbpsinteger | null

Throttled speed cap in kilobits per second after main capacity is exhausted (null if no throttling)

smsCountinteger | null

Number of SMS messages included (for SMS packages)

voiceSecondsinteger | null

Voice call seconds included (for voice packages)

validityobject

How long a package of this plan stays valid.

Show properties

unitstring

Extensible enum. minute, day (24 hours) or month, a calendar month that ends on the same day of the month, or on the last day of a shorter month.

Examplesdaymonth

countinteger

renewalobject | null

How often a recurring plan's allowance renews. Null for a non-recurring plan.

Show properties

unitstring

Extensible enum. minute, day (24 hours) or month, a calendar month that ends on the same day of the month, or on the last day of a shorter month.

Examplesdaymonth

countinteger

alignmentstring

Extensible enum. Where the plan's validity and renewal boundaries fall. relative: every boundary is counted from the moment the package's validity starts. calendar: every boundary falls on the 1st of the month.

Examplesrelativecalendar

validityMinutesinteger

Use validity. The validity in minutes, a month counted as 30 days.

countryCodestring

Country or region code for this plan (e.g. 'NL', 'EU', 'global')

recurringboolean

Whether this plan auto-renews when it expires

renewalPeriodMinutesinteger | null

Use renewal. The renewal cycle in minutes, a month counted as 30 days; null for a non-recurring plan.

typestring

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

Examplesdatasmsvoice

countryCodestring

statusstring

Pending means the order is accepted but not yet fully confirmed. Active means all required addons are confirmed. Legacy compatibility can represent pending packages as active and include them in active-filter results; webhook milestones remain the same.

Optionspendingactivethrottledexhaustedexpiredremoved

recurringboolean

Whether this package will auto-renew

activatedAtstring | null · date-time

expiresAtstring | null · date-time

createdAtstring · date-time

usageobject

Usage data for the package

Show properties

totalnumber | null

Total package capacity (MB for data, count for SMS, seconds for voice); null for a data package without a capacity limit

usednumber

Amount used

remainingnumber | null

Amount remaining; null when total is null

unitstring

Extensible enum. Unit a package's amounts are expressed in, determined by the package type: mb for data, seconds for voice and sms for text messages.

Examplesmbsecondssms

401Unauthorized - missing or invalid API key 403Forbidden - client does not have access to this resource 404Resource not found 429Rate limit exceeded. A `429` can also arrive without these headers or this body; handle it by its status code.500Internal server error

Request

curl 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

requests.get(
    "https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN'
  ]
]);

package main

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

func main() {
	requestUrl := "https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

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

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

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

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

curl 'https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

requests.get(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN'
  ]
]);

package main

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

func main() {
	requestUrl := "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

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

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

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

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response

{
  "data": {
    "packageReference": "C123456XYZDUSR_A1B2C3D4",
    "externalTransactionId": "order-12345",
    "profileReference": "string",
    "externalProfileId": "my-customer-123",
    "esimReference": "123456000000000001",
    "iccid": "string",
    "packagePlan": {
      "planReference": "C123456XYZDUSR",
      "name": "5GB - 30 Days - US",
      "type": "data",
      "capacityMb": 5120,
      "speedKbps": 100000,
      "throttleCapacityMb": 1024,
      "throttleSpeedKbps": 512,
      "smsCount": 100,
      "voiceSeconds": 3600,
      "validity": {
        "unit": "day",
        "count": 30
      },
      "renewal": {
        "unit": "day",
        "count": 30
      },
      "alignment": "relative",
      "validityMinutes": 43200,
      "countryCode": "US",
      "recurring": false,
      "renewalPeriodMinutes": null
    },
    "type": "data",
    "countryCode": "string",
    "status": "pending",
    "recurring": true,
    "activatedAt": "2026-01-15T09:30:00Z",
    "expiresAt": "2026-01-15T09:30:00Z",
    "createdAt": "2026-01-15T09:30:00Z",
    "usage": {
      "total": 5120,
      "used": 1234.5,
      "remaining": 3885.5,
      "unit": "mb"
    }
  }
}

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