The content in this section relects our KAZOO open source repository (version 4.3), which is no longer maintained.

Ledgers

Ledgers

About Ledgers

The Ledgers API provides an easy way to see usage like per-minutes or flat-rate and manage your account’s credit/debit values.

Ledgers Schema

Schema

ledgers document

KeyDescriptionTypeDefaultRequiredSupport Level
account.idAccount IDstring()false
account.nameAccount namestring()false
accountAccount infoobject()false
amountLedger amount, in currency amountnumber()false
descriptionUseful description for ledgerstring()false
metadataMetadata for ledger documentobject()false
period.endPeriod endinteger()false
period.startPeriod startinteger()false
periodPeriod of ledgerobject()false
source.idSource IDstring()true
source.serviceSource servicestring()true
sourceOrigin of ledgerobject()true
usage.quantityUsage quantityinteger()true
usage.typeUsage typestring()true
usage.unitUsage unitstring()true
usageUsage for ledgerobject()true

Get Available Ledgers

List available ledger sources from the account’s reseller.

GET /v2/accounts/{ACCOUNT_ID}/ledgers/available

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/ledgers/available
{
    "auth_token": "{AUTH_TOKEN}",
    "data": [
        {
            "name": "per-minute-voip",
            "friendly_name": "Per Minute VoIP",
            "markup_type": [
                "percentage"
            ]
        }
    ],
    "node": "{NODE}",
    "request_id": "{REQUEST_ID}",
    "status": "success",
    "timestamp": "{TIMESTAMP}",
    "version": "{VERSION}"
}

Fetch

GET /v2/accounts/{ACCOUNT_ID}/ledgers

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/ledgers
{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "mobile_data": {
            "amount": -10.5,
            "usage": {
                "quantity": 1000,
                "type": "debit",
                "unit": "MB"
            }
        },
        "per-minute-voip": {
            "amount": -54.7404,
            "usage": {
                "quantity": 14520,
                "type": "voice",
                "unit": "sec"
            }
        }
    },
    "node": "{NODE}",
    "request_id": "{REQUEST_ID}",
    "status": "success",
    "timestamp": "{TIMESTAMP}",
    "version": "{VERSION}"
}

Fetch Ledgers by source

GET /v2/accounts/{ACCOUNT_ID}/ledgers/{SOURCE_SERVICE}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/ledgers/{SOURCE_SERVICE}

Get Ledger values

List ledger values for an account with paging and filtering support

GET /v2/accounts/{ACCOUNT_ID}/ledgers/{LEDGER_ID}?created_from=11111111&created_to=22222222

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/ledgers/{LEDGER_ID}
{
    "page_size": 30,
    "data": [
        {
            "source": {
                "service": "per-minute-voip",
                "id": "{CALL_ID}"
            },
            "account": {
                "id": "{ACCOUNT_ID}",
                "name": "{ACCOUNT_NAME}"
            },
            "usage": {
                "type": "voice",
                "quantity": 3,
                "unit": "sec"
            },
            "amount": 6,
            "description": "US Hollywood",
            "period": {
                "start": 63630348840
            },
            "id": "{DOC_ID}"
        }
    ],
    "revision": "{REVISION}",
    "request_id": "{REQUEST_ID}",
    "status": "success",
    "auth_token": "{AUTH_TOKEN}"
}

Get Ledger document

GET /v2/accounts/{ACCOUNT_ID}/ledgers/{LEDGER_ID}/{LEDGER_ENTRY_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/ledgers/{LEDGER_ID}/{LEDGER_ENTRY_ID}
{
    "data": {
        "source": {
            "service": "per-minute-voip",
            "id": "{CALL_ID}"
        },
        "account": {
            "id": "{ACCOUNT_ID}",
            "name": "{ACCOUNT_NAME}"
        },
        "usage": {
            "type": "voice",
            "quantity": 3,
            "unit": "sec"
        },
        "amount": 6,
        "description": "US Hollywood",
        "period": {
            "start": 63630348840
        },
        "id": "{DOC_ID}"
    },
    "revision": "{REVISION}",
    "request_id": "{REQUEST_ID}",
    "status": "success",
    "auth_token": "{AUTH_TOKEN}"
}

Credit / Debit

Credit or Debit a specific ledger.

  • The account_id for AUTH_TOKEN must be reseller of target account.
  • The parameter impact_reseller (boolean not required) when true will also create the document in the reseller.
  • The source.id field must be representative of a specific ledger entry. To that effect, the combination of that field, the period.start field, and the period.end field must be unique. This prevents mistakenly submitting the same ledger entry multiple times.

PUT /v2/accounts/{ACCOUNT_ID}/ledgers/debit

PUT /v2/accounts/{ACCOUNT_ID}/ledgers/credit

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/ledgers/debit
{
    "data": {
        "amount": 100,
        "description": "blablabla",
        "source": {
            "service": "tower/support/...",
            "id": "mac/mdn/..."
        },
        "usage": {
            "type": "data",
            "quantity": 5,
            "unit": "MB"
        },
        "period": {
            "start": 10938710938,
            "end": 214109238023899
        }
    },
    "impact_reseller": true
}

Fetch

GET /v2/accounts/{ACCOUNT_ID}/ledgers/{SOURCE_SERVICE}/{LEDGER_ID}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/ledgers/{SOURCE_SERVICE}/{LEDGER_ID}

Fetch Ledger and Account Summary Breakdown

Fetches the account ledger summary as well as a breakdown of ledgers per account for a given YYYYMM.

GET /v2/accounts/{ACCOUNT_ID}/ledgers/summary/{MODB_SUFFIX}

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/ledgers/summary/{MODB_SUFFIX}

Example

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/ledgers/summary/201905
"data": {
    "summary": {
      "per-minute-voip": {
        "amount": -880.0,
        "usage": {
          "type": "voice",
          "quantity": 232320,
          "unit": "sec"
        }
      },
      "payments": {
        "amount": 251970.82,
        "usage": {
          "type": "debit",
          "quantity": 0,
          "unit": "dollars"
        }
      },
      "prorations": {
        "amount": -1.9258,
        "usage": {
          "quantity": 0
        }
      },
      "rollovers": {
        "amount": 36.102,
        "usage": {
          "quantity": 0
        }
      }
    },
    "breakdown": [
      {
        "account": {
          "id": "de6fd29a54407cfe46e6c9d3828ab0d8",
          "name": "Account A"
        },
        "ledgers": {
          "payments": {
            "amount": -1250000.0,
            "usage": {
              "type": "debit",
              "quantity": 0,
              "unit": "dollars"
            }
          },
          "per-minute-voip": {
            "amount": -385.0,
            "usage": {
              "type": "voice",
              "quantity": 101640,
              "unit": "sec"
            }
          }
        },
        "total": -1250385.0
      },
      {
        "account": {
          "id": "cc580f94d7da53816a94b87b2a1d25f8",
          "name": "Account 1"
        },
        "ledgers": {
          "payments": {
            "amount": 1501970.82,
            "usage": {
              "type": "credit",
              "quantity": 0,
              "unit": "dollars"
            }
          },
          "prorations": {
            "amount": -1.9258,
            "usage": {
              "quantity": 0
            }
          },
          "rollovers": {
            "amount": 36.102,
            "usage": {
              "quantity": 0
            }
          }
        },
        "total": 1500004.9962
      },
      {
        "account": {
          "id": "a71a670531d7dc92d2a4f9fc6774df36",
          "name": "Account B"
        },
        "ledgers": {
          "per-minute-voip": {
            "amount": -495.0,
            "usage": {
              "type": "voice",
              "quantity": 130680,
              "unit": "sec"
            }
          }
        },
        "total": -495.0
      }
    ]
  }