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

Get Bucket Balances

get

/bucket

Gets the bucket balances that match the specified query criteria.

Request

Query Parameters
  • The type of object to return. Use @type=Bucket for a base object or @type=BucketOracle for an extended object.
  • The list of comma-separated fields to return in the response.
    Examples

  • The maximum number of results to return.
    Examples

  • The number of results to offset the response by.
    Examples

  • Retrieves buckets with the associated party account reference.
    Example:
    0.0.0.1+-account+288459
  • Retrieves the buckets for the product with the specified ID.
    Examples

  • Retrieves buckets with the specified status: ACTIVE, INACTIVE, or CLOSED.
    Examples

  • Retrieves buckets with the specified usage type: monetary or other.
    Examples

There's no request body for this operation.

Back to Top

Response

Supported Media Types

200 Response

The bucket balances were retrieved successfully.
Headers
Body ()
Root Schema : schema
Type: array
Show Source
  • Bucket
    Title: Bucket
    A bucket that tracks a quantity of usage (remaining or consumed) for currency or noncurrency resources (such as messages, minutes, data).
Nested Schema : Bucket
Type: object
Title: Bucket
A bucket that tracks a quantity of usage (remaining or consumed) for currency or noncurrency resources (such as messages, minutes, data).
Show Source
Nested Schema : logicalResource
Type: array
Logical resources associated with the bucket.
Show Source
Nested Schema : Party Account Ref
Type: object
Title: Party Account Ref
A reference to a party account.
Show Source
Nested Schema : product
Type: array
Products associated with the bucket.
Show Source
Nested Schema : relatedParty
Type: array
Parties related to the bucket. (BRM does not use this property.)
Show Source
Nested Schema : Quantity
Type: object
The amount in a given unit.
Show Source
Nested Schema : TimePeriod
Type: object
The period of time, either as a deadline (endDateTime only) a startDateTime only, or both.
Show Source
Nested Schema : Logical Resource Ref
Type: object
Title: Logical Resource Ref
A reference to a logical resource.
Show Source
Nested Schema : Product Ref
Type: object
Title: Product Ref
A reference to a product.
Show Source
Nested Schema : Related Party
Type: object
Title: Related Party
A party related to another object.
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

Example 1: Get Bucket Balances Using Product ID Query Parameter

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

The request uses the product.id query parameter to restrict the results. 

curl -X GET 'http://host:port/brm/prepayBalanceManagement/version/bucket?product.id=0.0.0.1+-service-telco-gsm-sms+102975'

Example of the Response Body

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

[
    {
        "id": "0.0.0.1+-balance_group+106463",
        "href": "http://host:port/brm/prepayBalanceManagement/version/bucket/0.0.0.1+-balance_group+106463",
        "confirmationDate": null,
        "description": null,
        "isShared": null,
        "name": "Account Balance Group",
        "remainingValueName": null,
        "requestedDate": null,
        "logicalResource": null,
        "partyAccount": {
            "id": "0.0.0.1+-account+102879",
            "href": null,
            "description": null,
            "name": "Adam Baker",
            "status": "active",
            "@baseType": null,
            "@schemaLocation": null,
            "@type": "PartyAccountRef",
            "@referredType": null
        },
        "product": [
            {
                "id": "0.0.0.1+-service-telco-gsm-sms+102975",
                "href": null,
                "name": "ServiceTelcoGsmSms",
                "@baseType": null,
                "@schemaLocation": null,
                "@type": "ProductRef",
                "@referredType": null
            },
            {
                "id": "0.0.0.1+-service-telco-gsm-telephony+104255",
                "href": null,
                "name": "ServiceTelcoGsmTelephony",
                "@baseType": null,
                "@schemaLocation": null,
                "@type": "ProductRef",
                "@referredType": null
            }
        ],
        "relatedParty": null,
        "remainingValue": {
            "amount": 45.0,
            "units": "EUR",
            "@baseType": null,
            "@schemaLocation": null,
            "@type": "Quantity"
        },
        "reservedValue": {
            "amount": 0.0,
            "units": "EUR",
            "@baseType": null,
            "@schemaLocation": null,
            "@type": "Quantity"
        },
        "status": "ACTIVE",
        "usageType": null,
        "validFor": {
            "endDateTime": null,
            "startDateTime": "2025-05-02T00:00:00-07:00"
        },
        "@baseType": "Bucket",
        "@schemaLocation": null,
        "@type": "Bucket"
       }
]

Example 2: Get Bucket Balances Using Status Query Parameter

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

The request uses the status query parameter to restrict the results. 

curl -X GET 'http://host:port/brm/prepayBalanceManagement/version/bucket?status=ACTIVE'

Example of the Response Body

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

[
    {
        "id": "0.0.0.1+-balance_group+12345",
        "href": "http://host:port/brm/prepayBalanceManagement/version/bucket/0.0.0.1+-balance_group+12345",
        "confirmationDate": null,
        "description": null,
        "isShared": null,
        "name": "Account Balance Group",
        "remainingValueName": null,
        "requestedDate": null,
        "logicalResource": null,
        "partyAccount": {
            "id": "0.0.0.1+-account+98765",
            "href": null,
            "description": null,
            "name": "Sunita Patel",
            "status": "active",
            "@baseType": null,
            "@schemaLocation": null,
            "@type": "PartyAccountRef",
            "@referredType": null
        },
        "product": [
            {
                "id": "0.0.0.1+-service-telco-gsm-sms+475867",
                "href": null,
                "name": "ServiceTelcoGsmSms",
                "@baseType": null,
                "@schemaLocation": null,
                "@type": "ProductRef",
                "@referredType": null
            },
            {
                "id": "0.0.0.1+-service-telco-gsm-telephony+104255",
                "href": null,
                "name": "ServiceTelcoGsmTelephony",
                "@baseType": null,
                "@schemaLocation": null,
                "@type": "ProductRef",
                "@referredType": null
            }
        ],
        "relatedParty": null,
        "remainingValue": {
            "amount": 10.0,
            "units": "USD",
            "@baseType": null,
            "@schemaLocation": null,
            "@type": "Quantity"
        },
        "reservedValue": {
            "amount": 15.0,
            "units": "USD",
            "@baseType": null,
            "@schemaLocation": null,
            "@type": "Quantity"
        },
        "status": "ACTIVE",
        "usageType": null,
        "validFor": {
            "endDateTime": null,
            "startDateTime": "2025-01-02T00:00:00-07:00"
        },
        "@baseType": "Bucket",
        "@schemaLocation": null,
        "@type": "Bucket"
       }
]
Back to Top