INinvoiceninja
payments

List payments

Changed on

Lists payments, search and filters allow fine grained lists to be generated.

    Query parameters can be added to performed more fine grained filtering of the payments, these are handled by the PaymentFilters class which defines the methods available
get/api/v1/payments

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=date|desc.

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

Payments accept payments columns plus client, contact, and document-related sorts defined in the payment filters. Unsupported keys are ignored.

[
  "date|desc",
  "amount|asc"
]
statusstring

Filter the entity based on their status. ie active / archived / deleted. Format is a comma separated string with any of the following options:

  • active
  • archived
  • deleted
GET /api/v1/invoices?status=archived,deleted
Returns only archived and deleted invoices
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:

  • amount
  • date
  • custom_value1
  • custom_value2
  • custom_value3
  • custom_value4
numberstring

Search payments by payment number

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 payments

Example response

{
  "data": [
    {
      "id": "Opnel5aKBz",
      "client_id": "Opnel5aKBz",
      "invitation_id": "Opnel5aKBz",
      "client_contact_id": "Opnel5aKBz",
      "user_id": "Opnel5aKBz",
      "type_id": "1",
      "date": "1-1-2014",
      "transaction_reference": "xcsSxcs124asd",
      "assigned_user_id": "Opnel5aKBz",
      "private_notes": "The payment was refunded due to error",
      "is_manual": true,
      "is_deleted": true,
      "amount": 10,
      "refunded": 10,
      "updated_at": 1434342123,
      "archived_at": 1434342123,
      "company_gateway_id": "3",
      "paymentables": {
        "id": "AS3df3A",
        "invoice_id": "AS3df3A",
        "credit_id": "AS3df3A",
        "refunded": 10,
        "amount": 10,
        "updated_at": 1434342123,
        "created_at": 1434342123
      },
      "invoices": [
        {
          "invoice_id": "Opnel5aKBz",
          "amount": "2"
        }
      ],
      "credits": [
        {
          "credit_id": "Opnel5aKBz",
          "amount": "2"
        }
      ],
      "number": "PAY_101",
      "category_id": "Opnel5aKBz",
      "custom_value1": "Payment reference 123",
      "custom_value2": "Approved by John",
      "custom_value3": "Urgent payment",
      "custom_value4": "Q1 2024",
      "exchange_currency_id": "2",
      "exchange_rate": 1,
      "idempotency_key": "key_1234567890abcdef"
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 1,
      "current_page": 1,
      "total_pages": 1
    }
  }
}

Changes

  • 89876e7e51d6Revision changes
    • info

      for the query request parameter sort, the type was generalized from string to array

  • 69a36036d334Revision changes
    • info

      the response optional property // became read-only for the status

    • info

      the response optional property /// became read-only for the status