Skip to main content
GET
/
api
/
v1
/
partner
/
accounts
/
{customer_auth_id}
/
transactions
List customer transactions
curl --request GET \
  --url https://api.vobiz.ai/api/v1/partner/accounts/{customer_auth_id}/transactions \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>'
{
  "transactions": [
    {
      "id": "aabbccdd-1234-5678-90ab-cdef12345678",
      "account_id": "MA_XXXXXXXX",
      "balance_id": "11223344-1234-5678-90ab-cdef12345678",
      "type": "credit",
      "amount": 200,
      "currency": "INR",
      "description": "Transfer from partner Acme: Balance transfer",
      "reference": "ptc:99887766-1234-5678-90ab-cdef12345678:MA_XXXXXXXX:1778140310",
      "status": "completed",
      "processed_at": "2026-03-25T10:00:00Z",
      "created_at": "2026-03-25T10:00:00Z",
      "updated_at": "2026-03-25T10:00:00Z"
    },
    {
      "id": "55667788-1234-5678-90ab-cdef12345678",
      "account_id": "MA_XXXXXXXX",
      "balance_id": "11223344-1234-5678-90ab-cdef12345678",
      "type": "credit",
      "amount": 100,
      "currency": "INR",
      "description": "Transfer from partner Acme: Balance transfer",
      "reference": "ptc:99887766-1234-5678-90ab-cdef12345678:MA_XXXXXXXX:1778051898",
      "status": "completed",
      "processed_at": "2026-03-24T07:18:18Z",
      "created_at": "2026-03-24T07:18:18Z",
      "updated_at": "2026-03-24T07:18:18Z"
    },
    {
      "id": "aabbccdd-9999-5678-90ab-cdef12345678",
      "account_id": "MA_XXXXXXXX",
      "balance_id": "11223344-1234-5678-90ab-cdef12345678",
      "type": "credit",
      "amount": 1000,
      "currency": "INR",
      "description": "Transfer from partner Acme: Balance transfer",
      "reference": "ptc:99887766-1234-5678-90ab-cdef12345678:MA_XXXXXXXX:1778051770",
      "status": "completed",
      "processed_at": "2026-03-24T07:16:10Z",
      "created_at": "2026-03-24T07:16:10Z",
      "updated_at": "2026-03-24T07:16:10Z"
    }
  ],
  "summary": {
    "total_transactions": 3,
    "total_debit": 0,
    "total_credit": 1300,
    "net_amount": 1300,
    "by_reference_type": [
      {
        "reference_type": "unknown",
        "total_debit": 0,
        "total_credit": 1300,
        "count": 3
      }
    ]
  },
  "total": 3,
  "page": 1,
  "per_page": 20,
  "total_pages": 1,
  "account_auth_id": "MA_XXXXXXXX"
}
← Partner API Reference Detailed financial ledgers for every credit and debit event across your partner ecosystem. Use these for monthly billing reconciliation, dispute resolution, and auditing balance movements between your account and your customers.
All Partner API requests use X-Auth-ID and X-Auth-Token headers. See Authentication for details.

​
Overview

Two endpoints cover different scopes of transaction data:
  • Customer Transactions - All debits and credits for one specific customer. Use for per-customer invoicing and customer-facing statements.
  • All Transactions (Global) - Global ledger across every customer under your partner account. Use for platform-wide reconciliation and monthly financial close.

​
Customer Transactions

Returns a paginated transaction ledger for one specific customer. Filter by transaction type and date range to generate statements for a specific billing period.

​
Query Parameters

ParameterDefaultDescription
page1Page number (1-indexed)
per_page20Items per page (max 100)
from_date-Start date in YYYY-MM-DD format
to_date-End date in YYYY-MM-DD format
transaction_type-Filter to recharge, debit, refund, or transfer
curl -X GET \
  "https://api.vobiz.ai/api/v1/partner/accounts/{customer_auth_id}/transactions?page=1&per_page=20" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}" \
  -H "Accept: application/json"

curl -X GET \
  "https://api.vobiz.ai/api/v1/partner/accounts/{customer_auth_id}/transactions?from_date=2026-03-01&to_date=2026-03-31&per_page=100" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}" \
  -H "Accept: application/json"

curl -X GET \
  "https://api.vobiz.ai/api/v1/partner/accounts/{customer_auth_id}/transactions?transaction_type=recharge&per_page=50" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}" \
  -H "Accept: application/json"

{
  "transactions": [
    {
      "id": "aabbccdd-1234-5678-90ab-cdef12345678",
      "account_id": "MA_XXXXXXXX",
      "balance_id": "11223344-1234-5678-90ab-cdef12345678",
      "type": "credit",
      "amount": 200,
      "currency": "INR",
      "description": "Transfer from partner John Doe: Balance transfer",
      "reference": "ptc:aabbccdd-1234-5678-90ab-cdef12345678:MA_XXXXXXXX:1778140310",
      "status": "completed",
      "processed_at": "2026-05-07T07:51:50.402147Z",
      "created_at": "2026-05-07T07:51:50.402147Z",
      "updated_at": "2026-05-07T07:51:50.402147Z"
    },
    {
      "id": "99887766-1234-5678-90ab-cdef12345678",
      "account_id": "MA_XXXXXXXX",
      "balance_id": "11223344-1234-5678-90ab-cdef12345678",
      "type": "credit",
      "amount": 100,
      "currency": "INR",
      "description": "Transfer from partner John Doe: Balance transfer",
      "reference": "ptc:aabbccdd-1234-5678-90ab-cdef12345678:MA_XXXXXXXX:1778051898",
      "status": "completed",
      "processed_at": "2026-05-06T07:18:18.945506Z",
      "created_at": "2026-05-06T07:18:18.945506Z",
      "updated_at": "2026-05-06T07:18:18.945506Z"
    },
    {
      "id": "55667788-1234-5678-90ab-cdef12345678",
      "account_id": "MA_XXXXXXXX",
      "balance_id": "11223344-1234-5678-90ab-cdef12345678",
      "type": "credit",
      "amount": 1000,
      "currency": "INR",
      "description": "Transfer from partner John Doe: Balance transfer",
      "reference": "ptc:aabbccdd-1234-5678-90ab-cdef12345678:MA_XXXXXXXX:1778051770",
      "status": "completed",
      "processed_at": "2026-05-06T07:16:10.657945Z",
      "created_at": "2026-05-06T07:16:10.657945Z",
      "updated_at": "2026-05-06T07:16:10.657945Z"
    }
  ],
  "summary": {
    "total_transactions": 3,
    "total_debit": 0,
    "total_credit": 1300,
    "net_amount": 1300,
    "by_reference_type": [
      {
        "reference_type": "unknown",
        "total_debit": 0,
        "total_credit": 1300,
        "count": 3
      }
    ]
  },
  "total": 3,
  "page": 1,
  "per_page": 20,
  "total_pages": 1,
  "account_auth_id": "MA_XXXXXXXX"
}

​
All Transactions (Global)

Global reconciliation log - all transaction events across every customer under your partner account in a single paginated response. Same filter parameters as the per-customer endpoint. Essential for platform-wide monthly financial close.
If you only need a single customer’s ledger, prefer the per-customer endpoint above - it returns a summary block scoped to that customer. To reconcile across all customers when the global endpoint is unavailable to you, page through GET /accounts and call the per-customer ledger for each auth_id.
curl -X GET \
  "https://api.vobiz.ai/api/v1/partner/transactions?page=1&per_page=50" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}" \
  -H "Accept: application/json"

curl -X GET \
  "https://api.vobiz.ai/api/v1/partner/transactions?from_date=2026-03-01&to_date=2026-03-31&transaction_type=debit&per_page=100" \
  -H "X-Auth-ID: {your_partner_id}" \
  -H "X-Auth-Token: {your_auth_token}" \
  -H "Accept: application/json"

​
Response fields

FieldNotes
transactions[].idUUID of the ledger entry.
transactions[].account_idThe customer auth_id the entry belongs to.
transactions[].typeLedger direction - credit or debit. This is not the same vocabulary as the transaction_type filter (see below).
transactions[].amountPositive integer in the account currency. The sign is implied by type, not by the number.
transactions[].referenceMachine reference. Partner balance transfers use the form ptc:<partner_id>:<customer_auth_id>:<unix_ts>.
transactions[].statuscompleted for settled entries.
summaryAggregates for the filtered window: total_transactions, total_debit, total_credit, net_amount, and a by_reference_type breakdown.
total / page / per_page / total_pagesPagination over the full filtered result set.
Two different “type” vocabularies. The transaction_type query filter accepts recharge, debit, refund, transfer. The type field in each response row is the ledger direction credit or debit. Don’t filter on credit/debit as a transaction_type value - use the dedicated filter values.

​
Transaction types (filter values)

  • recharge - Wallet top-up credited to the customer. Reflected as a credit row. Amount is positive.
  • debit - Automatic usage deduction for completed calls and DID fees. Reflected as a debit row. Generated per call or in daily batches depending on configuration.
  • refund - Credit issued for a disputed charge or service outage. Reflected as a credit row.
  • transfer - A partner-to-customer balance transfer. On the customer ledger this lands as a credit (with description Transfer from partner …); on your partner ledger the matching debit appears.

​
Monthly Billing Guide

Use transactions to generate accurate invoices for your customers:
  • Pull all debits for the billing period - Filter by transaction_type=debit and the billing window dates. Sum the absolute amounts.
  • Add your margin - Apply your reseller markup on top of the raw usage cost before invoicing.
  • Check recharge history - Confirm the customer has covered their previous balance transfers before issuing the next invoice.
  • Global reconciliation - Use the global endpoint at month-end to reconcile your master ledger against the sum of all customer ledgers.

Authorizations

​
X-Auth-ID
string
header
required

Your Vobiz account Auth ID

​
X-Auth-Token
string
header
required

Your Vobiz account Auth Token

Path Parameters

​
customer_auth_id
string
required

Query Parameters

​
from_date
string<date>
Example:

"2026-03-01"

​
to_date
string<date>
Example:

"2026-03-31"

​
transaction_type
enum<string>
Available options:
recharge,
debit,
refund,
transfer
​
page
integer
default:1
​
per_page
integer
default:20

Response

200 - application/json

Transactions list

​
transactions
object[]
required
​
summary
object
required
​
total
integer
required
​
page
integer
required
​
per_page
integer
required
​
total_pages
integer
required
​
account_auth_id
string
required