Payments
Payments in the BlueSuite REST API
Record and maintain payments against invoices or quotes. These endpoints use invoices:read and invoices:write scopes. Recording a manual payment does not charge a card. Payment changes recalculate the parent balance/status.
Settle an invoice
Send object_type: "invoice", its object_id, category: "payment", and settle_remaining: true, omitting amount. The server calculates the remaining balance and records a completed manual payment. The default method is Other; a supplied method and created_at are preserved. Pending payments block settlement.
For an explicit amount, omit settle_remaining and provide amount. Tips must be nonnegative. A timestamp, when supplied, must include a timezone. Settlement is for recording funds already received, not collecting them or sending a receipt.
Deleting or editing a payment changes the accounting record; it is not a Stripe refund operation. Inspect the returned record and parent invoice after a change.
GET /api/v1/payments
GET /api/v1/paymentsRequired scopes: invoices:read.
Query parameters
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
page | integer | No | Page number, starting at 1. Default: 1. |
per_page | integer | No | Records per page, from 1 to 100. Default: 25. minimum: 1. maximum: 100. |
search | string | No | Search text. maxLength: 100. |
sort_by | string | No | Sort column. See the supported columns below when listed. |
sort_direction | "asc", "desc" | No | Sort direction. Default: "desc". |
object_id | string | No | ID of the invoice or quote. |
object_type | string | No | invoice or quote. |
status | string | No | Filter by status. |
Response
200 with { "success": true, "data": [...], "pagination": { "page": 1, "per_page": 25, "total_pages": 1 } }.
See response conventions and errors.
POST /api/v1/payments
POST /api/v1/paymentsRequired scopes: invoices:write.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
object_id | integer | Yes | |
object_type | "invoice", "quote" | Yes | |
category | "deposit", "payment" | Yes | |
amount | number | No | |
tip_amount | number | No | Default: 0. minimum: 0. |
status | "pending", "completed", "failed", "refunded" | No | Default: "completed". |
gateway | "manual", "stripe:connect" | No | Default: "manual". |
method | "other", "credit_card", "cash", "check", "bank_transfer", "ach", "financing" | No | Default: "other". |
notes | string or null | No | |
created_at | string | No | Format: date-time. |
settle_remaining | boolean | No |
Unknown body fields are rejected. Conditional requirements are explained above.
Response
201 with { "success": true, "data": ... }. The data contains the result of the operation.
See response conventions and errors.
GET /api/v1/payments/:id
GET /api/v1/payments/:idRequired scopes: invoices:read.
Path parameters: id. Use positive integer record IDs from this workspace.
Response
200 with { "success": true, "data": ... }. The data contains the result of the operation.
See response conventions and errors.
PUT /api/v1/payments/:id
PUT /api/v1/payments/:idRequired scopes: invoices:write.
Path parameters: id. Use positive integer record IDs from this workspace.
JSON body
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
object_id | integer | No | |
object_type | "invoice", "quote" | No | |
category | "deposit", "payment" | No | |
amount | number | No | |
tip_amount | number | No | Default: 0. minimum: 0. |
status | "pending", "completed", "failed", "refunded" | No | Default: "completed". |
gateway | "manual", "stripe:connect" | No | Default: "manual". |
method | "other", "credit_card", "cash", "check", "bank_transfer", "ach", "financing" | No | Default: "other". |
notes | string or null | No | |
created_at | string | No | Format: date-time. |
Unknown body fields are rejected. Conditional requirements are explained above.
Response
200 with { "success": true, "data": ... }. The data contains the result of the operation.
See response conventions and errors.
DELETE /api/v1/payments/:id
DELETE /api/v1/payments/:idRequired scopes: invoices:write.
Path parameters: id. Use positive integer record IDs from this workspace.
No request body.
Response
200 with { "success": true, "data": ... }. The data contains the result of the operation.