BalanceExperimental

Set eSIM balance

Sets an absolute target balance. clientTransactionId makes retries idempotent; this endpoint does not use X-Idempotency-Key. An eSIM whose balance accepts credits only refuses it with 422 and code balance_operation_not_supported.

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

dataobject

Show properties

profileReferencestring

esimReferencestring

currencystring

Three-letter ISO 4217 currency code

balanceinteger

Current balance in integer minor currency units

updatedAtstring · date-time

updateobject | null

Applied update, or null when balance was already at target

Show properties

profileReferencestring

esimReferencestring

typestring

Optionscreditdebit

sourcestring

Who originated the update: client for your own credit, debit or set; provider for a movement the network applied; system for a movement we made on our own.

Optionsclientprovidersystem

amountinteger

Update amount in integer minor currency units

balanceAfterinteger

Balance after this update

overdraftAmountinteger

Amount not covered when balance reached zero

currencystring

Three-letter ISO 4217 currency code

reasonstring

detailstring | null

clientTransactionIdstring | null

Client transaction identifier, present for client updates

providerTransactionIdstring | null

External transaction identifier when available

occurredAtstring | null · date-time

When the balance update occurred

createdAtstring · date-time

When the update was recorded

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. A `429` can also arrive without these headers or this body; handle it by its status code.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/{profileReference}/esims/{esimReference}/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))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/balance"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Content-Type", "application/json")
    .method("PUT", HttpRequest.BodyPublishers.ofString("{\n  \"currency\": \"EUR\",\n  \"reason\": \"topup\",\n  \"detail\": \"Top-up via partner app\",\n  \"clientTransactionId\": \"example-credit-tx-001\",\n  \"balance\": 1500\n}"))
    .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}/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/{profileReference}/esims/{esimReference}/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))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/balance"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Content-Type", "application/json")
    .method("PUT", HttpRequest.BodyPublishers.ofString("{\n  \"currency\": \"EUR\",\n  \"reason\": \"topup\",\n  \"detail\": \"Top-up via partner app\",\n  \"clientTransactionId\": \"example-credit-tx-001\",\n  \"balance\": 1500\n}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response

{
  "data": {
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "currency": "EUR",
    "balance": 1500,
    "updatedAt": "2026-01-15T09:30:00Z",
    "update": {
      "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"
    }
  }
}

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