--- title: "List credits" method: GET path: "/api/v1/credits" tags: ["credits"] --- # List credits `GET /api/v1/credits` ## Request - Base URL: `https://demo.invoiceninja.com` - URL: `https://demo.invoiceninja.com/api/v1/credits` - Auth: none declared. Required headers: `X-API-TOKEN`, `X-Requested-With` - TypeScript: (a function with typed inputs; its response is checked against the schema) Lists credits, search and filters allow fine grained lists to be generated. * * Query parameters can be added to performed more fine grained filtering of the credits, these are handled by the CreditFilters class which defines the methods available ## Query parameters - `include` string - `index` string - `per_page` integer - `page` integer - `sort` string[] ## Headers - `X-API-TOKEN` string, required - `X-Requested-With` string, required ## Response `200` A list of credits - object - `data` Credit[] - `id` string: The unique hashed ID of the credit - `user_id` string: The unique hashed ID of the user associated with the credit - `assigned_user_id` string: The unique hashed ID of the assigned user responsible for the credit - `client_id` string: The unique hashed ID of the client associated with the credit - `status_id` string: The ID representing the current status of the credit - `invoice_id` string: The unique hashed ID of the linked invoice to which the credit is applied - `number` string: The unique alphanumeric credit number per company - `po_number` string: The purchase order number referred to by the credit - `terms` string: The terms associated with the credit - `public_notes` string: Public notes for the credit - `private_notes` string: Private notes for internal use, not visible to the client - `footer` string: The footer text for the credit - `custom_value1` string: Custom value 1 for additional credit information - `custom_value2` string: Custom value 2 for additional credit information - `custom_value3` string: Custom value 3 for additional credit information - `custom_value4` string: Custom value 4 for additional credit information - `tax_name1` string: The name of the first tax applied to the credit - `tax_name2` string: The name of the second tax applied to the credit - `tax_rate1` number, float: The rate of the first tax applied to the credit - `tax_rate2` number, float: The rate of the second tax applied to the credit - `tax_name3` string: The name of the third tax applied to the credit - `tax_rate3` number, float: The rate of the third tax applied to the credit - `total_taxes` number, float: The total amount of taxes for the credit - `line_items` InvoiceItem[]: An array of objects which define the line items of the credit - `quantity` number: The quantity of the product offered for this line item - `cost` number, float: The cost of the product offered for this line item - `product_key` string: The product key of the product offered for this line item (Referred to as Product in the product tab) - `tags` string: A comma-separated snapshot of the product tag names for this line item - `product_cost` number, float: The cost of the product offered for this line item (Referred to as Cost in the product tab) - `notes` string: The notes/description for the product offered for this line item - `discount` number, float: The discount applied to the product offered for this line item - `is_amount_discount` boolean: Indicates whether the discount applied to the product offered for this line item is a fixed amount or a percentage - `tax_name1` string: The name of the first tax applied to the product offered for this line item - `tax_rate1` number, float: The rate of the first tax applied to the product offered for this line item - `tax_name2` string: The name of the second tax applied to the product offered for this line item - `tax_rate2` number, float: The rate of the second tax applied to the product offered for this line item - `tax_name3` string: The name of the third tax applied to the product offered for this line item - `tax_rate3` number, float: The rate of the third tax applied to the product offered for this line item - `sort_id` string: Deprecated - `line_total` number, float: The total amount of the product offered for this line item - `gross_line_total` number, float: The total amount of the product offered for this line item before discounts - `tax_amount` number, float: The total amount of tax applied to the product offered for this line item - `custom_value1` string: The first custom value of the product offered for this line item - `custom_value2` string: The second custom value of the product offered for this line item - `custom_value3` string: The third custom value of the product offered for this line item - `custom_value4` string: The fourth custom value of the product offered for this line item - `type_id` string: 1 = product, 2 = service, 3 unpaid gateway fee, 4 paid gateway fee, 5 late fee, 6 expense - `tax_id` string: The tax ID of the product: 1 product, 2 service, 3 digital, 4 shipping, 5 exempt, 5 reduced tax, 7 override, 8 zero rate, 9 reverse tax - `invitations` CreditInvitation[]: An array of objects which define the invitations of the credit - `id` string: The entity invitation hashed id - `client_contact_id` string: The client contact hashed id - `key` string: The invitation key - `link` string: The invitation link - `sent_date` string, date-time: The invitation sent date - `viewed_date` string, date-time: The invitation viewed date - `opened_date` string, date-time: The invitation opened date - `updated_at` number: Timestamp - `archived_at` number: Timestamp - `email_error` string: The email error - `email_status` string: The email status - `can_sign` boolean: Indicates whether the recipient contact may electronically sign this invitation. Mirrors the can_sign flag on the linked client contact at the time the invitation was issued. - `amount` number, float: The total amount of the credit - `balance` number, float: The outstanding balance of the credit - `paid_to_date` number, float: The total amount paid to date for the credit - `discount` number, float: The discount applied to the credit - `partial` number, float: The partial amount applied to the credit - `is_amount_discount` boolean: Indicates whether the discount applied is a fixed amount or a percentage - `is_deleted` boolean: Indicates whether the credit has been deleted - `uses_inclusive_taxes` boolean: Indicates whether the tax rates applied to the credit are inclusive or exclusive - `date` string, date: The date the credit was issued - `last_sent_date` string, date: The date the credit was last sent out - `next_send_date` string, date: The next scheduled date for sending a credit reminder - `partial_due_date` string, date: The due date for the partial amount of the credit - `due_date` string, date: The due date for the total amount of the credit - `settings` CompanySettings - `currency_id` string, required: The default currency id - `timezone_id` string: The timezone id - `date_format_id` string: The date format id - `military_time` boolean: Toggles 12/24 hour time - `language_id` string: The language id - `show_currency_code` boolean: Toggles whether the currency symbol or code is shown - `payment_terms` integer: -1 sets no payment term, 0 sets payment due immediately, positive integers indicates payment terms in days - `company_gateway_ids` string: A commad separate list of available gateways - `custom_value1` string: A Custom Label - `custom_value2` string: A Custom Label - `custom_value3` string: A Custom Label - `custom_value4` string: A Custom Label - `default_task_rate` number, float: The default task rate - `send_reminders` boolean: Toggles whether reminders are sent - `enable_client_portal_tasks` boolean: Show/hide the tasks panel in the client portal - `email_style` 'plain' | 'light' | 'dark' | 'custom': options include plain,light,dark,custom - `reply_to_email` string, email: The reply to email address - `bcc_email` string: A comma separate list of BCC emails - `pdf_email_attachment` boolean: Toggles whether to attach PDF as attachment - `ubl_email_attachment` boolean: Toggles whether to attach UBL as attachment - `email_style_custom` string: The custom template - `counter_number_applied` 'when_saved' | 'when_sent' | 'when_paid': enum when the invoice number counter is set - `quote_number_applied` 'when_saved' | 'when_sent': enum when the quote number counter is set - `custom_message_dashboard` string: A custom message which is displayed on the dashboard - `custom_message_unpaid_invoice` string: A custom message which is displayed in the client portal when a client is viewing a unpaid invoice. - `custom_message_paid_invoice` string: A custom message which is displayed in the client portal when a client is viewing a paid invoice. - `custom_message_unapproved_quote` string: A custom message which is displayed in the client portal when a client is viewing a unapproved quote. - `lock_invoices` 'off' | 'when_sent' | 'when_paid' | 'end_of_month': Toggles whether invoices are locked once sent and cannot be modified further - `auto_archive_invoice` boolean: Toggles whether a invoice is archived immediately following payment - `auto_archive_quote` boolean: Toggles whether a quote is archived after being converted to a invoice - `auto_convert_quote` boolean: Toggles whether a quote is converted to a invoice when approved - `inclusive_taxes` boolean: Boolean flag determining whether inclusive or exclusive taxes are used - `translations` object: JSON payload of customized translations - `task_number_pattern` string: Allows customisation of the task number pattern - `task_number_counter` integer: The incrementing counter for tasks - `reminder_send_time` integer: Time from UTC +0 when the email will be sent to the client - `expense_number_pattern` string: Allows customisation of the expense number pattern - `expense_number_counter` integer: The incrementing counter for expenses - `vendor_number_pattern` string: Allows customisation of the vendor number pattern - `vendor_number_counter` integer: The incrementing counter for vendors - `ticket_number_pattern` string: Allows customisation of the ticket number pattern - `ticket_number_counter` integer: The incrementing counter for tickets - `payment_number_pattern` string: Allows customisation of the payment number pattern - `payment_number_counter` integer: The incrementing counter for payments - `invoice_number_pattern` string: Allows customisation of the invoice number pattern - `invoice_number_counter` integer: The incrementing counter for invoices - `quote_number_pattern` string: Allows customisation of the quote number pattern - `quote_number_counter` integer: The incrementing counter for quotes - `client_number_pattern` string: Allows customisation of the client number pattern - `client_number_counter` integer: The incrementing counter for clients - `credit_number_pattern` string: Allows customisation of the credit number pattern - `credit_number_counter` integer: The incrementing counter for credits - `recurring_invoice_number_prefix` string: This string is prepended to the recurring invoice number - `reset_counter_frequency_id` integer: CONSTANT which is used to apply the frequency which the counters are reset - `reset_counter_date` string, date: The explicit date which is used to reset counters - `counter_padding` integer: Pads the counter with leading zeros - `shared_invoice_quote_counter` boolean: Flags whether to share the counter for invoices and quotes - `update_products` boolean: Determines if client fields are updated from third party APIs - `convert_products` boolean - `fill_products` boolean: Automatically fill products based on product_key - `invoice_terms` string: The default invoice terms - `quote_terms` string: The default quote terms - `invoice_taxes` integer: The number of Taxes that can be applied to the invoice - `invoice_design_id` string: The default design id (invoice, quote etc) - `quote_design_id` string: The default design id (invoice, quote etc) - `invoice_footer` string: The default invoice footer - `invoice_labels` string: JSON string of invoice labels - `tax_rate1` number, float: The tax rate (float) - `tax_name1` string: The tax name - `tax_rate2` number, float: The tax rate (float) - `tax_name2` string: The tax name - `tax_rate3` number, float: The tax rate (float) - `tax_name3` string: The tax name - `payment_type_id` string: The default payment type id - `custom_fields` string: JSON string of custom fields - `email_footer` string: The default email footer - `email_sending_method` 'default' | 'gmail' | 'office365' | 'client_postmark' | 'client_mailgun' | 'mailgun' | 'client_brevo': The email driver to use to send email - `gmail_sending_user_id` string: The hashed_id of the user account to send email from - `email_subject_invoice` string - `email_subject_quote` string - `email_subject_payment` string - `email_template_invoice` string: The full template for invoice emails - `email_template_quote` string: The full template for quote emails - `email_template_payment` string: The full template for payment emails - `email_subject_reminder1` string: Email subject for Reminder - `email_subject_reminder2` string: Email subject for Reminder - `email_subject_reminder3` string: Email subject for Reminder - `email_subject_reminder_endless` string: Email subject for endless reminders - `email_template_reminder1` string: The full template for Reminder 1 - `email_template_reminder2` string: The full template for Reminder 2 - `email_template_reminder3` string: The full template for Reminder 3 - `email_template_reminder_endless` string: The full template for enless reminders - `enable_portal_password` boolean: Toggles whether a password is required to log into the client portal - `show_accept_invoice_terms` boolean: Toggles whether the terms dialogue is shown to the client - `show_accept_quote_terms` boolean: Toggles whether the terms dialogue is shown to the client - `require_invoice_signature` boolean: Toggles whether a invoice signature is required - `require_quote_signature` boolean: Toggles whether a quote signature is required - `name` string: The company name - `company_logo` string: The company logo file - `website` string, uri: The company website URL - `address1` string: The company address line 1 - `address2` string: The company address line 2 - `city` string: The company city - `state` string: The company state - `postal_code` string: The company zip/postal code - `phone` string: The company phone - `email` string, email: The company email - `country_id` string: The country ID - `vat_number` string: The company VAT/TAX ID number - `page_size` string: The default page size - `font_size` number: The font size - `primary_font` string: The primary font - `secondary_font` string: The secondary font - `hide_paid_to_date` boolean: Flags whether to hide the paid to date field - `embed_documents` boolean: Toggled whether to embed documents in the PDF - `all_pages_header` boolean: The header for the PDF - `all_pages_footer` boolean: The footer for the PDF - `document_email_attachment` boolean: Toggles whether to attach documents in the email - `enable_client_portal_password` boolean: Toggles password protection of the client portal - `enable_email_markup` boolean: Toggles the use of markdown in emails - `enable_client_portal_dashboard` boolean: Toggles whether the client dashboard is shown in the client portal - `enable_client_portal` boolean: Toggles whether the entire client portal is displayed to the client, or only the context - `email_template_statement` string: The body of the email for statements - `email_subject_statement` string: The subject of the email for statements - `signature_on_pdf` boolean: Toggles whether the signature (if available) is displayed on the PDF - `quote_footer` string: The default quote footer - `email_subject_custom1` string: Custom reminder template subject - `email_subject_custom2` string: Custom reminder template subject - `email_subject_custom3` string: Custom reminder template subject - `email_template_custom1` string: Custom reminder template body - `email_template_custom2` string: Custom reminder template body - `email_template_custom3` string: Custom reminder template body - `enable_reminder1` boolean: Toggles whether this reminder is enabled - `enable_reminder2` boolean: Toggles whether this reminder is enabled - `enable_reminder3` boolean: Toggles whether this reminder is enabled - `num_days_reminder1` integer: The Reminder interval - `num_days_reminder2` integer: The Reminder interval - `num_days_reminder3` integer: The Reminder interval - `schedule_reminder1` 'after_invoice_date' | 'before_due_date' | 'after_due_date': (enum: after_invoice_date, before_due_date, after_due_date) - `schedule_reminder2` 'after_invoice_date' | 'before_due_date' | 'after_due_date': (enum: after_invoice_date, before_due_date, after_due_date) - `schedule_reminder3` 'after_invoice_date' | 'before_due_date' | 'after_due_date': (enum: after_invoice_date, before_due_date, after_due_date) - `late_fee_amount1` number, float: The late fee amount for reminder 1 - `late_fee_amount2` number, float: The late fee amount for reminder 2 - `late_fee_amount3` number, float: The late fee amount for reminder 2 - `endless_reminder_frequency_id` string: The frequency id of the endless reminder - `client_online_payment_notification` boolean: Determines if a client should receive the notification for a online payment - `client_manual_payment_notification` boolean: Determines if a client should receive the notification for a manually entered payment - `enable_e_invoice` boolean: Determines if e-invoicing is enabled - `default_expense_payment_type_id` string: The default payment type for expenses - `e_invoice_type` string: The e-invoice type - `mailgun_endpoint` 'api.mailgun.net' | 'api.eu.mailgun.net': The mailgun endpoint - used to determine whether US or EU endpoints are used - `client_initiated_payments` boolean: Determines if clients can initiate payments directly from the client portal - `client_initiated_payments_minimum` number, float: The minimum amount a client can pay - `sync_invoice_quote_columns` boolean: Determines if invoice and quote columns are synced for the PDF rendering, or if they use their own columns - `show_task_item_description` boolean: Determines if the task item description is shown on the invoice - `allow_billable_task_items` boolean: Determines if task items can be marked as billable - `accept_client_input_quote_approval` boolean: Determines if clients can approve quotes and also pass through a PO Number reference - `custom_sending_email` string, email: When using Mailgun or Postmark, the FROM email address can be customized using this setting. - `show_paid_stamp` boolean: Determines if the PAID stamp is shown on the invoice - `show_shipping_address` boolean: Determines if the shipping address is shown on the invoice - `company_logo_size` integer: The size of the company logo on the PDF - percentage value between 0 and 100 - `show_email_footer` boolean: Determines if the email footer is shown on emails - `email_alignment` 'left' | 'center' | 'right': The alignment of the email body text, options include left / center / right - `auto_bill_standard_invoices` boolean: Determines if standard invoices are automatically billed when they are created or due - `postmark_secret` string: The Postmark secret API key - `mailgun_secret` string: The Mailgun secret API key - `mailgun_domain` string: The Mailgun domain - `send_email_on_mark_paid` boolean: Determines if an email is sent when an invoice is marked as paid - `vendor_portal_enable_uploads` boolean: Determines if vendors can upload files to the portal - `besr_id` string: The BESR ID - `qr_iban` string: The IBAN for the QR code - `email_subject_purchase_order` string: The email subject for purchase orders - `email_template_purchase_order` string: The email template for purchase orders - `require_purchase_order_signature` boolean: Determines if a signature is required on purchase orders - `purchase_order_public_notes` string: The public notes for purchase orders - `purchase_order_terms` string: The terms for purchase orders - `purchase_order_footer` string: The footer for purchase orders - `purchase_order_design_id` string: The design id for purchase orders - `purchase_order_number_pattern` string: The pattern for purchase order numbers - `purchase_order_number_counter` integer: The counter for purchase order numbers - `page_numbering_alignment` 'left' | 'center' | 'right': The alignment for page numbering: options include left / center / right - `page_numbering` boolean: Determines if page numbering is enabled on Document PDFs - `auto_archive_invoice_cancelled` boolean: Determines if invoices are automatically archived when they are cancelled - `email_from_name` string: The FROM name for emails when using Custom emailers - `show_all_tasks_client_portal` 'all' | 'uninvoiced' | 'invoiced': Determines if all tasks are shown on the client portal - `entity_send_time` integer: The time that emails are sent. The time is localized to the clients locale, integer values from 1 - 24 - `shared_invoice_credit_counter` boolean: Determines if the invoice and credit counter are shared - `reply_to_name` string: The reply to name for emails - `hide_empty_columns_on_pdf` boolean: Determines if empty columns are hidden on PDFs - `enable_reminder_endless` boolean: Determines if endless reminders are enabled - `use_credits_payment` boolean: Determines if credits can be used as a payment method - `recurring_invoice_number_pattern` string: The pattern for recurring invoice numbers - `recurring_invoice_number_counter` integer: The counter for recurring invoice numbers - `client_portal_under_payment_minimum` number, float: The minimum payment payment - `auto_bill_date` 'on_send_date' | 'on_due_date': Determines when the invoices are auto billed - `primary_color` string: The primary color for the client portal / document highlights - `secondary_color` string: The secondary color for the client portal / document highlights - `client_portal_allow_under_payment` boolean: Determines if clients can pay invoices under the invoice amount due - `client_portal_allow_over_payment` boolean: Determines if clients can pay invoices over the invoice amount - `auto_bill` 'off' | 'always' | 'optin' | 'optout': Determines how autobilling is applied for recurring invoices - `client_portal_terms` string: The terms which are displayed on the client portal - `client_portal_privacy_policy` string: The privacy policy which is displayed on the client portal - `client_can_register` boolean: Determines if clients can register on the client portal - `portal_design_id` string: The design id for the client portal - `late_fee_endless_percent` number, float: The late fee percentage for endless late fees - `late_fee_endless_amount` number, float: The late fee amount for endless late fees - `auto_email_invoice` boolean: Determines if invoices are automatically emailed when they are created - `email_signature` string: The email signature for emails - `classification` string: The classification for the company - `valid_until` string: Default validity period for quotes - `credit_terms` string: Default terms for credit notes - `credit_footer` string: Default footer for credit notes - `last_viewed` number: The timestamp of the last time the credit was viewed - `updated_at` number: The timestamp of the last time the credit was updated - `archived_at` number: The timestamp of the last time the credit was archived - `custom_surcharge1` number, float: First custom surcharge amount - `custom_surcharge2` number, float: Second Custom Surcharge - `custom_surcharge3` number, float: Third Custom Surcharge - `custom_surcharge4` number, float: Fourth Custom Surcharge - `custom_surcharge_tax1` boolean: Toggles charging taxes on custom surcharge amounts - `custom_surcharge_tax2` boolean: Toggles charging taxes on custom surcharge amounts - `custom_surcharge_tax3` boolean: Toggles charging taxes on custom surcharge amounts - `custom_surcharge_tax4` boolean: Toggles charging taxes on custom surcharge amounts - `location_id` string: The client location id that this invoice relates to - `design_id` string: The unique identifier of the design template used for this credit - `exchange_rate` number, float: The exchange rate used for currency conversion - `project_id` string: The unique identifier of the project associated with this credit - `subscription_id` string: The unique identifier of the subscription associated with this credit - `vendor_id` string: The unique identifier of the vendor associated with this credit - `meta` Meta - `pagination` Pagination - `total` integer: The total number of items - `count` integer: The number of items per page - `per_page` integer: The number of items per page - `current_page` integer: The current page number - `total_pages` integer: The total number of pages - `links` object: The pagination links ## Other responses - `401`: Authentication error - `403`: Authorization error - `422`: Validation error - `429`: Rate Limit Exceeded - `5XX`: Server error - `default`: Unexpected Error ## Changes - **2026-08-21** `a8b7a375e4ed`: 1 info - added the optional property `data/items/line_items/items/tags` to the response with the `200` status - **2026-05-06** `89876e7e51d6`: 1 info - added the new optional `query` request parameter `sort` - **2026-04-20** `69a36036d334`: 2 info - added the optional property `data/items/invitations/items/can_sign` to the response with the `200` status - the response optional property `data/items/id` became read-only for the status `200` - **2025-11-22** `00ad5cc89fad`: 5 info - added the optional property `data/items/design_id` to the response with the `200` status - added the optional property `data/items/exchange_rate` to the response with the `200` status - added the optional property `data/items/project_id` to the response with the `200` status - added the optional property `data/items/subscription_id` to the response with the `200` status - …1 more - **2025-10-10** `f36c4f94ae7b`: 3 info - added the new optional `query` request parameter `index` - added the new optional `query` request parameter `page` - added the new optional `query` request parameter `per_page` [Operation history](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference/changes/api/v1/credits/get.md) --- [API](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference.md) - [All operations](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/invoiceninja/apis/invoice-ninja-api-reference/revisions/bcda1f823746?raw)