Packages

Remove a package

Removes a package from an eSIM. The package status will be set to 'removed'.

delete/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)

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 by their JSON content. Object key order, including in nested objects, and whitespace do not affect matching. 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 request body matching

Best Practices:

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

Responses

200Package removed successfully (idempotent - returns same result if already removed)application/json

Show response body

dataobjectoptional

Show properties

packageReferencestringoptional

Package reference identifier (23-character opaque token)

statusstringoptional

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

updatedAtstring · date-timeoptional

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. 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}' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Idempotency-Key: <x-idempotency-key>'

fetch('https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Idempotency-Key': '<x-idempotency-key>'
  }
})

requests.delete(
    "https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Idempotency-Key": "<x-idempotency-key>"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'X-Idempotency-Key' => '<x-idempotency-key>'
  ]
]);

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("DELETE", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	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))

}

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")
    .header("X-Idempotency-Key", "<x-idempotency-key>")
    .method("DELETE", 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}' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Idempotency-Key: <x-idempotency-key>'

fetch('https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Idempotency-Key': '<x-idempotency-key>'
  }
})

requests.delete(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Idempotency-Key": "<x-idempotency-key>"
    }
)

$client = new GuzzleHttp\Client();

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

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("DELETE", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	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))

}

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")
    .header("X-Idempotency-Key", "<x-idempotency-key>")
    .method("DELETE", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response

{
  "data": {
    "packageReference": "C123456XYZDUSR_A1B2C3D4",
    "status": "pending",
    "updatedAt": "2026-01-15T09:30:00Z"
  }
}

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