Balance

Create eSIM balance update

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

Applies a credit or debit. clientTransactionId makes retries idempotent; this endpoint does not use X-Idempotency-Key.

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

dataobjectrequired

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

201Balance update createdapplication/json

Show response body

dataobjectrequired

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

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/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/%7BprofileReference%7D/esims/%7BesimReference%7D/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))

}

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/%7BprofileReference%7D/esims/%7BesimReference%7D/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))

}

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",
  "title": "Validation failed",
  "status": 400,
  "detail": "Request contains invalid fields",
  "errors": [
    {
      "field": "planReference",
      "detail": "Must be a valid 14-character plan reference"
    }
  ]
}