# Check Brand Wallet Balance

**Method:** `POST`

**Path:** `/payment-option/wallet/balance`

**Category:** Brand Wallet

**Authentication:** Required

## Description

Retrieves the current balance of a customer's brand wallet,
including breakdown by bucket type (e.g. CASH, PROMOTIONAL).


## Request Body

Content-Type: `application/json`

- `notes` (`string`)
- `customers` (`object`) **required** — Customer information.
  - `email_id` (`string`) — Customer's email address.
  - `first_name` (`string`) — Customer's first name.
  - `last_name` (`string`) — Customer's last name.
  - `customer_id` (`string`) — Unique identifier of the customer.
  - `mobile_number` (`string`) — Customer's mobile number.
  - `country_code` (`string`) — Country code of the registered mobile number. Defaults to 91.
  - `billing_address` (`object`) — Physical address.
    - `address1` (`string`) — Address line 1.
    - `address2` (`string`) — Address line 2.
    - `address3` (`string`) — Address line 3.
    - `pincode` (`string`) — Postal/ZIP code.
    - `city` (`string`) — City name.
    - `state` (`string`) — State or province.
    - `country` (`string`) — Country name.
    - `full_name` (`string`) — Full name of the address holder.
    - `adddress_type` (`string`) — Type of address (e.g., Home, Office).
    - `address_category` (`billing | shipping`) — Category of the address.

  - `shipping_address` (`object`) — Physical address.
    - `address1` (`string`) — Address line 1.
    - `address2` (`string`) — Address line 2.
    - `address3` (`string`) — Address line 3.
    - `pincode` (`string`) — Postal/ZIP code.
    - `city` (`string`) — City name.
    - `state` (`string`) — State or province.
    - `country` (`string`) — Country name.
    - `full_name` (`string`) — Full name of the address holder.
    - `adddress_type` (`string`) — Type of address (e.g., Home, Office).
    - `address_category` (`billing | shipping`) — Category of the address.

  - `is_edit_customer_details_allowed` (`boolean`) — Whether the customer is allowed to edit their details.


### Example Request

```json
{
  "customers": {
    "email_id": "john@example.com",
    "first_name": "Kevin",
    "last_name": "Bob",
    "customer_id": "123456",
    "mobile_number": "9876543210",
    "country_code": "91",
    "billing_address": {
      "address1": "10 Downing Street Westminster London",
      "address2": "Oxford Street Westminster London",
      "address3": "Baker Street Westminster London",
      "pincode": "51524036",
      "city": "Westminster",
      "state": "Westminster",
      "country": "London",
      "full_name": "Kevin Bob",
      "adddress_type": "Home",
      "address_category": "billing"
    },
    "shipping_address": {
      "address1": "10 Downing Street Westminster London",
      "address2": "Oxford Street Westminster London",
      "address3": "Baker Street Westminster London",
      "pincode": "51524036",
      "city": "Westminster",
      "state": "Westminster",
      "country": "London",
      "full_name": "Kevin Bob",
      "adddress_type": "Home",
      "address_category": "billing"
    },
    "is_edit_customer_details_allowed": false
  }
}
```

## Responses

- `200` — Balance retrieved.
- `400` — 
- `401` — 
- `500` — 

### Response Schema

- `total_balance_amount` (`object`) — Monetary amount with currency.
  - `value` (`integer`) **required** — Amount in the smallest currency unit (e.g., paisa for INR).
  - `currency` (`string`) **required** — Three-letter ISO 4217 currency code.

- `number_of_pin_attempts_allowed` (`integer`) — Remaining PIN attempts before lockout
- `created_at` (`string`) — Wallet creation timestamp
- `native_currency` (`string`) — Primary currency of the wallet
- `buckets` (`BrandWalletBalanceBucket[]`) — Balance breakdown by bucket type
  - `currency_code` (`string`)
  - `number_of_cards` (`integer`) — Number of instruments in this bucket
  - `balance` (`integer`) — Bucket balance in lowest currency denomination (paisa)
  - `type` (`string`) — Bucket type (e.g. CASH, PROMOTIONAL)
  - `payment_instruments` (`BrandWalletPaymentInstrument[]`)
    - `instrument_number` (`string`)
    - `currency_code` (`string`)
    - `expiry_date` (`string`)
    - `terms_and_conditions` (`string`)



### Example Response

```json
{
  "total_balance_amount": {
    "value": 50000,
    "currency": "INR"
  },
  "native_currency": "INR",
  "buckets": [
    {
      "currency_code": "INR",
      "payment_instruments": []
    }
  ]
}
```

---

Reference: https://localhost:3000/api/brand-wallet/get-brand-wallet-balance