# Retrieve a month’s bill Returns billing details for a selected month. `GET` `https://api2.transloadit.com/bill/{billYearMonth}` 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](#billing-access-after-cancellation) 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](/docs/api/token-post.md) in `TRANSLOADIT_TOKEN`. If you need a token, expand the setup below. **Need a bearer token?** In a trusted server-side shell with `curl` and `jq`, set `TRANSLOADIT_KEY` and `TRANSLOADIT_SECRET` to your Auth Key and Auth Secret. Keep both credentials and the resulting token secret; never run this setup in browser code. First, create a token with this endpoint’s required scopes. Your Auth Key must already grant those scopes. ```bash 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 ``` Keep this shell open and run the request below. Reuse the token while it remains valid. ```bash 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={}' ``` ## Authentication This endpoint accepts signed `params` or a bearer token. See [Authentication](/docs/api/authentication.md) 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. ## Path parameters * `billYearMonth` (path segment), required. pattern: `^[0-9]{4}-(?:0[1-9]|1[0-2])$` ## Query parameters * `params` (JSON string). A JSON-encoded object whose supported keys are listed below. * `signature` (string). Required for signed requests. Omit this field when using a bearer token. ## Supported keys inside the signed `params` field 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. [Complete JSON Schema](/api-reference/schemas/bill-date-get/params-fields.json) `params`: Only the fields listed for this object are accepted. ### `params.auth` (required for signed requests; optional with a bearer token) [`object`](#params-fields-auth-expires) Contains the Transloadit API key and signature-authentication metadata for a Billing request. `params.auth`: Only the fields listed for this object are accepted. #### `params.auth.expires` (required) `string` ISO 8601 expiration timestamp in the future. Required when a request is signed or requires signature authentication; bearer-authenticated requests may omit it. #### `params.auth.key` (required) `string` Transloadit API key used to authenticate requests ### `params.nonce` `string | integer` Unique, random value included in signed request params to make each signature unique and prevent accidental signature reuse. ## Request parameters by authentication method ### With signed params Include your Auth Key as `params.auth.key`. When signing the request, include a future `params.auth.expires` timestamp and send the signature in the separate `signature` field. The field definitions below use paths inside `params`. [Complete JSON Schema](/api-reference/schemas/bill-date-get/signed-params.json) `params`: Only the fields listed for this object are accepted. Uses the field definitions above: [`params.auth`](#params-fields-auth), [`params.nonce`](#params-fields-nonce) ### With a bearer token Send the bearer token in the `Authorization` header. You can omit `params.auth` and the separate `signature` field. Other required parameters still apply. The field definitions below use paths inside `params`. [Complete JSON Schema](/api-reference/schemas/bill-date-get/bearer-params.json) `params`: Only the fields listed for this object are accepted. Uses the field definitions above: [`params.nonce`](#params-fields-nonce) #### `params.auth` [`object`](#bearer-params-auth-expires) Contains the Transloadit API key and signature-authentication metadata for a Billing request. `params.auth`: Only the fields listed for this object are accepted. ##### `params.auth.expires` `string` ISO 8601 expiration timestamp in the future. Required when a request is signed or requires signature authentication; bearer-authenticated requests may omit it. ##### `params.auth.key` `string` Transloadit API key used to authenticate requests ## 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](/docs/api/authentication.md#how-to-generate-signatures) with that configured algorithm instead. Save the following as `bill.mjs` and run `node bill.mjs`: ```js 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)) ``` ## Response Here’s an example response body: ```jsonc { "additional_gb": 0, "additional_gb_fee": 0, "address_1": "Jimbostreet 19", "address_2": "", "bill_limit": 0, "city": "Berlin", "company": "Jimbo Jones GmbH", "country": "Germany", "created": "2014-07-01T06:58:32.000Z", "credit": 0, "email": "testuser@example.org", "invoice_id": "0d04b65924da41d4b68c80f776d196d5", "is_prorated": false, "month": "2014-06", "ok": "BILL_FOUND", "plan": { "gb_included": 35, "gb_limit": null, "has_lifetime_limit": false, "id": "3599821193a1f77baafb98e5f8fb17a6", "price_per_gb": 2.85, "price_per_month": 99 }, "reverse_charge_vat": false, "reward_discount": 1.98, "reward_discount_percent": 2, "robots": { "/assemblies": { "factor": 0, "freeGb": 0, "gb": 0, "gbFactorApplied": 0, "rawGb": 0 }, "/s3/store": { "factor": 10, "freeGb": 0.57, "gb": 0.6, "gbFactorApplied": 1.17, "rawGb": 11.75 }, "/video/encode": { "factor": 1, "freeGb": 0, "gb": 21.05, "gbFactorApplied": 21.05, "rawGb": 21.05 }, "/video/thumbs": { "factor": 10, "freeGb": 0, "gb": 0.34, "gbFactorApplied": 0.34, "rawGb": 3.42 } }, "signup_discount": 0, "signup_discount_percent": 0, "state": null, "sub_total": 99, "to": "Test User", "total": 115.45, "used_gb": 21.99, "vat": 18.43, "vat_id": "", "vat_rate": 0.19, "zip": "10117" } ``` ### 2xx success JSON response body. `application/json` `text/plain; charset=utf-8` #### Response body schema [Complete JSON Schema](/api-reference/schemas/bill-date-get/response-1-body.json) **Any of the following schemas may apply:** * **Variant 1** The response contains only the fields listed for this object. * **`additional_gb`** `number` (minimum: 0) * **`additional_gb_fee`** `number` * **`address_1`** `null | string` * **`address_2`** `null | string` * **`bill_limit`** `number` * **`city`** `null | string` * **`company`** `null | string` * **`country`** `null | string` * **`country_id`** `null | string` * **`coupon_discount`** `number | string | null` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * `null` * **`coupon_discount_percent`** `number | string | null` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * `null` * **`created` (required)** `string | null` (minimum length: 1) * **`credit` (required)** `number | string | null` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * `null` * **`currency`** `null | string` * **`email`** `null | string` * **`final_sub_total`** `number` * **`invoice_id` (required)** `null` * **`is_prorated` (required)** `boolean` * **`month` (required)** `string` Validation pattern (regular expression): `^[0-9]{4}-(?:0[1-9]|1[0-2])$` * **`ok` (required)** `string` (always: "BILL\_FOUND") * **`plan` (required)** [`object`](#response-1-body-anyOf-1-plan-gb_included) `plan`: The response may contain additional fields. * **`plan.gb_included` (required)** `number | string` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * **`plan.gb_limit` (required)** `number | string | null` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * `null` * **`plan.has_lifetime_limit` (required)** `boolean | 0 | 1 | "0" | "1" | null` **Any of the following schemas may apply:** * `boolean | 0 | 1 | "0" | "1"` * `null` * **`plan.id` (required)** `null | string` * **`plan.price_per_gb` (required)** `number | string` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * **`plan.price_per_month` (required)** `number | string` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * **`po_number`** `null | string` * **`reverse_charge_vat`** `boolean` * **`reward_discount`** `number | string | null` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * `null` * **`reward_discount_percent`** `number | string | null` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * `null` * **`robots` (required)** `object` * **Additional property schema** `object` (required properties: gb) [Additional schema details are available in the complete JSON Schema.](/api-reference/schemas/bill-date-get/response-1-body.json) * **`signup_discount`** `number | string | null` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * `null` * **`signup_discount_percent`** `number | string | null` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * `null` * **`state`** `null | string` * **`sub_total` (required)** `number` * **`tiers`** `any value` * **`to`** `null | string` * **`to_contact_email_address`** `null | string` * **`total` (required)** `number` * **`used_gb`** `number` (minimum: 0) * **`vat`** `number` * **`vat_id`** `null | string` * **`vat_rate`** `number` * **`zip`** `null | string` * **Variant 2** The response contains only the fields listed for this object. * **`additional_gb`** `number` (minimum: 0) * **`additional_gb_fee`** `number` * **`address_1`** `null | string` * **`address_2`** `null | string` * **`bill_limit`** `number` * **`city`** `null | string` * **`company`** `null | string` * **`country`** `null | string` * **`country_id`** `null | string` * **`coupon_discount`** `number | string | null` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * `null` * **`coupon_discount_percent`** `number | string | null` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * `null` * **`created` (required)** `string | null` (minimum length: 1) * **`credit` (required)** `number | string | null` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * `null` * **`currency`** `null | string` * **`custom_expenses`** `any value` * **`email`** `null | string` * **`final_sub_total`** `number` * **`invoice_id` (required)** `string | number` * **`is_prorated` (required)** `boolean` * **`month` (required)** `string` Validation pattern (regular expression): `^[0-9]{4}-(?:0[1-9]|1[0-2])$` * **`ok` (required)** `string` (always: "BILL\_FOUND") * **`plan` (required)** [`object`](#response-1-body-anyOf-2-plan-gb_included) `plan`: The response may contain additional fields. * **`plan.gb_included` (required)** `number | string` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * **`plan.gb_limit` (required)** `number | string | null` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * `null` * **`plan.has_lifetime_limit` (required)** `boolean | 0 | 1 | "0" | "1" | null` **Any of the following schemas may apply:** * `boolean | 0 | 1 | "0" | "1"` * `null` * **`plan.id` (required)** `null | string` * **`plan.price_per_gb` (required)** `number | string` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * **`plan.price_per_month` (required)** `number | string` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * **`po_number`** `null | string` * **`reverse_charge_vat`** `boolean` * **`reward_discount`** `number | string | null` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * `null` * **`reward_discount_percent`** `number | string | null` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * `null` * **`robots` (required)** `string | number | boolean | null | Array | object` **Any of the following schemas may apply:** * `string` * `number` * `boolean` * `null` * `Array` * **Array item schema** `any value` * `object` * **Additional property schema** `any value` * **`signup_discount`** `number | string | null` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * `null` * **`signup_discount_percent`** `number | string | null` * `number` * `string` Validation pattern (regular expression): `^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$` * `null` * **`state`** `null | string` * **`sub_total` (required)** `number` * **`tiers`** `any value` * **`to`** `null | string` * **`to_contact_email_address`** `null | string` * **`total` (required)** `number` * **`used_gb`** `number` (minimum: 0) * **`vat`** `number` * **`vat_id`** `null | string` * **`vat_rate`** `number` * **`zip`** `null | string` * **error: "BILL\_NOT\_FOUND", http\_code: 200** The response contains only the fields listed for this object. * **`error` (required)** `string` (always: "BILL\_NOT\_FOUND") * **`http_code` (required)** `number` (always: 200) * **`message` (required)** `string` * **`reason` (required)** `string` ### Error response JSON response body. `application/json` `text/plain; charset=utf-8` #### Response body schema [Complete JSON Schema](/api-reference/schemas/bill-date-get/response-2-body.json) At least one of these properties is required: error, message, reason The response may contain additional fields. ##### `assembly_id` `string` ##### `error` `string` (minimum length: 1) ##### `http_code` `number | string` * `number` * `string` [Validation pattern (regular expression)](/api-reference/schemas/bill-date-get/response-2-body.json) ##### `message` `string` Human-readable explanation of the error. Its wording can vary; use the `error` code when handling a specific failure. ##### `reason` `null | string | number | boolean | Array | object` **Any of the following schemas may apply:** * `null` * `string` * `number` * `boolean` * `Array` * **Array item schema** `any value` * `object` * **Additional property schema** `any value` ### HTTP 400 JSON response body. `application/json` `text/plain; charset=utf-8` #### Response body schema [Complete JSON Schema](/api-reference/schemas/bill-date-get/response-3-body.json) **Named errors and the general error format** * **error: "SIGNATURE\_REUSE\_DETECTED"** The request was denied for security reasons. If you think this is in error, please get in touch with support. The response may contain additional fields. * **`error` (required)** `string` (always: "SIGNATURE\_REUSE\_DETECTED") * **`http_code`** `number` (always: 400) * **`message`** `string` Human-readable explanation of the error. Its wording can vary; use the `error` code when handling a specific failure. * **General error format** [See the general error response fields.](#response-2-body) The `invoice_id` is `null` for the current month.