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

Create a Bucket

post

/bucket

Creates a bucket to store balances.

Request

There are no request parameters for this operation.

Supported Media Types
Request Body - application/json;charset=utf-8 ()
Root Schema : schema
Type: object
A bucket, used in bucket create requests.
Show Source
Nested Schema : logicalResource
Type: array
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
Show Source
Nested Schema : relatedParty
Type: array
Used to provide information about any other entity with relation to the balance. For instance, to define a customer hierarchy for the balance (such as customerId, userId).
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
Back to Top

Response

Supported Media Types

201 Response

The bucket was created successfully.
Body ()
Root 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

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 examples show how to create buckets (balance groups in BRM) by submitting POST requests on the REST resource using cURL. For more information about cURL, see Use cURL.

The -d option specifies the file to attach as the request body. 

curl -X POST 'http://host:port/brm/prepayBalanceManagement/version/bucket' -d @bucketCreate.json

Example of Request Body for Creating a Currency Bucket

The following is an example of the contents of the bucketCreate.json file sent as the request body to create a currency bucket. It specifies both partyAccount and product, but only one is required. It also specifies the units for the remaining value, but this is optional. If you do not specify the unit, the default account currency is used. 

{
   "partyAccount": {
      "id": "0.0.0.1+-account+2090314"
   },
   "product": [
      {
         "id": "0.0.0.1+-service-telco-gsm-telephony+2092746"
      }
   ],
   "remainingValue": {
      "amount": 1000,
      "units": "USD"
   },
   "validFor": {
      "endDateTime": "2025-06-02T16:24:59+05:30",
      "startDateTime": "2024-10-02T13:04:42+05:30"
   },
   "usageType": "monetary"
}

Example of Response Body for Creating a Currency Bucket

The following is an example of the response body in JSON format.

{
   "id": "0.0.0.1+-balance_group+2090186+840+28",
   "href": "https://host:port/brm/prepayBalanceManagement/v4/bucket/0.0.0.1+-balance_group+2090186+840+28",
   "confirmationDate": null,
   "description": null,
   "isShared": null,
   "name": "Balance Group (1)",
   "remainingValueName": null,
   "requestedDate": null,
   "logicalResource": null,
   "partyAccount": {
      "id": "0.0.0.1+-account+2090314",
      "href": null,
      "description": null,
      "name": "aa sa",
      "status": "active",
      "@baseType": null,
      "@schemaLocation": null,
      "@type": "PartyAccountRef",
      "@referredType": null
   },
   "product": [
      {
         "id": "0.0.0.1+-service-telco-gsm-telephony+2092746",
         "href": null,
         "name": "ServiceTelcoGsmTelephony",
         "@baseType": null,
         "@schemaLocation": null,
         "@type": "ProductRef",
         "@referredType": null
      }
   ],
   "relatedParty": null,
   "remainingValue": {
      "amount": 1000.0,
      "units": "USD",
      "@baseType": null,
      "@schemaLocation": null,
      "@type": "Quantity"
   },
   "reservedValue": {
      "amount": 0.0,
      "units": "USD",
      "@baseType": null,
      "@schemaLocation": null,
      "@type": "Quantity"
   },
   "status": "ACTIVE",
   "usageType": null,
   "validFor": {
      "endDateTime": "2025-06-02T16:24:59+05:30",
      "startDateTime": "2024-10-02T13:04:42+05:30",
      "@baseType": null,
      "@schemaLocation": null,
      "@type": null
   },
   "@baseType": "Bucket",
   "@schemaLocation": null,
   "@type": "Bucket"
}

Example of Request Body for Creating a Noncurrency Bucket

The following is an example of the contents of the bucketCreate.json file sent as the request body to create a noncurrency bucket. 

{
   "partyAccount": {
      "id": "0.0.0.1+-account+2090314"
   },
   "remainingValue": {
      "amount": 9999,
      "units": "Free Domestic Minutes"
   },
   "validFor": {
      "endDateTime": "2025-05-02T16:24:59+05:30",
      "startDateTime": "2024-04-02T13:04:42+05:30"
   },
   "usageType": "other"
}

You can also transfer noncurrency product balances, with or without a cost.

Example of Response Body for Creating a Noncurrency Bucket

The following is an example of the response body in JSON format.

{
   "id": "0.0.0.1+-balance_group+2091210+1000010+4",
   "href": "https://host:port/brm/prepayBalanceManagement/v4/bucket/0.0.0.1+-balance_group+2091210+1000010+4",
   "confirmationDate": null,
   "description": null,
   "isShared": null,
   "name": "Balance Group<Account>",
   "remainingValueName": null,
   "requestedDate": null,
   "logicalResource": null,
   "partyAccount": {
      "id": "0.0.0.1+-account+2090314",
      "href": null,
      "description": null,
      "name": "aa sa",
      "status": "active",
      "@baseType": null,
      "@schemaLocation": null,
      "@type": "PartyAccountRef",
      "@referredType": null
   },
   "product": null,
   "relatedParty": null,
   "remainingValue": {
      "amount": 9999.0,
      "units": "Free Domestic Minutes",
      "@baseType": null,
      "@schemaLocation": null,
      "@type": "Quantity"
   },
   "reservedValue": {
      "amount": 0.0,
      "units": "Free Domestic Minutes",
      "@baseType": null,
      "@schemaLocation": null,
      "@type": "Quantity"
   },
   "status": "ACTIVE",
   "usageType": null,
   "validFor": {
      "endDateTime": "2025-05-02T16:24:59+05:30",
      "startDateTime": "2024-04-02T13:04:42+05:30",
      "@baseType": null,
      "@schemaLocation": null,
      "@type": null
   },
   "@baseType": "Bucket",
   "@schemaLocation": null,
   "@type": "Bucket"
}
Back to Top