Sign in
API Reference

Balance

Retrieve your organization's current account balance and paginated transaction history. Balances consist of a usable cash balance and an optional reward balance.

GET /api/v1/balance

Get balance

Returns the current usable cash balance, reward balance, and combined total for your organization.

Required scope

balance.read

Fields

Field
Type
Required
Description
availableBalance
object
—
Cash balance immediately available for new orders
availableBalance.amount
number
—
Numeric value of the available balance
availableBalance.currency
string
—
ISO 4217 currency code, e.g. USD
pendingBalance
object
—
Amount committed to orders currently being processed (not yet complete)
pendingBalance.amount
number
—
Numeric value of the pending balance
pendingBalance.currency
string
—
ISO 4217 currency code, e.g. USD
POST /api/v1/balance/charge

Request ACH balance top-up

Submit an ACH wire transfer request to top up your organization's balance. The request is recorded with PENDING status and reviewed by the Giftronaut team. Balance is credited after wire transfer is confirmed.

Not available in sandbox. Production credentials only.

Required scope

balance.write

Request body

Field
Type
Required
Description
amount
number
Yes
Top-up amount in USD. Minimum 100.00. No decimal fractions.
companyName
string
Yes
Legal company name as registered
phoneNumber
string
Yes
Company contact phone number
billingAddress
string
Yes
Street address for billing
city
string
Yes
City
state
string
Yes
State or province
country
string
Yes
Country code, e.g. US
zipCode
string
Yes
Postal/ZIP code
ein
string
Yes
Employer Identification Number (EIN), e.g. 12-3456789
companyWebsite
string
No
Company website URL

Response fields

Field
Type
Description
fundingNo
string
Unique reference number for this top-up request
amount
object
Requested amount — { amount, currency }
status
string
Always PENDING — balance is credited after wire is confirmed
createdAt
string
ISO-8601 UTC timestamp of the request
GET /api/v1/balance/ledger

List ledger

Returns a paginated, reverse-chronological list of balance transactions — charges, order deductions, refunds, and transfers.

Required scope

balance.read

Query parameters

Parameter
Type
Required
Description
page
integer
No
Page number, default 1
pageSize
integer
No
Results per page, default 20, max 100
startDate
string
No
ISO-8601 date filter start, e.g. 2024-01-01
endDate
string
No
ISO-8601 date filter end, e.g. 2024-12-31

Transaction types

Type
Description
CHARGE
Balance added (top-up)
USE
Balance deducted for an order (amount is negative)
REFUND
Balance refunded from a canceled order
REWARD
Promotional credit or reward applied to balance
TRANSFER
Balance transferred between accounts