Skip to content
Space Invoices Documentation

Payments

Payments

Payment management operations.
Record payments against invoices and credit notes.
Supports partial payments, credit note applications to invoices, and automatic payment status updates.

Endpoints
POST/paymentsGET/paymentsGET/payments/{id}PATCH/payments/{id}DELETE/payments/{id}

Create a new payment

POST/payments

Record a payment against an invoice, credit note, or both.
At least one document reference is required.
For type credit_note, both invoice_id and credit_note_id are required (applying credit to invoice).
Document payment totals are automatically updated.
Credit note payments cannot exceed the credit note total.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Optional - defaults to the first created entity if not provided.

Body parameters

amountnumberrequired
typestringrequired
datestringoptional

Payment date in YYYY-MM-DD format

invoice_idstringoptional
metadataobjectoptional

Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.

Other parameters
credit_note_idstringoptional
advance_invoice_idstringoptional
referencestringoptional
notestringoptional
curl -X POST "https://eu.spaceinvoices.com/payments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_id": "inv_abc123def456",
    "amount": 1200,
    "type": "cash"
  }'
Example:
Response
json
{
  "id": "pmt_abc123def456",
  "invoice_id": "inv_abc123def456",
  "credit_note_id": null,
  "advance_invoice_id": null,
  "amount": 1200,
  "type": "cash",
  "date": "2024-01-15T00:00:00.000Z",
  "reference": null,
  "note": null,
  "entity_id": "ent_xyz789",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z"
}
Example:

List all payments

GET/payments

Retrieve a paginated list of payments with optional filtering and sorting. Supports cursor-based pagination for efficient navigation, flexible JSON querying with MongoDB-style operators, full-text search, and sorting by various payment properties.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Optional - defaults to the first created entity if not provided.

Query parameters

limitintegeroptional

Number of results per request.

Default: 10

next_cursorstringoptional

Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.

prev_cursorstringoptional

Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response.

include_total_countbooleanoptional

Whether to include the total count of items in pagination.total.
Default is true.
When false, pagination.total returns -1 for better performance.

order_byoptional
querystring<json>optional

JSON query object for filtering results. Supports MongoDB-style operators.

Supported operators:
- equals or direct value - Exact match (default)
- gte - Greater than or equal
- lte - Less than or equal
- gt - Greater than
- lt - Less than
- in - Value in array
- notIn - Value not in array
- contains - String contains (case-insensitive)
- startsWith - String starts with
- endsWith - String ends with
- between - Value between two numbers/dates [min, max]

Allowed fields: id, invoice_id, amount, type, date, reference, note, metadata, created_at, updated_at

Examples:
- {"total": {"gte": 1000}} - Invoices over 1000
- {"customer.name": {"contains": "Acme"}} - Customer name contains "Acme"
- {"date": {"between": ["2025-01-01", "2025-12-31"]}} - Date range

searchstringoptional

Full-text search query to filter results across multiple fields.
Searches are case-insensitive and match partial strings.
Searches across all text fields including names, descriptions, addresses, and metadata values.

includestringoptional

Comma-separated list of relations to include in the response. Allowed: Invoice, CreditNote, AdvanceInvoice

curl "https://eu.spaceinvoices.com/payments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID"
Response

Returns

dataarray
paginationobject

Pagination metadata including cursors and result counts

json
{
  "data": [
    {
      "id": "pmt_abc123def456",
      "invoice_id": "inv_abc123def456",
      "credit_note_id": null,
      "advance_invoice_id": null,
      "amount": 1200,
      "type": "cash",
      "date": "2024-01-15T00:00:00.000Z",
      "reference": null,
      "note": null,
      "entity_id": "ent_xyz789",
      "metadata": {},
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "pmt_def789ghi012",
      "invoice_id": "inv_abc123def456",
      "credit_note_id": null,
      "advance_invoice_id": null,
      "amount": 600,
      "type": "bank_transfer",
      "date": "2024-01-10T00:00:00.000Z",
      "reference": "TXN-2024-0015",
      "note": "First installment payment",
      "entity_id": "ent_xyz789",
      "metadata": {
        "source": "web_app",
        "processor": "stripe"
      },
      "created_at": "2024-01-10T14:20:00.000Z",
      "updated_at": "2024-01-10T14:20:00.000Z"
    }
  ],
  "pagination": {
    "total": 2,
    "next_cursor": null,
    "prev_cursor": null,
    "has_more": false
  }
}

Get payment by ID

GET/payments/{id}

Retrieve a single payment by its unique identifier. Returns the complete payment details including amount, type, date, and reference information.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Optional - defaults to the first created entity if not provided.

Path parameters

idstring<resource-id>required

Unique resource identifier

Query parameters

includestringoptional

Comma-separated list of relations to include in the response. Allowed: Invoice, CreditNote, AdvanceInvoice

curl "https://eu.spaceinvoices.com/payments/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID"
Response
json
{
  "id": "pmt_def789ghi012",
  "invoice_id": "inv_abc123def456",
  "credit_note_id": null,
  "advance_invoice_id": null,
  "amount": 600,
  "type": "bank_transfer",
  "date": "2024-01-10T00:00:00.000Z",
  "reference": "TXN-2024-0015",
  "note": "First installment payment",
  "entity_id": "ent_xyz789",
  "metadata": {
    "source": "web_app",
    "processor": "stripe"
  },
  "created_at": "2024-01-10T14:20:00.000Z",
  "updated_at": "2024-01-10T14:20:00.000Z"
}

Update a payment

PATCH/payments/{id}

Update an existing payment.
Only the provided fields will be updated.
Document references cannot be changed.
If amount is changed, payment totals on all linked documents are automatically recalculated.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Optional - defaults to the first created entity if not provided.

Path parameters

idstring<resource-id>required

Unique resource identifier

Body parameters

amountnumberoptional
typestringoptional
datestringoptional

Payment date in YYYY-MM-DD format

metadataobjectoptional

Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.

Other parameters
referencestringoptional
notestringoptional
curl -X PATCH "https://eu.spaceinvoices.com/payments/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 800
  }'
Example:
Response
json
{
  "id": "pmt_def789ghi012",
  "invoice_id": "inv_abc123def456",
  "credit_note_id": null,
  "advance_invoice_id": null,
  "amount": 800,
  "type": "bank_transfer",
  "date": "2024-01-10T00:00:00.000Z",
  "reference": "TXN-2024-0016-UPDATED",
  "note": "Updated payment note",
  "entity_id": "ent_xyz789",
  "metadata": {},
  "created_at": "2024-01-10T14:20:00.000Z",
  "updated_at": "2024-01-15T09:00:00.000Z"
}

Delete a payment

DELETE/payments/{id}

Delete a payment by its unique identifier. Payment totals on all linked documents (invoice, credit note) are automatically recalculated after deletion.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Optional - defaults to the first created entity if not provided.

Path parameters

idstring<resource-id>required

Unique resource identifier

curl -X DELETE "https://eu.spaceinvoices.com/payments/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID"