1. REST Services Manager API for Billing and Revenue Management
  2. Tasks
  3. Prepay Balance Management
  4. Top-up Balances

Get Top-up Balances

get

/topupBalance

Gets top-up balances that match the query criteria.

Request

Query Parameters
  • Retrieves the top-up balance associated with the balance group POID.
    Example:
    0.0.0.1+-balance_group+71659
  • The list of comma-separated fields to return in the response.
    Example:
    isAutoTopup,paymentMethod
  • Retrieves the specified top-up POID.
    Example:
    0.0.0.1+-topup+285083
  • Whether the request is for an automatic top up.
    Example:
    true
  • The maximum number of results to return. For example, use limit=10 to return the first 10 results only.
    Example:
    10
  • Retrieves the top-up balance associated with the login ID or device ID.
    Example:
    964-20210827-041409-0-9169--146802944-mum-54
  • The number of periods to execute the recharge operation. If not included, the topup occurs every period.
    Example:
    2
  • The number of results to offset the response by. For example, use offset=10 to return results 10 and higher.
    Example:
    10
  • Retrieves the top-up balance associated with the account POID or account number.
    Example:
    0.0.0.1 /account 10966 0
  • Retrieves the top-up balance associated with the specified service ID.
    Example:
    0.0.0.1+-service-telco-gsm+67479
  • The periodicity for the recharge operation, such as monthly, weekly, or daily.
    Example:
    daily
  • The type of underlying balance type, such as data or voice.
    Example:
    data

There's no request body for this operation.

Back to Top

Response

Supported Media Types

200 Response

The top-up balances were retrieved successfully.
Headers
Body ()
Root Schema : schema
Type: array
Show Source
Nested Schema : Topup Balance
Type: object
Title: Topup Balance
A top-up.
Show Source
Nested Schema : Quantity
Type: object
The amount in a given unit.
Show Source
Nested Schema : Bucket Ref
Type: object
Title: Bucket Ref
A reference to a bucket.
Show Source
Nested Schema : ChannelRef
Type: object
A reference to a channel.
Show Source
Nested Schema : impactedBucket
Type: array
A reference to the bucket impacted by the request.
Show Source
Nested Schema : Logical Resource Ref
Type: object
Title: Logical Resource Ref
A reference to a logical resource.
Show Source
Nested Schema : Party Account Ref
Type: object
Title: Party Account Ref
A reference to a party account.
Show Source
Nested Schema : PaymentRef
Type: object
A payment received at order time.
Show Source
Nested Schema : PaymentMethodRef
Type: object
The PaymentMethod reference. A payment method defines a specific means of payment, such as direct debit.
Match All
The PaymentMethod reference. A payment method defines a specific means of payment, such as direct debit.
Show Source
Nested Schema : Product Ref
Type: object
Title: Product Ref
A reference to a product.
Show Source
Nested Schema : relatedParty
Type: array
Parties related to the top-up.
Show Source
Nested Schema : Related Topup Balance
Type: object
Title: Related Topup Balance
A relationship between balance top-ups that defines whether a balance is the parent or child of another.
Show Source
Nested Schema : Related Party
Type: object
Title: Related Party
A party related to another object.
Show Source
Nested Schema : ImpactedBucket
Type: object
A bucket impacted by a balance top-up, adjustment, transfer, or reservation.
Show Source
Nested Schema : item
Type: array
Minimum Number of Items: 1
The impacted bucket items.
Show Source
Nested Schema : ImpactedBucketItem
Type: object
An impact item that affects an ImpactedBucket object.
Show Source
Nested Schema : EntityRef
Match All
The entity reference schema to be used for all entityRef class.
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Addressable
    The base schema for adressable entities.
  • EntityRef-allOf[2]
    The entity reference schema to be used for all entityRef class.
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Addressable
Type: object
The base schema for adressable entities.
Show Source
Nested Schema : EntityRef-allOf[2]
Type: object
The entity reference schema to be used for all entityRef class.
Show Source

400 Response

The request isn't valid.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source

401 Response

The client doesn't have the correct privileges.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source

403 Response

The request wasn't authorized.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source

404 Response

The requested resource couldn't be found.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source

405 Response

This method is not allowed.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source

409 Response

The request could not be processed due to the conflict with the existing state of the resource.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source

500 Response

The system encountered an internal error.
Body ()
Root Schema : Error
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Match All
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
The operation used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx).
Show Source
  • Extensible
    The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
  • Error-allOf[1]
Nested Schema : Extensible
Type: object
The Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means that the Entity described by the schema MUST be extended with the @type
Show Source
Nested Schema : Error-allOf[1]
Type: object
Show Source
Back to Top

Examples

The following example shows how to get top-up balances by submitting a GET request on the REST resource using cURL. For more information about cURL, see Use cURL.

The request uses query parameters to show two top-up balances for a specified account.

curl -X GET 'http://host:port/brm/prepayBalanceManagement/version/topupBalance?partyAccount.id=0.0.0.1+-account+6340627&limit=2'

Response Body

The following example shows the contents of the response body in JSON format.

[
   {
      "@baseType": "TopupBalance",
      "@schemaLocation": null,
      "@type": "TopupBalance",
      "amount": {
         "amount": 2.0,
         "units": "USD",
         "@baseType": null,
         "@schemaLocation": null,
         "@type": null
      },
      "bucket": {
         "id": "0.0.0.1+-balance_group+6344211+840+0",
         "href": "http://host:port/brm/prepayBalanceManagement/v4/bucket/0.0.0.1+-balance_group+6344211+840+0",
         "name": null,
         "@baseType": "BucketRef",
         "@schemaLocation": null,
         "@type": "BucketRef",
         "@referredType": null
      },
      "channel": null,
      "confirmationDate": "2025-09-20T11:45:02+05:30",
      "description": null,
      "href": "http://host:port/brm/prepayBalanceManagement/v4/topupBalance/0.0.0.1+-topup+6448982",
      "id": "0.0.0.1+-topup+6448982",
      "impactedBucket": [
         {
            "@baseType": "ImpactedBucket",
            "@schemaLocation": null,
            "@type": "ImpactedBucket",
            "amountAfter": {
               "amount": -2.0,
               "units": "USD",
               "@baseType": null,
               "@schemaLocation": null,
               "@type": null
            },
            "amountBefore": {
               "amount": 0.0,
               "units": "USD",
               "@baseType": null,
               "@schemaLocation": null,
               "@type": null
            },
            "bucket": {
               "id": "0.0.0.1+-balance_group+6344211+840+0",
               "href": "http://host:port/brm/prepayBalanceManagement/v4/bucket/0.0.0.1+-balance_group+6344211+840+0",
               "name": null,
               "@baseType": "BucketRef",
               "@schemaLocation": null,
               "@type": "BucketRef",
               "@referredType": null
            },
            "confirmationDate": null,
            "description": null,
            "item": [
               {
                  "@baseType": "ImpactedBucketItem",
                  "@schemaLocation": null,
                  "@type": "ImpactedBucketItem",
                  "amount": {
                     "amount": 2.0,
                     "units": "USD",
                     "@baseType": null,
                     "@schemaLocation": null,
                     "@type": null
                  },
                  "description": null,
                  "itemType": null,
                  "name": null,
                  "reason": null
               }
            ],
            "name": null,
            "requestedDate": null
         }
      ],
      "isAutoTopup": false,
      "logicalResource": {
         "@baseType": null,
         "@referredType": null,
         "@schemaLocation": null,
         "@type": null,
         "href": null,
         "id": null,
         "name": null,
         "value": ""
      },
      "numberOfPeriods": null,
      "partyAccount": {
         "id": "0.0.0.1+-account+6340627",
         "href": null,
         "description": null,
         "name": "Jane Mason",
         "status": "active",
         "@baseType": null,
         "@schemaLocation": null,
         "@type": "PartyAccountRef",
         "@referredType": null
      },
      "payment": {
         "id": "0.0.0.1+-item-payment+6450518",
         "href": "http://host:port/brm/payment/v4/payment/0.0.0.1+-item-payment+6450518",
         "name": "Billing Event Log",
         "amount": {
            "unit": "USD",
            "value": 2.0
         },
         "paymentDate": "2025-09-20T11:45:01+05:30",
         "@baseType": "Payment",
         "@schemaLocation": null,
         "@type": "Payment",
         "@referredType": null
      },
      "paymentMethod": {
         "id": "0.0.0.1+-payinfo-cc+6342675",
         "href": "http:/host:port/brm/paymentMethods/v1/paymentMethod/0.0.0.1+-payinfo-cc+6342675",
         "description": null,
         "isPreferred": true,
         "name": "PIN Payinfo Object",
         "status": null,
         "statusDate": null,
         "account": [
            {
               "id": "0.0.0.1+-account+6340627",
               "href": null,
               "description": null,
               "name": "Jane Mason",
               "@baseType": null,
               "@schemaLocation": null,
               "@type": null,
               "@referredType": null
            }
         ],
         "relatedParty": null,
         "validFor": null,
         "@baseType": null,
         "@schemaLocation": null,
         "@type": "tokenizedCard",
         "@referredType": null
      },
      "product": {
         "id": "0.0.0.1+-service-telco-gsm-telephony+6343955",
         "href": null,
         "name": "ServiceTelcoGsmTelephony",
         "@baseType": null,
         "@schemaLocation": null,
         "@type": "ProductRef",
         "@referredType": null
      },
      "reason": null,
      "recurringPeriod": null,
      "relatedParty": null,
      "relatedTopupBalance": null,
      "requestedDate": "2025-09-20T11:45:02+05:30",
      "requestor": null,
      "status": "CONFIRMED",
      "usageType": "monetary",
      "voucher": ""
   },
   {
      "@baseType": "TopupBalance",
      "@schemaLocation": null,
      "@type": "TopupBalance",
      "amount": {
         "amount": 20.0,
         "units": "USD",
         "@baseType": null,
         "@schemaLocation": null,
         "@type": null
      },
      "bucket": {
         "id": "0.0.0.1+-balance_group+4097444+840+0",
         "href": "http://host:port/brm/prepayBalanceManagement/v4/bucket/0.0.0.1+-balance_group+4097444+840+0",
         "name": null,
         "@baseType": "BucketRef",
         "@schemaLocation": null,
         "@type": "BucketRef",
         "@referredType": null
      },
      "channel": null,
      "confirmationDate": "2025-09-20T10:41:44+05:30",
      "description": null,
      "href": "http://host:port/brm/prepayBalanceManagement/v4/topupBalance/0.0.0.1+-topup+6442543",
      "id": "0.0.0.1+-topup+6442543",
      "impactedBucket": [
         {
            "@baseType": "ImpactedBucket",
            "@schemaLocation": null,
            "@type": "ImpactedBucket",
            "amountAfter": {
               "amount": 643.0,
               "units": "USD",
               "@baseType": null,
               "@schemaLocation": null,
               "@type": null
            },
            "amountBefore": {
               "amount": 663.0,
               "units": "USD",
               "@baseType": null,
               "@schemaLocation": null,
               "@type": null
            },
            "bucket": {
               "id": "0.0.0.1+-balance_group+4097444+840+0",
               "href": "http://host:port/brm/prepayBalanceManagement/v4/bucket/0.0.0.1+-balance_group+4097444+840+0",
               "name": null,
               "@baseType": "BucketRef",
               "@schemaLocation": null,
               "@type": "BucketRef",
               "@referredType": null
            },
            "confirmationDate": null,
            "description": null,
            "item": [
               {
                  "@baseType": "ImpactedBucketItem",
                  "@schemaLocation": null,
                  "@type": "ImpactedBucketItem",
                  "amount": {
                     "amount": 20.0,
                     "units": "USD",
                     "@baseType": null,
                     "@schemaLocation": null,
                     "@type": null
                  },
                  "description": null,
                  "itemType": null,
                  "name": null,
                  "reason": null
               }
            ],
            "name": null,
            "requestedDate": null
         }
      ],
      "isAutoTopup": false,
      "logicalResource": {
         "@baseType": null,
         "@referredType": null,
         "@schemaLocation": null,
         "@type": null,
         "href": null,
         "id": null,
         "name": null,
         "value": "056-20250812-035011-1-20412--146856192-cagbu-phx-175"
      },
      "numberOfPeriods": null,
      "partyAccount": {
         "id": "0.0.0.1+-account+6340627",
         "href": null,
         "description": null,
         "name": "Jane Mason",
         "status": "active",
         "@baseType": null,
         "@schemaLocation": null,
         "@type": "PartyAccountRef",
         "@referredType": null
      },
      "payment": {
         "id": "0.0.0.1+-item-payment+6439471",
         "href": "http://host:port/brm/payment/v4/payment/0.0.0.1+-item-payment+6439471",
         "name": "Billing Event Log",
         "amount": {
            "unit": "USD",
            "value": 20.0
         },
         "paymentDate": "2025-09-20T10:41:43+05:30",
         "@baseType": "Payment",
         "@schemaLocation": null,
         "@type": "Payment",
         "@referredType": null
      },
      "paymentMethod": {
         "id": "0.0.0.1+-payinfo-cc+6306114",
         "href": "http://host:port/brm/paymentMethods/v1/paymentMethod/0.0.0.1+-payinfo-cc+6306114",
         "description": null,
         "isPreferred": false,
         "name": "PIN Payinfo Object",
         "status": null,
         "statusDate": null,
         "account": [
            {
               "id": "0.0.0.1+-account+6340627",
               "href": null,
               "description": null,
               "name": "Jane Mason",
               "@baseType": null,
               "@schemaLocation": null,
               "@type": null,
               "@referredType": null
            }
         ],
         "relatedParty": null,
         "validFor": null,
         "@baseType": null,
         "@schemaLocation": null,
         "@type": "tokenizedCard",
         "@referredType": null
      },
      "product": {
         "id": "0.0.0.1+-service-telco-gsm-sms+4099940",
         "href": null,
         "name": "ServiceTelcoGsmSms",
         "@baseType": null,
         "@schemaLocation": null,
         "@type": "ProductRef",
         "@referredType": null
      },
      "reason": null,
      "recurringPeriod": null,
      "relatedParty": null,
      "relatedTopupBalance": null,
      "requestedDate": "2025-09-20T10:41:44+05:30",
      "requestor": null,
      "status": "CONFIRMED",
      "usageType": "monetary",
      "voucher": ""
   }
]
Back to Top