> ## Documentation Index
> Fetch the complete documentation index at: https://help.gorelo.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Records a payment received outside Gorelo against an approved invoice.
> Required:
`InvoiceId`, `PaymentDate` and `Reference`.
Optional:`Amount` - defaults to the invoice's whole amount due. It must be
greater than 0 and no more than what the invoice still owes, so an invoice cannot be
overpaid. `PaymentDate` is a calendar date and cannot be later than today in the
service provider's time zone.
The invoice must be Approved. A payment that leaves nothing owing marks the invoice Paid;
otherwise its status is unchanged. The payment is added to the invoice's timeline and
appears in `Payments` on `GET /v1/invoices/{invoiceId}`.
Refused with 409 while the service provider has Xero or QuickBooks Online connected - record
the payment there instead and it syncs to Gorelo. An invoice that doesn't exist, or belongs
to another service provider, is a 404.
The response is just the recorded payment's `Id`.
## OpenAPI
````yaml /api-reference/openapi.json post /v1/payments
openapi: 3.0.4
info:
title: Public API
description: Gorelo Public API documentation.
version: 1.0.0
servers:
- url: https://api.usw.gorelo.io
description: US
- url: https://api.aue.gorelo.io
description: Australia
security:
- ApiKeyAuth: []
tags:
- name: Attachments
description: "Uploading a file, for anything that can carry one. One endpoint rather than one per record\r\ntype, because the upload itself is identical - only the record it is checked against differs."
- name: Alerts
description: Alerts management operations
- name: Assets
description: Assets management operations
- name: Billing
description: Billing management operations
- name: Tickets
description: Tickets management operations
- name: Clients
description: Clients management operations
- name: Contacts
description: Contacts management operations
- name: Deletions
description: Deletions management operations
- name: Documents
description: Documents management operations
- name: Forms
description: Forms management operations
- name: Organization
description: Organization management operations
- name: Projects
description: Projects management operations
paths:
/v1/payments:
post:
tags:
- Billing
summary: Records a payment received outside Gorelo against an approved invoice.
description: "Required:\r\n`InvoiceId`, `PaymentDate` and `Reference`.\r\n \nOptional:`Amount` - defaults to the invoice's whole amount due. It must be\r\n greater than 0 and no more than what the invoice still owes, so an invoice cannot be\r\n overpaid. `PaymentDate` is a calendar date and cannot be later than today in the\r\n service provider's time zone.\r\n \n\r\n The invoice must be Approved. A payment that leaves nothing owing marks the invoice Paid;\r\n otherwise its status is unchanged. The payment is added to the invoice's timeline and\r\n appears in `Payments` on `GET /v1/invoices/{invoiceId}`.\r\n \n\r\n Refused with 409 while the service provider has Xero or QuickBooks Online connected - record\r\n the payment there instead and it syncs to Gorelo. An invoice that doesn't exist, or belongs\r\n to another service provider, is a 404.\r\n \nThe response is just the recorded payment's `Id`."
operationId: post_v1_payments
requestBody:
description: The payment to record.
content:
application/json-patch+json:
schema:
$ref: '#/components/schemas/CreatePaymentCommand'
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentCommand'
text/json:
schema:
$ref: '#/components/schemas/CreatePaymentCommand'
application/*+json:
schema:
$ref: '#/components/schemas/CreatePaymentCommand'
responses:
'200':
description: OK
content:
text/plain:
schema:
$ref: '#/components/schemas/CreatePaymentResultBaseResponse'
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentResultBaseResponse'
text/json:
schema:
$ref: '#/components/schemas/CreatePaymentResultBaseResponse'
'400':
description: Bad Request
content:
text/plain:
schema:
$ref: '#/components/schemas/ObjectBaseResponse'
application/json:
schema:
$ref: '#/components/schemas/ObjectBaseResponse'
text/json:
schema:
$ref: '#/components/schemas/ObjectBaseResponse'
'401':
description: Unauthorized
content:
text/plain:
schema:
$ref: '#/components/schemas/ObjectBaseResponse'
application/json:
schema:
$ref: '#/components/schemas/ObjectBaseResponse'
text/json:
schema:
$ref: '#/components/schemas/ObjectBaseResponse'
'404':
description: Not Found
content:
text/plain:
schema:
$ref: '#/components/schemas/ObjectBaseResponse'
application/json:
schema:
$ref: '#/components/schemas/ObjectBaseResponse'
text/json:
schema:
$ref: '#/components/schemas/ObjectBaseResponse'
'409':
description: Conflict
content:
text/plain:
schema:
$ref: '#/components/schemas/ObjectBaseResponse'
application/json:
schema:
$ref: '#/components/schemas/ObjectBaseResponse'
text/json:
schema:
$ref: '#/components/schemas/ObjectBaseResponse'
'500':
description: Internal Server Error
content:
text/plain:
schema:
$ref: '#/components/schemas/ObjectBaseResponse'
application/json:
schema:
$ref: '#/components/schemas/ObjectBaseResponse'
text/json:
schema:
$ref: '#/components/schemas/ObjectBaseResponse'
components:
schemas:
CreatePaymentCommand:
type: object
properties:
InvoiceId:
type: string
description: "Invoice the payment is recorded against. Required. The invoice must be Approved; an invoice\r\nthat does not exist, or belongs to another service provider, is a 404."
format: uuid
example: 3f1a9e2b-6c4d-4e2a-8b1a-0e2f7c9d1a44
Amount:
type: number
description: "Amount received. Optional - defaults to the invoice's whole amount due when omitted. Must be\r\ngreater than 0 and no more than the invoice's amount due."
format: double
nullable: true
example: 250
PaymentDate:
type: string
description: "Date the payment was received, a calendar date. Required. Cannot be later than today in the\r\nservice provider's time zone."
format: date
nullable: true
example: '2026-10-01'
Reference:
type: string
description: "Your reference for the payment, such as a bank transaction or remittance number. Required,\r\nmax 50 characters."
example: BANK-20261001-118
additionalProperties: false
description: Records a payment received outside Gorelo against an invoice.
CreatePaymentResultBaseResponse:
type: object
properties:
StatusCode:
$ref: '#/components/schemas/HttpStatusCode'
IsSuccess:
type: boolean
Data:
$ref: '#/components/schemas/CreatePaymentResult'
DataContext:
type: object
additionalProperties: false
nullable: true
example: null
Notifications:
type: array
items:
$ref: '#/components/schemas/Error'
additionalProperties: false
ObjectBaseResponse:
type: object
properties:
StatusCode:
$ref: '#/components/schemas/HttpStatusCode'
IsSuccess:
type: boolean
Data:
nullable: true
DataContext:
$ref: '#/components/schemas/ErrorDataContext'
Notifications:
type: array
items:
$ref: '#/components/schemas/Error'
additionalProperties: false
HttpStatusCode:
enum:
- 100
- 101
- 102
- 103
- 200
- 201
- 202
- 203
- 204
- 205
- 206
- 207
- 208
- 226
- 300
- 301
- 302
- 303
- 304
- 305
- 306
- 307
- 308
- 400
- 401
- 402
- 403
- 404
- 405
- 406
- 407
- 408
- 409
- 410
- 411
- 412
- 413
- 414
- 415
- 416
- 417
- 421
- 422
- 423
- 424
- 426
- 428
- 429
- 431
- 451
- 500
- 501
- 502
- 503
- 504
- 505
- 506
- 507
- 508
- 510
- 511
type: integer
format: int32
CreatePaymentResult:
type: object
properties:
Id:
type: string
description: Identifier of the newly recorded payment.
format: uuid
additionalProperties: false
description: "Result of recording a payment: just the new payment's `Id`, the same minimal shape Create\r\nInvoice returns. The payment appears in `Payments` on `GET /v1/invoices/{invoiceId}`."
Error:
type: object
properties:
Code:
pattern: ^[0-9]{6}$
type: string
description: 6-digit MMTTNN error code. See the Public API error-code registry.
example: '070101'
Message:
type: string
PropertyName:
type: string
nullable: true
ActionHint:
type: string
nullable: true
DocUrl:
type: string
nullable: true
additionalProperties: false
ErrorDataContext:
type: object
properties:
TraceId:
type: string
description: Request correlation id. Quote this when reporting a problem.
nullable: true
additionalProperties: false
description: "The `DataContext` of an error response: carries the correlation id for the failed\r\nrequest."
securitySchemes:
ApiKeyAuth:
type: apiKey
description: >-
Your Gorelo API key. See [Generate API key](/generate-api-key). If your
data is hosted in Australia, click the base URL at the top of this page
and select `https://api.aue.gorelo.io`.
name: X-API-Key
in: header
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.