Balance

Set eSIM balance

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

Sets an absolute target balance. clientTransactionId makes retries idempotent; this endpoint does not use X-Idempotency-Key.

put/profiles/{profileReference}/esims/{esimReference}/balance

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)

Request body

application/json · required

currencystringrequired

Three-letter ISO 4217 currency code

reasonstringrequired

Machine-readable reason

detailstring

Optional human-readable context

clientTransactionIdstringrequired

Client identifier used for idempotency

balanceintegerrequired

Target balance in integer minor currency units

Responses

200Balance set or already at targetapplication/json

Show response body

dataobjectrequired

Show properties

profileReferencestringrequired

esimReferencestringrequired

currencystringrequired

Three-letter ISO 4217 currency code

balanceintegerrequired

Current balance in integer minor currency units

updatedAtstring · date-timerequired

updateone of EsimBalanceUpdate | option 2required

Applied update, or null when balance was already at target

Show properties

EsimBalanceUpdateobject

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

option 2null

400Bad request - invalid parameters 401Unauthorized - missing or invalid API key 403Forbidden - client does not have access to this resource 404Resource not found 409Another operation is already in progress 422Request cannot be applied to the current resource 429Rate limit exceeded 500Internal server error 502Temporary service failure 503Service temporarily unavailable. Safe to retry.

Request

curl 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/balance' \
  --request PUT \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "currency": "EUR",
  "reason": "topup",
  "detail": "Top-up via partner app",
  "clientTransactionId": "example-credit-tx-001",
  "balance": 1500
}'

fetch('https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/balance', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    currency: 'EUR',
    reason: 'topup',
    detail: 'Top-up via partner app',
    clientTransactionId: 'example-credit-tx-001',
    balance: 1500
  })
})

requests.put(
    "https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/balance",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
    },
    json={
      "currency": "EUR",
      "reason": "topup",
      "detail": "Top-up via partner app",
      "clientTransactionId": "example-credit-tx-001",
      "balance": 1500
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('PUT', 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/balance', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json'
  ],
  'json' => [
    'currency' => 'EUR',
    'reason' => 'topup',
    'detail' => 'Top-up via partner app',
    'clientTransactionId' => 'example-credit-tx-001',
    'balance' => 1500
  ]
]);

package main

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

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

	payload := strings.NewReader(`{
  "currency": "EUR",
  "reason": "topup",
  "detail": "Top-up via partner app",
  "clientTransactionId": "example-credit-tx-001",
  "balance": 1500
}`)

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

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("Content-Type", "application/json")

	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' \
  --request PUT \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "currency": "EUR",
  "reason": "topup",
  "detail": "Top-up via partner app",
  "clientTransactionId": "example-credit-tx-001",
  "balance": 1500
}'

fetch('https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/balance', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    currency: 'EUR',
    reason: 'topup',
    detail: 'Top-up via partner app',
    clientTransactionId: 'example-credit-tx-001',
    balance: 1500
  })
})

requests.put(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/balance",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
    },
    json={
      "currency": "EUR",
      "reason": "topup",
      "detail": "Top-up via partner app",
      "clientTransactionId": "example-credit-tx-001",
      "balance": 1500
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('PUT', 'https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/balance', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json'
  ],
  'json' => [
    'currency' => 'EUR',
    'reason' => 'topup',
    'detail' => 'Top-up via partner app',
    'clientTransactionId' => 'example-credit-tx-001',
    'balance' => 1500
  ]
]);

package main

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

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

	payload := strings.NewReader(`{
  "currency": "EUR",
  "reason": "topup",
  "detail": "Top-up via partner app",
  "clientTransactionId": "example-credit-tx-001",
  "balance": 1500
}`)

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

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("Content-Type", "application/json")

	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",
    "currency": "EUR",
    "balance": 1500,
    "updatedAt": "2026-01-15T09:30:00Z"
  }
}

{
  "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"
    }
  ]
}