---
title: "Get a balance"
method: POST
path: "/customs/guarantees/{grn}/balance"
---

# Get a balance

`POST /customs/guarantees/{grn}/balance`

## Request

- Base URL: `https://test-api.service.hmrc.gov.uk`
- URL: `https://test-api.service.hmrc.gov.uk/customs/guarantees/{grn}/balance`
- Auth: OAuth 2
  - Authorization code: `https://api.service.hmrc.gov.uk/oauth/authorize`
  - Token URL: `https://api.service.hmrc.gov.uk/oauth/token` scopes: `common-transit-convention-guarantee-balance`
- TypeScript: <https://skmtc.dev/hmrc/apis/common-transit-convention-guarantee-balance/docs/customs/guarantees/:grn/balance/post.ts> (a function with typed inputs; its response is checked against the schema)

Get the balance associated with a guarantee reference number (GRN).

## Path parameters

- `grn` string, required

## Headers

- `Accept` 'application/vnd.hmrc.2.0+json', required
- `Content-Type` 'application/json', required

## Request body

- object: A balance request for the CTC Guarantee Balance API.
  - `accessCode` string, required: The `accessCode` granting access to make use of the guarantee.

## Response `200`

A successful balance request response

- object: A successful balance response.
  - `_links` object: An object containing links to other resources.
  - `_embedded` object: An object containing embedded resources.
  - `balance` number, required: The guarantee's balance.
  - `currency` string: The alphanumeric 3-character ISO currency code of the currency in which the balance is held.

## Other responses

- `400`: Bad request or invalid guarantee type
- `404`: Guarantee not found or invalid access code
- `406`: Not Acceptable
- `429`: Too Many Requests

---

[API](https://skmtc.dev/hmrc/apis/common-transit-convention-guarantee-balance.md) - [All operations](https://skmtc.dev/hmrc/apis/common-transit-convention-guarantee-balance/llms.txt) - [OpenAPI document](https://skmtc.dev/hmrc/apis/common-transit-convention-guarantee-balance/revisions/ec0535c39d75?raw)