---
title: "Gift card balance inquiry"
method: POST
path: "/scl/v1/balance_inquiry"
tags: ["ECOMMGIFTCARD"]
---

# Gift card balance inquiry

`POST /scl/v1/balance_inquiry`

## Request

- Base URL: `https://scl-sandbox.dev.clover.com`
- URL: `https://scl-sandbox.dev.clover.com/scl/v1/balance_inquiry`
- Auth: OAuth 2
  - Authorization code: `https://sandbox.dev.clover.com/oauth/authorize`
  - Token URL: `https://sandbox.dev.clover.com/oauth/token`

Displays the current balance of an existing virtual gift card:
 > If a currency code is specified, the current balance displays in that currency and the base currency if they are different.
 > If no currency code is specified, the current balance displays in the base currency.

> **Important: Information for Gift Card Holders**
> This page contains technical API documentation for software developers. It cannot be used to check your gift card balance.
> 
> **To check your gift card balance, please download and use the [Gyft app](https://www.gyft.com/).**
>
> For merchant-facing information about Gift Cards reporting, see the [Clover Help site](https://www.clover.com/help).

## Headers

- `User-Agent` string, required

## Request body

- object
  - `source` string, required: Single-pay Clover gift card token (cToken) indicating the gift card details and metadata.
  - `amount` integer: Transaction amount in local currency. Gift card amount.
  - `currency` string: Three-letter [ISO 4217 currency code](https://www.iso.org/iso-4217-currency-codes.html). Format: Lower case Length: Maximum 3
  - `promotion_code` string: Virtual promotional code of the gift card. **Note:** Applicable only for gift card virtual activation, if the promo code is not already configured.

## Response `200`

Gift card balance inquiry is successful.

- EcommGiftCardResponse: Gift card data.
  - `status` string: Indicates the transaction response.
  - `gift_card` EcommGiftCardResponseExtra: Indicates meta data of the gift card.
    - `previous_balance` integer: Indicates the previous balance before the transaction was initiated.
    - `new_balance` integer: Indicates the updated balance after the transaction is completed.
    - `lock_amount` integer: Indicates the value on the card that was locked due to a balance lock transaction.
    - `expiration_date` string: Indicates the account expiration date.
    - `lock_id` integer: Unique lock number identifier for each balance lock record. The `lock_id` helps capture the authorized amount and is applicable for pre-auth and capture flow.
    - `number` string: Embossed card number on the gift card or the ift card number. Only applicable for virtual gift card activation.
    - `security_card_value` string: Gift card security code. Only applicable for virtual gift card activation.

## Other responses

- `400`: Bad request
- `default`: Error response

---

[API](https://skmtc.dev/clover/apis/ecommerce-service-api.md) - [All operations](https://skmtc.dev/clover/apis/ecommerce-service-api/llms.txt) - [OpenAPI document](https://skmtc.dev/clover/apis/ecommerce-service-api/revisions/a0aeb344ed80?raw)