Retrieve a month’s bill

Returns billing details for a selected month.

Retrieves the billing data for the requested month.

Check that the response has ok === "BILL_FOUND" before using its billing fields. A missing bill or failed lookup returns error: "BILL_NOT_FOUND" with HTTP 200, so HTTP status alone does not establish that a bill was found.

The billYearMonth path parameter is in YYYY-MM format. For example, to retrieve your bill for March 2019 you would use 2019-03.

Request example

Set BILL_YEAR_MONTH to your resource value without percent-encoding it.

Canceled Workspaces cannot create new bearer tokens. This endpoint remains available with an existing active Auth Key: use the signed billing recipe instead of the token setup below. The key must grant this endpoint’s required scopes.

Run this request in a server-side shell with curl and a suitable bearer token in TRANSLOADIT_TOKEN. If you need a token, expand the setup below.

if ! TOKEN_RESPONSE="$(curl --fail-with-body -sS \
  --request POST \
  --url 'https://api2.transloadit.com/token' \
  --user "${TRANSLOADIT_KEY:?Set TRANSLOADIT_KEY}:${TRANSLOADIT_SECRET:?Set TRANSLOADIT_SECRET}" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'aud=api2' \
  --data-urlencode 'scope=billing:read')"; then
  printf '%s\n' "$TOKEN_RESPONSE" >&2
  exit 1
fi
TRANSLOADIT_TOKEN="$(printf '%s' "$TOKEN_RESPONSE" |
  jq -er '.access_token | strings | select(length > 0)')" || exit 1

curl --fail-with-body -sS --request GET --get \
  --url "https://api2.transloadit.com/bill/${BILL_YEAR_MONTH:?Set BILL_YEAR_MONTH}" \
  --header "Authorization: Bearer ${TRANSLOADIT_TOKEN:?Set TRANSLOADIT_TOKEN}" \
  --data-urlencode 'params={}'

This endpoint accepts signed params or a bearer token. See Authentication for setup instructions.

Required scope for the Auth Key or bearer token: billing:read.

Signed requests require both a signature and a future params.auth.expires timestamp. Bearer tokens do not require either.

Authentication fields in this list apply to signed requests. With a bearer token, you can omit params.auth and the separate signature field. Compare the authentication-specific request parameters below.

Billing access after cancellation

Canceled Workspaces cannot create new bearer tokens. To retrieve their bills, use a signed request with an existing active Auth Key and its Auth Secret instead of the token setup above. The key must still grant the scope listed for this endpoint.

The Node.js SDK signs billing requests directly; it does not call /token. In a trusted server-side Node.js project, install it with yarn add @transloadit/node. Set TRANSLOADIT_KEY, TRANSLOADIT_SECRET, and BILL_YEAR_MONTH (for example, 2026-08) in the environment. Keep the secret on your backend.

This SDK example uses sha384, the default for newly created API keys. If your key uses another signature algorithm, follow Signature Authentication with that configured algorithm instead.

Save the following as bill.mjs and run node bill.mjs:

import { Transloadit } from '@transloadit/node'

const { TRANSLOADIT_KEY, TRANSLOADIT_SECRET, BILL_YEAR_MONTH } = process.env
if (!TRANSLOADIT_KEY || !TRANSLOADIT_SECRET || !BILL_YEAR_MONTH) {
  throw new Error('Set TRANSLOADIT_KEY, TRANSLOADIT_SECRET, and BILL_YEAR_MONTH')
}

const transloadit = new Transloadit({
  authKey: TRANSLOADIT_KEY,
  authSecret: TRANSLOADIT_SECRET,
})
const bill = await transloadit.getBill(BILL_YEAR_MONTH)
if (bill.ok !== 'BILL_FOUND') throw new Error('No bill was returned')
console.log(JSON.stringify(bill, null, 2))

The invoice_id is null for the current month.