--- title: "List all billing statements" method: GET path: "/billing/statements" tags: ["Billing"] --- # List all billing statements `GET /billing/statements` Returns a list of all billing statements for the instance. The statements are returned sorted by creation date, with the newest statements appearing first. Pagination is supported. ## Query parameters - `paginated` boolean - `limit` integer - `offset` integer ## Response `200` A list of billing statements. - PaginatedBillingStatementResponse - `data` BillingStatement[], required — Array of billing statements. - `object` 'commerce_statement', required — String representing the object's type. Objects of the same type share the same value. - `id` string, required — Unique identifier for the billing statement. - `instance_id` string, required — The ID of the instance this statement belongs to. - `timestamp` integer, required — Unix timestamp (in milliseconds) when the statement was created. - `payer` CommercePayerResponse, required - `object` 'commerce_payer', required — String representing the object's type. Objects of the same type share the same value. - `id` string, required — Unique identifier for the payer. - `instance_id` string, required — Unique identifier for the Clerk instance. - `user_id` string, nullable — User ID for user-type payers. - `first_name` string, nullable — First name of the payer. - `last_name` string, nullable — Last name of the payer. - `email` string, nullable — Email address of the payer. - `organization_id` string, nullable — Organization ID for org-type payers. - `organization_name` string, nullable — Organization name for org-type payers. - `image_url` string — URL of the payer's image/avatar. - `credits_balance` CommerceMoneyResponse - `amount` integer, required — The amount in cents. - `amount_formatted` string, required — The formatted amount as a string (e.g., "$49.99"). - `currency` string, required — The currency code (e.g., "USD"). - `currency_symbol` string, required — The currency symbol (e.g., "$"). - `created_at` integer — Unix timestamp (in milliseconds) when the payer was created. - `updated_at` integer — Unix timestamp (in milliseconds) when the payer was last updated. - `status` 'open' | 'closed', required — The current status of the statement. - `totals` object, required — Totals for the statement. - `grand_total` CommerceMoneyResponse, required - `amount` integer, required — The amount in cents. - `amount_formatted` string, required — The formatted amount as a string (e.g., "$49.99"). - `currency` string, required — The currency code (e.g., "USD"). - `currency_symbol` string, required — The currency symbol (e.g., "$"). - `subtotal` CommerceMoneyResponse, required - `amount` integer, required — The amount in cents. - `amount_formatted` string, required — The formatted amount as a string (e.g., "$49.99"). - `currency` string, required — The currency code (e.g., "USD"). - `currency_symbol` string, required — The currency symbol (e.g., "$"). - `base_fee` CommerceMoneyResponse, required - `amount` integer, required — The amount in cents. - `amount_formatted` string, required — The formatted amount as a string (e.g., "$49.99"). - `currency` string, required — The currency code (e.g., "USD"). - `currency_symbol` string, required — The currency symbol (e.g., "$"). - `tax_total` CommerceMoneyResponse, required - `amount` integer, required — The amount in cents. - `amount_formatted` string, required — The formatted amount as a string (e.g., "$49.99"). - `currency` string, required — The currency code (e.g., "USD"). - `currency_symbol` string, required — The currency symbol (e.g., "$"). - `groups` object[], required — Array of statement groups. - `object` 'commerce_statement_group', required — String representing the object's type. Objects of the same type share the same value. - `timestamp` integer, required — Unix timestamp (in milliseconds) of the date the group's payment attempts were created - `items` BillingPaymentAttempt[], required — The payment attempts included in the group - `object` 'commerce_payment', required — String representing the object's type. Objects of the same type share the same value. - `id` string, required — Unique identifier for the payment attempt. - `payment_id` string, required — Unique identifier for the associated payment. - `instance_id` string, required — The ID of the instance this payment attempt belongs to. - `charge_type` string, required — Type of charge for this payment attempt. - `payee_id` string, required — Unique identifier for the payee. - `payee` object, required — The payee associated with this payment attempt. - `payer_id` string, required — Unique identifier for the payer. - `payer` CommercePayerResponse, required - `object` 'commerce_payer', required — String representing the object's type. Objects of the same type share the same value. - `id` string, required — Unique identifier for the payer. - `instance_id` string, required — Unique identifier for the Clerk instance. - `user_id` string, nullable — User ID for user-type payers. - `first_name` string, nullable — First name of the payer. - `last_name` string, nullable — Last name of the payer. - `email` string, nullable — Email address of the payer. - `organization_id` string, nullable — Organization ID for org-type payers. - `organization_name` string, nullable — Organization name for org-type payers. - `image_url` string — URL of the payer's image/avatar. - `credits_balance` CommerceMoneyResponse - `amount` integer, required — The amount in cents. - `amount_formatted` string, required — The formatted amount as a string (e.g., "$49.99"). - `currency` string, required — The currency code (e.g., "USD"). - `currency_symbol` string, required — The currency symbol (e.g., "$"). - `created_at` integer — Unix timestamp (in milliseconds) when the payer was created. - `updated_at` integer — Unix timestamp (in milliseconds) when the payer was last updated. - `subscription_item_id` string — Unique identifier for the associated subscription item. - `subscription_item` object — The subscription item associated with this payment attempt. - `amount` CommerceMoneyResponse, required - `amount` integer, required — The amount in cents. - `amount_formatted` string, required — The formatted amount as a string (e.g., "$49.99"). - `currency` string, required — The currency code (e.g., "USD"). - `currency_symbol` string, required — The currency symbol (e.g., "$"). - `totals` CommerceTotalsResponse2 - `subtotal` CommerceMoneyResponse, required - `amount` integer, required — The amount in cents. - `amount_formatted` string, required — The formatted amount as a string (e.g., "$49.99"). - `currency` string, required — The currency code (e.g., "USD"). - `currency_symbol` string, required — The currency symbol (e.g., "$"). - `base_fee` CommerceMoneyResponse, required - `amount` integer, required — The amount in cents. - `amount_formatted` string, required — The formatted amount as a string (e.g., "$49.99"). - `currency` string, required — The currency code (e.g., "USD"). - `currency_symbol` string, required — The currency symbol (e.g., "$"). - `tax_total` CommerceMoneyResponse, required - `amount` integer, required — The amount in cents. - `amount_formatted` string, required — The formatted amount as a string (e.g., "$49.99"). - `currency` string, required — The currency code (e.g., "USD"). - `currency_symbol` string, required — The currency symbol (e.g., "$"). - `grand_total` CommerceMoneyResponse, required - `amount` integer, required — The amount in cents. - `amount_formatted` string, required — The formatted amount as a string (e.g., "$49.99"). - `currency` string, required — The currency code (e.g., "USD"). - `currency_symbol` string, required — The currency symbol (e.g., "$"). - `per_unit_totals` CommercePerUnitTotal2[] - `name` string, required — Name of the billable unit (for example, seats) - `block_size` integer, required — Number of units included in each pricing block - `tiers` CommercePerUnitTotalTier2[], required — Computed totals for each pricing tier - … - `credits` CommerceCreditsResponse - `proration` CommerceProrationCreditDetailResponse, required - … - `payer` CommercePayerCreditResponse, required - … - `total` CommerceMoneyResponse, required - … - `discounts` BillingDiscountsResponse - `proration` BillingProrationDiscountDetail, required - … - `total` CommerceMoneyResponse, required - … - `payment_method_id` string, required — Unique identifier for the payment method. - `payment_method` CommercePaymentMethodResponse, required - `object` 'commerce_payment_method', required — String representing the object's type. Objects of the same type share the same value. - `id` string, required — Unique identifier for the payment method. - `payer_id` string, required — Unique identifier for the payer. - `payment_type` 'card' | 'link' | 'payer-credits', required — The payment method type. - `is_default` boolean — Whether this is the default payment method for the payer. - `gateway` string, required — The payment gateway. - `gateway_external_id` string, required — External ID in the payment gateway. - `gateway_external_account_id` string, nullable, required — External account ID in the payment gateway. - `last4` string, nullable, required — Last 4 digits of the card (for card payment methods). - `status` 'active' | 'disconnected', required — Status of the payment method. - `wallet_type` string, nullable — Type of wallet (if applicable). - `card_type` string, nullable, required — Type of card (if applicable). - `expiry_year` integer, nullable — Card expiration year (for card payment methods). - `expiry_month` integer, nullable — Card expiration month (for card payment methods). - `created_at` integer — Unix timestamp (in milliseconds) when the payment method was created. - `updated_at` integer — Unix timestamp (in milliseconds) when the payment method was last updated. - `is_removable` boolean — Whether this payment method can be removed. - `statement_id` string, required — Unique identifier for the associated statement. - `gateway_external_id` string, nullable, required — External identifier from the payment gateway. - `gateway_external_url` string, nullable, required — External URL from the payment gateway. - `status` 'pending' | 'paid' | 'failed', required — The current status of the payment attempt. - `paid_at` integer, nullable, required — Unix timestamp (in milliseconds) when the payment was completed. - `failed_at` integer, nullable, required — Unix timestamp (in milliseconds) when the payment failed to be processed. - `created_at` integer, required — Unix timestamp (in milliseconds) when the payment attempt was created. - `updated_at` integer, required — Unix timestamp (in milliseconds) when the payment attempt was last updated. - `total_count` integer, required — Total number of billing statements. ## Other responses - `400` — Request was not successful - `401` — Authentication invalid - `422` — Invalid request parameters - `500` — Request was not successful --- [API](https://skmtc.net/clerk/apis/clerk-backend-api.md) · [All operations](https://skmtc.net/clerk/apis/clerk-backend-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clerk/clerk-backend-api/revisions/cf036e7951d3/schema)