Sign in
API Reference

Balance

Retrieve your organization's current account balance and paginated transaction history. Your balance consists of a usable cash balance available for orders.

GET /api/v1/balance

Get balance

Returns the current usable cash balance and pending balance 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
—
ACH top-up requests pending approval. Always 0 in sandbox.
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.
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
message
string
Human-readable confirmation message
estimatedProcessingTime
string
Expected review turnaround, e.g. 1-3 business days
createdAt
string
ISO-8601 UTC timestamp of the request
DELETE /api/v1/balance/charge/{fundingNo}

Cancel ACH balance top-up

Withdraws (voids) a still-pending ACH top-up request — the same action as "Void Funding Request" in the portal balance history. Only requests awaiting review can be canceled; completed, rejected, or already-canceled requests return 409 FUNDING_NOT_CANCELABLE. After cancel the request no longer counts toward pendingBalance, and the reserved balance.ach_approved / balance.ach_rejected webhook events will not fire.

Not available in sandbox. Production credentials only.

Required scope

balance.write

Path parameters

Field
Type
Required
Description
fundingNo
string
Yes
Funding request number returned by POST /balance/charge

Response fields

Field
Type
Description
fundingNo
string
The canceled funding request number
amount
object
Withdrawn amount — { amount, currency }
status
string
Always CANCELED
canceledAt
string
ISO-8601 UTC timestamp of the cancellation
GET /api/v1/balance/ledger

List ledger

Returns a paginated, reverse-chronological list of balance transactions. These are the same rows shown on the Account Balance page in the Giftronaut portal — promotions, transfers, ACH/card top-ups, and order spend or cancellation for both branded and choice cards.

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

Response fields

Field
Type
Description
referenceNumber
string
Order number or funding number
type
string
Coarse category — see Transaction types
source
string
Row origin — reward, transfer, funding, branded, choice
status
string
Source-specific status code; interpret together with source
statusLabel
string
Human-readable label shown in the portal
amount
object
Unchanged from previous versions — same value the portal stores
signedAmount
object
New. Direction-aware — negative for outflows, positive for inflows
occurredAt
string
ISO-8601 UTC timestamp

Two amount fields. amount keeps its original meaning and value, so existing integrations are unaffected. signedAmount is new and encodes direction — use it if you want to sum a running balance.

Transaction types

The coarse type field is kept for backward compatibility. It cannot distinguish a pending top-up from a completed one, nor a promotion from a refund — for that, read statusLabel or combine source with status.

Type
Description
CHARGE
Balance top-up (ACH or credit card)
USE
Balance deducted for an order (amount is negative)
REFUND
Refund from a canceled order, or a reward refund
TRANSFER
Balance transferred between accounts
REWARD
Promotional or administratively granted reward

source + status → statusLabel

source
status
statusLabel
Sign
reward
1, 2
Promotion
+
reward
3
Refund
+
transfer
20
Transfer (sent)
−
transfer
21
Transfer (received)
+
funding
90
Pending
+
funding
99
Processed
+
funding
03
Unapproved
+
branded
1
Balance Used
−
branded
2
Canceled
+
choice
1, 3
Balance Used
−
choice
2, 3
Canceled
+

Pending and unapproved top-ups are included. Rows whose statusLabel is Pending or Unapproved have not been credited to your balance yet. Filter them out if you only want settled movements.

Sandbox limitation. The reward and funding sources have no sandbox tables, so sandbox credentials return only order-related rows (branded, choice) and the cash leg of transfer. Production credentials return all sources.