INinvoiceninja
Recurring Invoices

List recurring invoices

Changed on

GET /api/v1/recurring_invoices

Lists invoices with the option to chain multiple query parameters allowing fine grained filtering of the list.

get/api/v1/recurring_invoices

Request

Query parameters

includestring
Example:first_load

Includes child relationships in the response, format is comma separated. Check each model for the list of associated includes

indexstring
Example:user

Replaces the default response index from data to a user specific string

ie.

  ?index=new_index

response is wrapped

  {
    'new_index' : [
      .....  
    ]
  }
per_pageinteger
Example:20

The number of records to return for each request, default is 20

pageinteger
Example:1

The page number to return for this request (when performing pagination), default is 1

sortstring[]

Order the list by choosing a column and direction. Each value uses the form column|asc or column|desc.

Single sort — for example sort=next_send_date|asc.

Multiple sorts — for example
sort[]=id|desc&sort[]=number|asc.

Recurring invoices use the recurring-invoice table columns plus the client/contact-style sorts exposed by RecurringInvoiceFilters. Unsupported keys are ignored.

[
  "number|asc",
  "next_send_date|desc"
]
client_idstring

Filters the entity list by client_id. Suitable when you only want the entities of a specific client.

GET /api/v1/invoices?client_id=AxB7Hjk9
Returns only invoices for the specified client
created_atinteger

Filters the entity list by the created at timestamp. Parameter value can be a datetime string or unix timestamp

GET /api/v1/invoices?created_at=2022-01-10
Returns entities created on January 10th, 2022
updated_atinteger

Filters the entity list by the updated at timestamp. Parameter value can be a datetime string or unix timestamp

GET /api/v1/invoices?updated_at=2022-01-10
Returns entities last updated on January 10th, 2022
is_deletedboolean

Filters the entity list by entities that have been deleted.

GET /api/v1/invoices?is_deleted=true
Returns only soft-deleted entities
filter_deleted_clientsstring

Filters the entity list and only returns entities for clients that have not been deleted

GET /api/v1/invoices?filter_deleted_clients=true
Returns only invoices for active (non-deleted) clients
vendor_idstring

Filters the entity list by an associated vendor

GET /api/v1/purchases?vendor_id=AxB7Hjk9
Returns only purchases for the specified vendor
filterstring

Searches across a range of columns including:

  • custom_value1
  • custom_value2
  • custom_value3
  • custom_value4
client_statusstring

A comma separated list of invoice status strings. Valid options include:

  • all
  • active
  • paused
  • completed
numberstring

Filters the list by number.

product_keystring

Filters the list by product_key.

next_send_betweenstring

Filters the list by next_send_between.

frequency_idstring

Filters the list by frequency_id.

Headers

X-API-TOKENstring required
Example:TOKEN

The API token to be used for authentication

X-Requested-Withstring required
Example:XMLHttpRequest

Used to send the XMLHttpRequest header

Response

A list of recurring_invoices

Example response

{
  "data": [
    {
      "id": "Opnel5aKBz",
      "user_id": "Opnel5aKBz",
      "assigned_user_id": "Opnel5aKBz",
      "client_id": "Opnel5aKBz",
      "status_id": "4",
      "frequency_id": 4,
      "remaining_cycles": 4,
      "number": "INV_101",
      "po_number": "PO-1234",
      "terms": "These are invoice terms",
      "public_notes": "These are some public notes",
      "private_notes": "These are some private notes",
      "custom_value1": "2022-10-01",
      "custom_value2": "Something custom",
      "tax_rate1": 10,
      "tax_rate2": 10,
      "tax_rate3": 10,
      "total_taxes": 10,
      "line_items": {},
      "amount": 10,
      "balance": 10,
      "paid_to_date": 10,
      "discount": 10,
      "partial": 10,
      "is_amount_discount": true,
      "is_deleted": true,
      "uses_inclusive_taxes": true,
      "date": "1994-07-30",
      "last_sent_date": "1994-07-30",
      "next_send_date": "1994-07-30",
      "partial_due_date": "1994-07-30",
      "due_date": "1994-07-30",
      "settings": {
        "currency_id": "1",
        "timezone_id": "15",
        "date_format_id": "15",
        "military_time": true,
        "language_id": "1",
        "show_currency_code": true,
        "payment_terms": 1,
        "company_gateway_ids": "1,2,3,4",
        "custom_value1": "Custom Label",
        "custom_value2": "Custom Label",
        "custom_value3": "Custom Label",
        "custom_value4": "Custom Label",
        "default_task_rate": 10,
        "send_reminders": true,
        "enable_client_portal_tasks": true,
        "email_style": "light",
        "reply_to_email": "email@gmail.com",
        "bcc_email": "email@gmail.com, contact@gmail.com",
        "pdf_email_attachment": true,
        "ubl_email_attachment": true,
        "email_style_custom": "<HTML></HTML>",
        "counter_number_applied": "when_sent",
        "quote_number_applied": "when_sent",
        "custom_message_dashboard": "Please pay invoices immediately",
        "custom_message_unpaid_invoice": "Please pay invoices immediately",
        "custom_message_paid_invoice": "Thanks for paying this invoice!",
        "custom_message_unapproved_quote": "Please approve quote",
        "lock_invoices": "off",
        "auto_archive_invoice": true,
        "auto_archive_quote": true,
        "auto_convert_quote": true,
        "inclusive_taxes": true,
        "translations": {},
        "task_number_pattern": "{$year}-{$counter}",
        "task_number_counter": 1,
        "reminder_send_time": 32400,
        "expense_number_pattern": "{$year}-{$counter}",
        "expense_number_counter": 1,
        "vendor_number_pattern": "{$year}-{$counter}",
        "vendor_number_counter": 1,
        "ticket_number_pattern": "{$year}-{$counter}",
        "ticket_number_counter": 1,
        "payment_number_pattern": "{$year}-{$counter}",
        "payment_number_counter": 1,
        "invoice_number_pattern": "{$year}-{$counter}",
        "invoice_number_counter": 1,
        "quote_number_pattern": "{$year}-{$counter}",
        "quote_number_counter": 1,
        "client_number_pattern": "{$year}-{$counter}",
        "client_number_counter": 1,
        "credit_number_pattern": "{$year}-{$counter}",
        "credit_number_counter": 1,
        "recurring_invoice_number_prefix": "R",
        "reset_counter_frequency_id": 1,
        "reset_counter_date": "2019-01-01",
        "counter_padding": 1,
        "shared_invoice_quote_counter": true,
        "update_products": true,
        "convert_products": true,
        "fill_products": true,
        "invoice_terms": "Invoice Terms are...",
        "quote_terms": "Quote Terms are...",
        "invoice_taxes": 1,
        "invoice_design_id": "1",
        "quote_design_id": "1",
        "invoice_footer": "1",
        "invoice_labels": "1",
        "tax_rate1": 10,
        "tax_name1": "GST",
        "tax_rate2": 10,
        "tax_name2": "GST",
        "tax_rate3": 10,
        "tax_name3": "GST",
        "payment_type_id": "1",
        "custom_fields": "{}",
        "email_footer": "A default email footer",
        "email_sending_method": "default",
        "gmail_sending_user_id": "F76sd34D",
        "email_subject_invoice": "Your Invoice Subject",
        "email_subject_quote": "Your Quote Subject",
        "email_subject_payment": "Your Payment Subject",
        "email_template_invoice": "<HTML></HTML>",
        "email_template_quote": "<HTML></HTML>",
        "email_template_payment": "<HTML></HTML>",
        "email_subject_reminder1": "<HTML></HTML>",
        "email_subject_reminder2": "<HTML></HTML>",
        "email_subject_reminder3": "<HTML></HTML>",
        "email_subject_reminder_endless": "<HTML></HTML>",
        "email_template_reminder1": "<HTML></HTML>",
        "email_template_reminder2": "<HTML></HTML>",
        "email_template_reminder3": "<HTML></HTML>",
        "email_template_reminder_endless": "<HTML></HTML>",
        "enable_portal_password": true,
        "show_accept_invoice_terms": true,
        "show_accept_quote_terms": true,
        "require_invoice_signature": true,
        "require_quote_signature": true,
        "name": "Acme Co",
        "company_logo": "logo.png",
        "website": "https://www.acme.com",
        "address1": "Suite 888",
        "address2": "5 Jimbo Way",
        "city": "Sydney",
        "state": "Florida",
        "postal_code": "90210",
        "phone": "555-213-3948",
        "email": "joe@acme.co",
        "country_id": "1",
        "vat_number": "32 120 377 720",
        "page_size": "A4",
        "font_size": 9,
        "primary_font": "roboto",
        "secondary_font": "roboto",
        "email_template_statement": "template matter",
        "email_subject_statement": "subject matter",
        "quote_footer": "the quote footer",
        "email_subject_custom1": "Custom Subject 1",
        "email_subject_custom2": "Custom Subject 2",
        "email_subject_custom3": "Custom Subject 3",
        "email_template_custom1": "<HTML></HTML>",
        "email_template_custom2": "<HTML></HTML>",
        "email_template_custom3": "<HTML></HTML>",
        "num_days_reminder1": 9,
        "num_days_reminder2": 9,
        "num_days_reminder3": 9,
        "schedule_reminder1": "after_invoice_date",
        "schedule_reminder2": "after_invoice_date",
        "schedule_reminder3": "after_invoice_date",
        "late_fee_amount1": 10,
        "late_fee_amount2": 20,
        "late_fee_amount3": 100,
        "endless_reminder_frequency_id": "1",
        "default_expense_payment_type_id": "0",
        "e_invoice_type": "EN16931",
        "mailgun_endpoint": "api.mailgun.net",
        "client_initiated_payments_minimum": 10,
        "custom_sending_email": "bob@gmail.com",
        "company_logo_size": 100,
        "email_alignment": "left",
        "postmark_secret": "123456",
        "mailgun_secret": "123456",
        "mailgun_domain": "sandbox123456.mailgun.org",
        "besr_id": "123456",
        "qr_iban": "CH123456",
        "email_subject_purchase_order": "Purchase Order",
        "email_template_purchase_order": "Please see attached your purchase order.",
        "purchase_order_public_notes": "Please see attached your purchase order.",
        "purchase_order_terms": "Please see attached your purchase order.",
        "purchase_order_footer": "Please see attached your purchase order.",
        "purchase_order_design_id": "hd677df",
        "purchase_order_number_pattern": "PO-000000",
        "purchase_order_number_counter": 1,
        "page_numbering_alignment": "left",
        "email_from_name": "Bob Smith",
        "show_all_tasks_client_portal": "all",
        "entity_send_time": 9,
        "reply_to_name": "Bob Smith",
        "recurring_invoice_number_pattern": "R-000000",
        "recurring_invoice_number_counter": 1,
        "client_portal_under_payment_minimum": 10,
        "auto_bill_date": "on_send_date",
        "primary_color": "#ffffff",
        "secondary_color": "#ffffff",
        "auto_bill": "off",
        "client_portal_terms": "Please see attached your invoice.",
        "client_portal_privacy_policy": "These are the terms of use for using the client portal.",
        "portal_design_id": "hd677df",
        "late_fee_endless_percent": 10,
        "late_fee_endless_amount": 10,
        "email_signature": "Bob Smith",
        "classification": "individual",
        "valid_until": "30 days",
        "credit_terms": "Credit note terms",
        "credit_footer": "Credit note footer"
      },
      "last_viewed": 1434342123,
      "updated_at": 1434342123,
      "archived_at": 1434342123,
      "custom_surcharge1": 10,
      "custom_surcharge2": 10,
      "custom_surcharge3": 10,
      "custom_surcharge4": 10,
      "custom_surcharge_tax1": true,
      "custom_surcharge_tax2": true,
      "custom_surcharge_tax3": true,
      "custom_surcharge_tax4": true,
      "location_id": "Opnel5aKBz",
      "auto_bill": "always",
      "auto_bill_enabled": true,
      "design_id": "Opnel5aKBz",
      "due_date_days": 30,
      "exchange_rate": 1,
      "next_send_date_client": "2024-12-31",
      "project_id": "Opnel5aKBz",
      "vendor_id": "Opnel5aKBz"
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 1,
      "current_page": 1,
      "total_pages": 1
    }
  }
}

Changes