Skip to content
Space Invoices Documentation

Payments

Payments

Payment management operations.
Record payments against outgoing documents and incoming purchase documents.
Supports partial payments, credit note applications, and automatic payment status updates.

Endpoints
IntroductionPOST/paymentsGET/paymentsGET/payments/{id}PATCH/payments/{id}DELETE/payments/{id}DELETE/payments/{id}/permanentPOST/payments/{id}/restore

The Payment object

object

Attributes

idstring
amountnumber
typestring

Payment type/method

Possible values: "cash", "bank_transfer", "card", "check", "paypal", "coupon", "other", "credit_note", "advance"

datestring<date-time>

Date the payment was received (ISO 8601 datetime at midnight UTC)

invoice_idstring
referencestring
notestring
metadataobject

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 attributes
credit_note_idstring
advance_invoice_idstring
incoming_purchase_document_idstring
applied_to_incoming_purchase_document_idstring
currency_codestring
amount_convertednumber
tagstring
entity_idstring
deleted_atstring<date-time>
created_atstring<date-time>
updated_atstring<date-time>
Invoiceobject
CreditNoteobject
AdvanceInvoiceobject
IncomingPurchaseDocumentobject
AppliedToIncomingPurchaseDocumentobject
Examplejson
{
  "id": "pmt_def789ghi012",
  "invoice_id": "inv_abc123def456",
  "credit_note_id": null,
  "advance_invoice_id": null,
  "incoming_purchase_document_id": null,
  "applied_to_incoming_purchase_document_id": null,
  "amount": 12500,
  "type": "bank_transfer",
  "date": "2024-01-10T00:00:00.000Z",
  "reference": "ORB-2025-042",
  "tag": null,
  "note": "First installment for antenna array",
  "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",
  "deleted_at": null
}

Create a new payment

POST/payments

Record a payment against an outgoing document or an incoming purchase document.
At least one document reference is required.
For new direct outgoing payments, prefer document_id; the API infers invoice_id, credit_note_id, or advance_invoice_id from the ID prefix.
Legacy type-specific fields remain supported for backward compatibility.
For outgoing type credit_note, both invoice_id and credit_note_id are required.
For incoming settlement type credit_note, both incoming_purchase_document_id and applied_to_incoming_purchase_document_id are required.
Document payment totals are automatically updated.
Credit note refunds or settlements cannot exceed the remaining credit balance.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Body parameters

amountnumberrequired
typestringrequired

Payment type/method

Possible values: "cash", "bank_transfer", "card", "check", "paypal", "coupon", "other", "credit_note", "advance"

datestringoptional

Payment date in YYYY-MM-DD format

invoice_idstringoptional
referencestringoptional
notestringoptional
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
incoming_purchase_document_idstringoptional
applied_to_incoming_purchase_document_idstringoptional
tagstringoptional
document_idstringoptional
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": 1500,
    "type": "cash"
  }'
Example:
Response

Returns

idstring
amountnumber
typestring

Payment type/method

Possible values: "cash", "bank_transfer", "card", "check", "paypal", "coupon", "other", "credit_note", "advance"

datestring<date-time>

Date the payment was received (ISO 8601 datetime at midnight UTC)

invoice_idstring
referencestring
notestring
metadataobject

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_idstring
advance_invoice_idstring
incoming_purchase_document_idstring
applied_to_incoming_purchase_document_idstring
currency_codestring
amount_convertednumber
tagstring
entity_idstring
deleted_atstring<date-time>
created_atstring<date-time>
updated_atstring<date-time>
Invoiceobject
CreditNoteobject
AdvanceInvoiceobject
IncomingPurchaseDocumentobject
AppliedToIncomingPurchaseDocumentobject
json
{
  "id": "pmt_abc123def456",
  "invoice_id": "inv_abc123def456",
  "credit_note_id": null,
  "advance_invoice_id": null,
  "incoming_purchase_document_id": null,
  "applied_to_incoming_purchase_document_id": null,
  "amount": 1500,
  "type": "cash",
  "date": "2024-01-15T00:00:00.000Z",
  "reference": null,
  "tag": null,
  "note": null,
  "entity_id": "ent_xyz789",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z",
  "deleted_at": null
}
Example:

List all payments

GET/payments

Retrieve a paginated list of payments with optional filtering and sorting. Supports cursor-based pagination, flexible JSON querying with MongoDB-style operators, full-text search, and sorting across both outgoing and incoming purchase document payment references.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Query parameters

limitintegeroptional

Number of results per request.

Default: 10

next_cursorstringoptional

Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.

prev_cursorstringoptional

Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. 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

Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with - for descending order. When paginating, reuse cursors only with the same effective ordering.

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, credit_note_id, advance_invoice_id, incoming_purchase_document_id, applied_to_incoming_purchase_document_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.

Available relations:
- Invoice - The invoice this payment is linked to
- CreditNote - The credit note this payment is linked to
- AdvanceInvoice - The advance invoice this payment is linked to
- IncomingPurchaseDocument - The incoming purchase document this payment is linked to
- AppliedToIncomingPurchaseDocument - The incoming purchase invoice this credit note settlement is applied to

Usage:
?include=Invoice
?include=Invoice,CreditNote,AdvanceInvoice,IncomingPurchaseDocument,AppliedToIncomingPurchaseDocument

deletedbooleanoptional

When true, returns only soft-deleted (trashed) items. Default false excludes deleted items.

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

Returns

dataarray of objects
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,
      "incoming_purchase_document_id": null,
      "applied_to_incoming_purchase_document_id": null,
      "amount": 1500,
      "type": "cash",
      "date": "2024-01-15T00:00:00.000Z",
      "reference": null,
      "tag": null,
      "note": null,
      "entity_id": "ent_xyz789",
      "metadata": {},
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z",
      "deleted_at": null
    },
    {
      "id": "pmt_def789ghi012",
      "invoice_id": "inv_abc123def456",
      "credit_note_id": null,
      "advance_invoice_id": null,
      "incoming_purchase_document_id": null,
      "applied_to_incoming_purchase_document_id": null,
      "amount": 12500,
      "type": "bank_transfer",
      "date": "2024-01-10T00:00:00.000Z",
      "reference": "ORB-2025-042",
      "tag": null,
      "note": "First installment for antenna array",
      "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",
      "deleted_at": null
    }
  ],
  "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. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstring<resource-id>required

Unique resource identifier

Query parameters

includestringoptional

Comma-separated list of relations to include in the response.

Available relations:
- Invoice - The invoice this payment is linked to
- CreditNote - The credit note this payment is linked to
- AdvanceInvoice - The advance invoice this payment is linked to
- IncomingPurchaseDocument - The incoming purchase document this payment is linked to
- AppliedToIncomingPurchaseDocument - The incoming purchase invoice this credit note settlement is applied to

Usage:
?include=Invoice
?include=Invoice,CreditNote,AdvanceInvoice,IncomingPurchaseDocument,AppliedToIncomingPurchaseDocument

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

Returns

idstring
amountnumber
typestring

Payment type/method

Possible values: "cash", "bank_transfer", "card", "check", "paypal", "coupon", "other", "credit_note", "advance"

datestring<date-time>

Date the payment was received (ISO 8601 datetime at midnight UTC)

invoice_idstring
referencestring
notestring
metadataobject

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_idstring
advance_invoice_idstring
incoming_purchase_document_idstring
applied_to_incoming_purchase_document_idstring
currency_codestring
amount_convertednumber
tagstring
entity_idstring
deleted_atstring<date-time>
created_atstring<date-time>
updated_atstring<date-time>
Invoiceobject
CreditNoteobject
AdvanceInvoiceobject
IncomingPurchaseDocumentobject
AppliedToIncomingPurchaseDocumentobject
json
{
  "id": "pmt_def789ghi012",
  "invoice_id": "inv_abc123def456",
  "credit_note_id": null,
  "advance_invoice_id": null,
  "incoming_purchase_document_id": null,
  "applied_to_incoming_purchase_document_id": null,
  "amount": 12500,
  "type": "bank_transfer",
  "date": "2024-01-10T00:00:00.000Z",
  "reference": "ORB-2025-042",
  "tag": null,
  "note": "First installment for antenna array",
  "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",
  "deleted_at": null
}

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 outgoing or incoming documents are automatically recalculated.
System-managed settlement payments cannot be modified.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstring<resource-id>required

Unique resource identifier

Body parameters

amountnumberoptional
typestringoptional

Payment type/method

Possible values: "cash", "bank_transfer", "card", "check", "paypal", "coupon", "other", "credit_note", "advance"

datestringoptional

Payment date in YYYY-MM-DD format

referencestringoptional
notestringoptional
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
tagstringoptional
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": 15000
  }'
Example:
Response

Returns

idstring
amountnumber
typestring

Payment type/method

Possible values: "cash", "bank_transfer", "card", "check", "paypal", "coupon", "other", "credit_note", "advance"

datestring<date-time>

Date the payment was received (ISO 8601 datetime at midnight UTC)

invoice_idstring
referencestring
notestring
metadataobject

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_idstring
advance_invoice_idstring
incoming_purchase_document_idstring
applied_to_incoming_purchase_document_idstring
currency_codestring
amount_convertednumber
tagstring
entity_idstring
deleted_atstring<date-time>
created_atstring<date-time>
updated_atstring<date-time>
Invoiceobject
CreditNoteobject
AdvanceInvoiceobject
IncomingPurchaseDocumentobject
AppliedToIncomingPurchaseDocumentobject
json
{
  "id": "pmt_def789ghi012",
  "invoice_id": "inv_abc123def456",
  "credit_note_id": null,
  "advance_invoice_id": null,
  "amount": 15000,
  "type": "bank_transfer",
  "date": "2024-01-10T00:00:00.000Z",
  "reference": "MSN-2025-001-FINAL",
  "tag": null,
  "note": "Final payment for ground station antenna array",
  "entity_id": "ent_xyz789",
  "metadata": {},
  "created_at": "2024-01-10T14:20:00.000Z",
  "updated_at": "2024-01-15T09:00:00.000Z",
  "deleted_at": null
}

Delete a payment

DELETE/payments/{id}

Soft delete a payment by its unique identifier. The payment is moved to trash and can be restored later. Payment totals on all linked outgoing or incoming documents are automatically recalculated after deletion. System-managed settlement payments remain immutable.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

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"

Permanently delete a payment

DELETE/payments/{id}/permanent

Permanently delete a soft-deleted payment. Only payments in the trash can be permanently deleted. Document payment totals are automatically recalculated.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstring<resource-id>required

Unique resource identifier

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

Restore a deleted payment

POST/payments/{id}/restore

Restore a soft-deleted payment from the trash. Document payment totals are automatically recalculated.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstring<resource-id>required

Unique resource identifier

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

Returns

idstring
amountnumber
typestring

Payment type/method

Possible values: "cash", "bank_transfer", "card", "check", "paypal", "coupon", "other", "credit_note", "advance"

datestring<date-time>

Date the payment was received (ISO 8601 datetime at midnight UTC)

invoice_idstring
referencestring
notestring
metadataobject

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_idstring
advance_invoice_idstring
incoming_purchase_document_idstring
applied_to_incoming_purchase_document_idstring
currency_codestring
amount_convertednumber
tagstring
entity_idstring
deleted_atstring<date-time>
created_atstring<date-time>
updated_atstring<date-time>
Invoiceobject
CreditNoteobject
AdvanceInvoiceobject
IncomingPurchaseDocumentobject
AppliedToIncomingPurchaseDocumentobject
json
{
  "id": "pmt_def789ghi012",
  "invoice_id": "inv_abc123def456",
  "credit_note_id": null,
  "advance_invoice_id": null,
  "incoming_purchase_document_id": null,
  "applied_to_incoming_purchase_document_id": null,
  "amount": 12500,
  "type": "bank_transfer",
  "date": "2024-01-10T00:00:00.000Z",
  "reference": "ORB-2025-042",
  "tag": null,
  "note": "First installment for antenna array",
  "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",
  "deleted_at": null
}