Balance

List eSIM balance updates

Experimental. This endpoint is still settling — its request and response shape may change without a deprecation cycle.

Returns completed balance updates, newest first.

get/profiles/{profileReference}/esims/{esimReference}/balance/updates

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)

Query parameters

limitinteger

Maximum number of items to return (1-100)

Default20

cursorstring

Opaque cursor token for fetching the next page. Pass the nextCursor value from a previous response.

typestring

Filter by update type

Optionscreditdebit

sourcestring

Filter by update source

Optionsclientprovider

fromstring · date-time

Include updates created at or after this timestamp

untilstring · date-time

Include updates created at or before this timestamp

clientTransactionIdstring

Filter by client transaction identifier

providerTransactionIdstring

Filter by provider transaction identifier

Responses

200Balance update historyapplication/json

Show response body

dataarray of EsimBalanceUpdaterequired

Show properties

profileReferencestringrequired

esimReferencestringrequired

typestringrequired

Optionscreditdebit

sourcestringrequired

Optionsclientprovider

amountintegerrequired

Update amount in integer minor currency units

balanceAfterintegerrequired

Balance after this update

overdraftAmountintegerrequired

Amount not covered when balance reached zero

currencystringrequired

Three-letter ISO 4217 currency code

reasonstringrequired

detailstring | nullrequired

clientTransactionIdstring | nullrequired

Client transaction identifier, present for client updates

providerTransactionIdstring | nullrequired

External transaction identifier when available

occurredAtstring | null · date-timerequired

When the balance update occurred

createdAtstring · date-timerequired

When the update was recorded

paginationobjectrequired

Show properties

limitintegerrequired

Maximum items per page

hasMorebooleanrequired

Whether there are more items after this page

nextCursorstring | nullrequired

Opaque cursor token for the next page. Null when there are no more results.

400Bad request - invalid parameters 401Unauthorized - missing or invalid API key 403Forbidden - client does not have access to this resource 404Resource not found 422Request cannot be applied to the current resource 429Rate limit exceeded 500Internal server error

Request

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

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

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

$client = new GuzzleHttp\Client();

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

package main

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

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

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

}

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

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

requests.get(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/balance/updates",
    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}/balance/updates', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN'
  ]
]);

package main

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

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

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

}

Response

{
  "data": [
    {
      "profileReference": "1234567890123456",
      "esimReference": "123456000000000001",
      "type": "credit",
      "source": "client",
      "amount": 500,
      "balanceAfter": 1500,
      "overdraftAmount": 0,
      "currency": "EUR",
      "reason": "topup",
      "detail": "Top-up via partner app",
      "clientTransactionId": "example-credit-tx-001",
      "providerTransactionId": "external-tx-001",
      "occurredAt": "2026-01-15T09:30:00Z",
      "createdAt": "2026-01-15T09:30:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "MjAyNC0wMS0xNVQxMDowMDowMC4wMDBaOjQy"
  }
}

{
  "type": "https://developers.firsty.app/errors/validation-failed",
  "title": "Validation failed",
  "status": 400,
  "detail": "Request contains invalid fields",
  "errors": [
    {
      "field": "planReference",
      "detail": "Must be a valid 14-character plan reference"
    }
  ]
}