BalanceExperimental

Create eSIM balance update

Applies a credit or debit. clientTransactionId makes retries idempotent; this endpoint does not use X-Idempotency-Key. An eSIM whose balance accepts credits only refuses a debit with 422 and code balance_operation_not_supported. Before such an eSIM is activated, a credit returns 409 with code balance_not_available.

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

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

typestringrequired

Optionscreditdebit

amountintegerrequired

Update amount in integer minor currency units

Responses

200Existing update returned for an idempotent replayapplication/json

Show response body

dataobject

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

201Balance update createdapplication/json

Show response body

dataobject

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/updates' \
  --request POST \
  --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",
  "type": "credit",
  "amount": 500
}'

fetch('https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/balance/updates', {
  method: 'POST',
  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',
    type: 'credit',
    amount: 500
  })
})

requests.post(
    "https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/balance/updates",
    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",
      "type": "credit",
      "amount": 500
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/balance/updates', [
  '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',
    'type' => 'credit',
    'amount' => 500
  ]
]);

package main

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

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

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

	req, _ := http.NewRequest("POST", 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/updates"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"currency\": \"EUR\",\n  \"reason\": \"topup\",\n  \"detail\": \"Top-up via partner app\",\n  \"clientTransactionId\": \"example-credit-tx-001\",\n  \"type\": \"credit\",\n  \"amount\": 500\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/updates' \
  --request POST \
  --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",
  "type": "credit",
  "amount": 500
}'

fetch('https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/balance/updates', {
  method: 'POST',
  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',
    type: 'credit',
    amount: 500
  })
})

requests.post(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/balance/updates",
    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",
      "type": "credit",
      "amount": 500
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/balance/updates', [
  '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',
    'type' => 'credit',
    'amount' => 500
  ]
]);

package main

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

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

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

	req, _ := http.NewRequest("POST", 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/updates"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"currency\": \"EUR\",\n  \"reason\": \"topup\",\n  \"detail\": \"Top-up via partner app\",\n  \"clientTransactionId\": \"example-credit-tx-001\",\n  \"type\": \"credit\",\n  \"amount\": 500\n}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.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"
  }
}

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

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