> ## Documentation Index > Fetch the complete documentation index at: https://docs.metrifox.com/llms.txt > Use this file to discover all available pages before exploring further. # Get billing history > Retrieve the billing history for a subscription, including all invoices, credit notes, and payment statuses ## OpenAPI ````yaml GET /api/v1/subscriptions/{subscription_id}/billing-history openapi: 3.0.1 info: title: Metrifox API Documentation version: v1 description: >- Welcome to Metrifox Platform's API documentation. This comprehensive API suite enables seamless integration with our platform, providing secure and efficient access to our services. servers: - url: https://{defaultHost} variables: defaultHost: default: api.metrifox.com security: - api_key: [] paths: /api/v1/subscriptions/{subscription_id}/billing-history: get: tags: - Subscriptions summary: Get billing history for a subscription description: > Retrieves the billing history for a specific subscription. Returns a list of all invoices associated with the subscription, including: - **Draft invoices**: Upcoming invoices not yet finalized - **Paid invoices**: Successfully paid invoices - **Credit notes**: Invoices with negative amounts representing credits or refunds (e.g., from plan downgrades) Each entry includes the invoice amount, payment status, due date, and source type indicating whether it originated from a regular billing cycle or an order (e.g., plan change). operationId: getSubscriptionBillingHistory parameters: - name: subscription_id in: path required: true description: The unique subscription identifier (UUID) schema: type: string format: uuid example: 625f5cee-259b-4994-b7eb-416b9e551f2c responses: '200': description: Billing history fetched successfully content: application/json: schema: $ref: '#/components/schemas/BillingHistoryResponse' examples: billing_history: summary: Billing History Response value: statusCode: 200 message: Billing history fetched successfully meta: {} data: - invoice_id: 0d9e5a0e-7de4-48c6-b01a-b1759394578b invoice_number: null issued_date: '2026-03-12T16:55:21.847Z' due_date: '2026-04-01T23:59:59.999Z' total_amount: 21 amount_paid: 0 balance_due: 21 currency: USD status: draft payment_method: null source_type: billing_cycle created_at: '2026-02-13T13:01:32.715Z' - invoice_id: 762d8b5f-e416-4d88-8461-2a357b91ff25 invoice_number: INV027 issued_date: '2026-02-13T13:01:01.520Z' due_date: '2026-03-05T23:59:59.999Z' total_amount: -23.0356 amount_paid: 0 balance_due: -23.0356 currency: USD status: paid payment_method: null source_type: order created_at: '2026-02-13T13:01:02.598Z' errors: {} '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Subscription not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: statusCode: 404 message: Subscription not found errors: subscription_id: - >- Subscription with ID '625f5cee-259b-4994-b7eb-416b9e551f2c' does not exist x-codeSamples: - lang: python label: Python SDK source: | from metrifox_sdk import MetrifoxClient client = MetrifoxClient(api_key="your_api_key") # Get billing history for a subscription subscription_id = "625f5cee-259b-4994-b7eb-416b9e551f2c" response = client.subscriptions.get_billing_history(subscription_id) for invoice in response['data']: print(f"Invoice: {invoice['invoice_number'] or 'Draft'}") print(f" Amount: {invoice['currency']} {invoice['total_amount']}") print(f" Status: {invoice['status']}") print(f" Due: {invoice['due_date']}") print(f" Source: {invoice['source_type']}") - lang: javascript label: Javascript SDK source: > import { init } from "metrifox-js"; const metrifoxClient = init({ apiKey: process.env.METRIFOX_API_KEY }); // Get billing history for a subscription const subscriptionId = "625f5cee-259b-4994-b7eb-416b9e551f2c"; const response = await metrifoxClient.subscriptions.getBillingHistory(subscriptionId); response.data.forEach(invoice => { console.log(`Invoice: ${invoice.invoice_number || 'Draft'}`); console.log(` Amount: ${invoice.currency} ${invoice.total_amount}`); console.log(` Status: ${invoice.status}`); console.log(` Due: ${invoice.due_date}`); console.log(` Source: ${invoice.source_type}`); }); - lang: ruby label: Ruby SDK source: > require 'metrifox-sdk' # Initialize with configuration METRIFOX_SDK = MetrifoxSDK.init({ api_key: "your-api-key" }) # Get billing history for a subscription subscription_id = "625f5cee-259b-4994-b7eb-416b9e551f2c" response = METRIFOX_SDK.subscriptions.get_billing_history(subscription_id) response['data'].each do |invoice| puts "Invoice: #{invoice['invoice_number'] || 'Draft'}" puts " Amount: #{invoice['currency']} #{invoice['total_amount']}" puts " Status: #{invoice['status']}" puts " Due: #{invoice['due_date']}" puts " Source: #{invoice['source_type']}" end components: schemas: BillingHistoryResponse: type: object properties: statusCode: type: integer example: 200 message: type: string example: Billing history fetched successfully meta: type: object additionalProperties: true description: Additional metadata data: type: array items: $ref: '#/components/schemas/BillingHistoryEntry' description: Array of billing history entries errors: type: object additionalProperties: true description: Any errors that occurred ErrorResponse: type: object properties: message: type: string description: Error message errors: type: object additionalProperties: true description: Detailed error information BillingHistoryEntry: type: object properties: invoice_id: type: string format: uuid description: Unique invoice identifier invoice_number: type: string nullable: true description: Invoice number (null for draft invoices) issued_date: type: string format: date-time description: When the invoice was issued due_date: type: string format: date-time description: Payment due date total_amount: type: number description: Total invoice amount (negative for credits/refunds) amount_paid: type: number description: Amount already paid balance_due: type: number description: Remaining balance due currency: type: string description: Currency code for the invoice status: type: string description: Invoice status (e.g., draft, paid, pending, overdue) payment_method: type: string nullable: true description: Payment method used (null if unpaid) source_type: type: string description: Source of the invoice (e.g., billing_cycle, order) created_at: type: string format: date-time description: When the invoice record was created securitySchemes: api_key: type: apiKey name: x-api-key in: header ````