Skip to main content
The Mobile Ledger object represents a record of mobile data usage or allocation in the Byteful system. It serves as a complete audit trail that tracks all changes to the mobile data pool associated with a customer account, including daily usage consumption, top-ups, service purchases, and administrative adjustments.

​
Key Attributes

AttributeTypeDescription
mobile_ledger_idstringUnique identifier for the ledger entry
mobile_ledger_bytesintegerAmount of data in bytes associated with this ledger entry
mobile_ledger_requestsintegerNumber of requests associated with this ledger entry
mobile_ledger_period_datestringThe date this ledger entry is associated with
mobile_ledger_reasonstringReason for the ledger entry (e.g., “usage”, “top_up”, “service_purchase”)
service_idstringID of the related service if applicable
service_adjustment_idintegerID of the related service adjustment if applicable
mobile_ledger_creation_datetimedatetimeWhen the ledger entry was created
mobile_ledger_last_update_datetimedatetimeWhen the ledger entry was last updated

​
Object Relationships

The Mobile Ledger object is connected to several other objects in the Byteful API:
  • Customer: Each mobile ledger entry belongs to a customer account
  • Service: Entries may be associated with a mobile service (e.g., when purchasing additional data)
  • Service Adjustment: Entries may be linked to service adjustments (e.g., refunds or manual adjustments)
  • Proxy User: While not directly linked, proxy users consume data which creates ledger entries
EndpointDescription
GET /public/user/mobile_ledger/retrieve/{mobile_ledger_id}Retrieve a specific mobile ledger entry
GET /public/user/mobile_ledger/searchSearch mobile ledger entries with filters
GET /public/user/mobile/summaryGet a summary of mobile data status

​
Example Response

{
  "data": {
    "customer_id": 1955,
    "mobile_ledger_bytes": 128290101,
    "mobile_ledger_creation_datetime": "2023-04-01 12:00:00",
    "mobile_ledger_id": "123e4567-e89b-12d3-a456-426614174000",
    "mobile_ledger_last_update_datetime": "2023-04-02 12:00:00",
    "mobile_ledger_period_date": "2023-10-01",
    "mobile_ledger_reason": "top_up",
    "mobile_ledger_requests": 1244,
    "service_adjustment_id": 10,
    "service_id": "API-1234-5678"
  },
  "message": "Mobile Ledger successfully retrieved."
}

​
Ledger Entry Types

Mobile ledger entries have various reason types that indicate different data changes:
ReasonDescription
usageDaily decrements to the data pool from proxy usage
top_upIncrements from purchasing additional data
adjustmentManual adjustments (positive or negative) made by administrators

​
Usage Notes

  • The mobile ledger is maintained at the account data pool level, not per proxy
  • Usage entries are aggregated daily, providing a day-by-day audit trail of data consumption
  • Entries with positive mobile_ledger_bytes values add to your data pool (top-ups, purchases)
  • Entries with negative mobile_ledger_bytes values subtract from your data pool (usage)
  • The mobile_ledger_period_date field indicates the specific day when usage occurred or changes were made
  • Unlike datacenter and ISP proxies, mobile proxies operate on a data-based billing model
  • There is no automatic expiration for mobile data - it remains in your account until consumed
  • For real-time data status, use the /mobile/summary endpoint