Redeem Balance Code

This endpoint allows you to redeem a data balance code (gift card or top-up code) to add a specified amount of data transfer volume to your network. Once redeemed, the data balance is credited to your account and remains active until the specified end time.

`POST /subscription/redeem-balance-code`

Redeem a secret alphanumeric code for a data balance allocation.

Request

POST /subscription/redeem-balance-code

Headers:

{
  "Host": "api.bringyour.com",
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_JWT_TOKEN"
}

Body:

{
  "secret": "string"
}

Field	Type	Description
`secret`	`string`	Required. The unique, alphanumeric secret code providing the data balance.

Response

`200 Success`

Status: 200 OK

Content-Type: application/json

A successful response returns the details of the newly credited transfer balance.

{
  "transfer_balance": {
    "transfer_balance_id": "udid",
    "start_time": "string",
    "end_time": "string",
    "balance_byte_count": 0
  },
  "error": {
    "message": "string"
  }
}

Fields

Field	Type	Description
`transfer_balance`	`object`	Details of the data balance added to the account.
`transfer_balance.transfer_balance_id`	`string`	Unique identifier (UDID) for this balance record.
`transfer_balance.start_time`	`string`	ISO 8601 timestamp of when this balance became active.
`transfer_balance.end_time`	`string`	ISO 8601 timestamp of when this balance will expire.
`transfer_balance.balance_byte_count`	`integer`	The total number of bytes granted by the code.
`error`	`object`	Details if the redemption failed (can be null).
`error.message`	`string`	Human-readable explanation of the error.

Example

HTTP Request

POST /subscription/redeem-balance-code HTTP/1.1
Host: api.bringyour.com
Content-Type: application/json
Authorization: Bearer YOUR_JWT_TOKEN
 
{
  "secret": "GIFT-10GB-XYZ789"
}

Successful HTTP Response

{
  "transfer_balance": {
    "transfer_balance_id": "c73040c1-0000-4444-8888-000000000000",
    "start_time": "2025-01-20T12:00:00Z",
    "end_time": "2025-02-20T12:00:00Z",
    "balance_byte_count": 10737418240
  },
  "error": null
}

On this page