Invoices

Document creation, sending, and payment tracking. Covers invoices, receipts, payment requests, credit/debit memos, and clearance flows for jurisdictions that require it.

15 endpoints·Scopes: invoices:read, invoices:write

GET/api/dashboard#

List dashboard summaries

scope · invoices:read

Lists dashboard summaries the caller can see. Results are filtered by the caller's accessible organizations; many routes paginate via page and limit.

Scope: invoices:read
Endpoint: GET /api/dashboard

Example request

curl "https://guliel.com/api/dashboard?organizationId=value" \
  -H "Authorization: Bearer $GULIEL_API_KEY"

Query parameters

organizationIdreq
string
yearreq
integer

Response (200/201)

totalInvoicesreq
integer
totalRevenuereq
number
outstandingAmountreq
number
pendingAmountreq
number
invoicesByStatusreq
objectPer-status counts of the org's invoices for the requested year.
- draftreq
  integer
- unsentreq
  integer
- sentreq
  integer
- paidreq
  integer
revenueByMonthreq
array<object>
- monthreq
  string
- revenuereq
  number
- sentreq
  number
- unsentreq
  number
- draftreq
  number
revenueByCustomerreq
array<object>Top customers by revenue, sorted descending. Currency-converted to `displayCurrency`. `count` is that client's own number of PAID invoices.
- namereq
  string
- revenuereq
  number
- countreq
  integer
growthreq
numberYoY revenue growth percentage.
displayCurrencyreq
stringCurrency that all monetary fields are converted to (the organization's primary currency).
exchangeRateDatereq
stringDate of the FX-rate snapshot used for conversions.
pendingPaymentsListreq
array<object>Open invoices awaiting payment, sorted by due date.
expenseTotalreq
number
expensesByMonthreq
array<object>
expensesByVendorreq
array<object>
paidInvoicesCountreq
integer
approvedExpensesCountreq
integer
expenseGrowthreq
number
netTotalreq
numberRevenue minus expenses, in displayCurrency.
netGrowthreq
number
marginPercentreq
number
pendingExpensesTotalreq
number
pendingExpensesCountreq
integer
pendingExpensesGrowthreq
number
cashFlowByMonthreq
array<object>
lowStockItemsCountreq
integer
activeItemsCountreq
integer
fxIncomplete
booleanTrue when one or more source currencies could not be converted to `displayCurrency` (missing FX rate). Those amounts were summed at face value — totals are approximate. Surfaced in ALL environments (data quality, not a diagnostic).
fxMissingCurrencies
array<string>Source currencies that lacked a usable rate to `displayCurrency`. Present (and non-empty) iff `fxIncomplete` is true.
_diagnostics
array<string>Only present in non-production environments — surfaces errors that were caught and logged but didn't abort the response.

Error responses

`400`	Validation
`401`	Unauthenticated
`403`	Forbidden
`500`	Internal

GET/api/documents#

List documents

scope · invoices:read

Lists documents the caller can see. Results are filtered by the caller's accessible organizations; many routes paginate via page and limit.

Scope: invoices:read
Endpoint: GET /api/documents

Example request

curl "https://guliel.com/api/documents?organizationId=value" \
  -H "Authorization: Bearer $GULIEL_API_KEY"

Query parameters

organizationIdreq
string
pagereq
integer
limitreq
integer
status
enum<4>
DRAFT · UNSENT · SENT · PAID
documentType
string
searchreq
string
customerId
string
disputed
enum<2>
true · false
sortByreq
enum<6>
issueDate · dueDate · total · status · documentNumber · customerName
sortOrderreq
enum<2>
asc · desc

Response (200/201)

invoicesreq
array<object>
- idreq
  string
- organizationIdreq
  string
- customerIdreq
  string
- documentTypereq
  string
- invoiceNumberreq
  string | null
- statusreq
  string
- inDisputereq
  boolean
- invoiceDatereq
  string
- dueDatereq
  string | null
- currencyreq
  string
- exchangeRatereq
  number | null
- subtotalreq
  number
- taxAmountreq
  number
- totalAmountreq
  number
- paidAmountreq
  number
- notesreq
  string | null
- vatAllocationNumberreq
  string | null
- generatorVersionreq
  string
- createdAtreq
  string
- updatedAtreq
  string
- customerreq
  object | null
- itemsreq
  array<object>
  - idreq
    string
  - descriptionreq
    string
  - quantityreq
    number
  - unitPricereq
    number
  - amountreq
    number
- payments
  array<object>
- attachments
  array<object>
- createdByreq
  object | null
paginationreq
object
- pagereq
  integer
- limitreq
  integer
- totalreq
  integer
- totalPagesreq
  integer

Error responses

`400`	Validation
`401`	Unauthenticated
`403`	Forbidden
`500`	Internal

POST/api/documents#

Create a document

scope · invoices:writerole · CONTRIBUTOR+

Creates a new document in the target organization. Returns the created record on success.

Scope: invoices:write
Min role: CONTRIBUTOR or higher
Endpoint: POST /api/documents

Example request

curl -X POST "https://guliel.com/api/documents" \
  -H "Authorization: Bearer $GULIEL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "organizationId": "abc123",
  "customerId": "abc123",
  "currency": "USD",
  "status": "DRAFT",
  "documentType": "INVOICE",
  "items": [
    {
      "id": "abc123",
      "description": "string",
      "quantity": 0,
      "unitPrice": 0,
      "amount": 100
    }
  ],
  "subtotal": 0,
  "taxRate": 0,
  "taxAmount": 100,
  "total": 0
}'

Request body

organizationIdreq
string
customerIdreq
string
bankAccountId
string | null
currencyreq
string
statusreq
enum<4>
DRAFT · UNSENT · SENT · PAID
documentTypereq
enum<4>
INVOICE · RECEIPT · INVOICE_RECEIPT · PAYMENT_REQUEST
dueDate
string | null
payUntil
string | null
itemsreq
array<object>
- idreq
  string
- itemId
  string | null
- descriptionreq
  string
- quantityreq
  number
- unitPricereq
  number
- amountreq
  number
subtotalreq
number
taxRatereq
number
taxAmountreq
number
totalreq
number
countrySpecificData
object
notes
string | null
paymentMethod
string | null
paymentDate
string | null

Response (200/201)

idreq
string
organizationIdreq
string
customerIdreq
string
documentTypereq
string
invoiceNumberreq
string | null
statusreq
string
inDisputereq
boolean
invoiceDatereq
string
dueDatereq
string | null
currencyreq
string
exchangeRatereq
number | null
subtotalreq
number
taxAmountreq
number
totalAmountreq
number
paidAmountreq
number
notesreq
string | null
vatAllocationNumberreq
string | null
generatorVersionreq
string
createdAtreq
string
updatedAtreq
string
customerreq
object | null
itemsreq
array<object>
- idreq
  string
- descriptionreq
  string
- quantityreq
  number
- unitPricereq
  number
- amountreq
  number
payments
array<object>
attachments
array<object>
createdByreq
object | null

Error responses

`400`	Validation
`401`	Unauthenticated
`403`	Forbidden
`429`	RateLimit
`500`	Internal

DELETE/api/documents/{id}#

Delete a document

scope · invoices:write

Deletes the document. Some endpoints hard-delete the row, others soft-revoke (set revokedAt). Check the response shape.

Scope: invoices:write
Endpoint: DELETE /api/documents/{id}

Example request

curl -X DELETE "https://guliel.com/api/documents/abc123?id=value" \
  -H "Authorization: Bearer $GULIEL_API_KEY"

Query parameters

idreq
string

Response (200/201)

successreq
boolean

Error responses

`400`	Validation
`401`	Unauthenticated
`403`	Forbidden
`429`	RateLimit
`500`	Internal

GET/api/documents/{id}#

Get a document

scope · invoices:read

Fetches a single document by id. Returns 404 if the document isn't in the caller's accessible organizations.

Scope: invoices:read
Endpoint: GET /api/documents/{id}

Example request

curl "https://guliel.com/api/documents/abc123?id=value" \
  -H "Authorization: Bearer $GULIEL_API_KEY"

Query parameters

idreq
string

Response (200/201)

idreq
string
organizationIdreq
string
customerIdreq
string
bankAccountIdreq
string | null
invoiceNumberreq
string | null
documentTypereq
string
statusreq
string
directionreq
string
inDisputereq
boolean
currencyreq
string
exchangeRatereq
number | null
issueDatereq
string
dueDatereq
string | null
payUntilreq
string | null
paymentMethodreq
string | null
paymentDatereq
string | null
receiptNumberreq
string | null
subtotalreq
number
taxRatereq
number | null
taxAmountreq
number
totalreq
number
paidAmountreq
number
notesreq
string | null
generatorVersionreq
string
vatAllocationNumberreq
string | null
countrySpecificDatareq
object | null
itemsreq
array<object>
organizationreq
object | null
customerreq
object | null
bankAccountreq
object | null
createdByreq
object | null
createdAtreq
string
updatedAtreq
string

Error responses

`400`	Validation
`401`	Unauthenticated
`403`	Forbidden
`500`	Internal

PATCH/api/documents/{id}#

Update a document

scope · invoices:write

Updates an existing document. Only the fields present in the request body are changed; omitted fields stay as-is.

Scope: invoices:write
Endpoint: PATCH /api/documents/{id}

Example request

curl -X PATCH "https://guliel.com/api/documents/abc123" \
  -H "Authorization: Bearer $GULIEL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "id": "abc123"
}'

Request body

idreq
string
customerId
string
bankAccountId
string | null
currency
string
status
enum<4>
DRAFT · UNSENT · SENT · PAID
documentType
enum<4>
INVOICE · RECEIPT · INVOICE_RECEIPT · PAYMENT_REQUEST
dueDate
string | null
payUntil
string | null
items
array<object>
- idreq
  string
- itemId
  string | null
- descriptionreq
  string
- quantityreq
  number
- unitPricereq
  number
- amountreq
  number
subtotal
number
taxRate
number
taxAmount
number
total
number
countrySpecificData
object
notes
string | null
clearReceiptInfo
boolean
paymentMethod
string | null
paymentDate
string | null

Response (200/201)

idreq
string
organizationIdreq
string
customerIdreq
string
bankAccountIdreq
string | null
invoiceNumberreq
string | null
documentTypereq
string
statusreq
string
directionreq
string
inDisputereq
boolean
currencyreq
string
exchangeRatereq
number | null
issueDatereq
string
dueDatereq
string | null
payUntilreq
string | null
paymentMethodreq
string | null
paymentDatereq
string | null
receiptNumberreq
string | null
subtotalreq
number
taxRatereq
number | null
taxAmountreq
number
totalreq
number
paidAmountreq
number
notesreq
string | null
generatorVersionreq
string
vatAllocationNumberreq
string | null
countrySpecificDatareq
object | null
itemsreq
array<object>
organization
object | null
customer
object | null
bankAccount
object | null
createdBy
object | null
createdAtreq
string
updatedAtreq
string

Error responses

`400`	Validation
`401`	Unauthenticated
`403`	Forbidden
`429`	RateLimit
`500`	Internal

PUT/api/documents/{id}#

Update a document

scope · invoices:write

Replaces an existing document. All required fields must be supplied — omitted fields revert to their schema defaults.

Scope: invoices:write
Endpoint: PUT /api/documents/{id}

Example request

curl -X PUT "https://guliel.com/api/documents/abc123" \
  -H "Authorization: Bearer $GULIEL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "id": "abc123"
}'

Request body

idreq
string
customerId
string
bankAccountId
string | null
currency
string
status
enum<4>
DRAFT · UNSENT · SENT · PAID
documentType
enum<4>
INVOICE · RECEIPT · INVOICE_RECEIPT · PAYMENT_REQUEST
dueDate
string | null
payUntil
string | null
items
array<object>
- idreq
  string
- itemId
  string | null
- descriptionreq
  string
- quantityreq
  number
- unitPricereq
  number
- amountreq
  number
subtotal
number
taxRate
number
taxAmount
number
total
number
countrySpecificData
object
notes
string | null
clearReceiptInfo
boolean
paymentMethod
string | null
paymentDate
string | null

Response (200/201)

idreq
string
organizationIdreq
string
customerIdreq
string
bankAccountIdreq
string | null
invoiceNumberreq
string | null
documentTypereq
string
statusreq
string
directionreq
string
inDisputereq
boolean
currencyreq
string
exchangeRatereq
number | null
issueDatereq
string
dueDatereq
string | null
payUntilreq
string | null
paymentMethodreq
string | null
paymentDatereq
string | null
receiptNumberreq
string | null
subtotalreq
number
taxRatereq
number | null
taxAmountreq
number
totalreq
number
paidAmountreq
number
notesreq
string | null
generatorVersionreq
string
vatAllocationNumberreq
string | null
countrySpecificDatareq
object | null
itemsreq
array<object>
organization
object | null
customer
object | null
bankAccount
object | null
createdBy
object | null
createdAtreq
string
updatedAtreq
string

Error responses

`400`	Validation
`401`	Unauthenticated
`403`	Forbidden
`429`	RateLimit
`500`	Internal

GET/api/documents/{id}/clearance#

List clearance for a document

scope · invoices:read

Returns every clearance row associated with the given document.

Scope: invoices:read
Endpoint: GET /api/documents/{id}/clearance

Example request

curl "https://guliel.com/api/documents/abc123/clearance?id=value" \
  -H "Authorization: Bearer $GULIEL_API_KEY"

Query parameters

idreq
string

Response (200/201)

JSON object. The exact response shape is being progressively documented — call the endpoint with a real access token to see the live structure, or check the type definitions exposed by the official client libraries.

Error responses

`400`	Validation
`401`	Unauthenticated
`403`	Forbidden
`500`	Internal

POST/api/documents/{id}/clearance#

Attach clearance to a document

scope · invoices:write

Creates a new clearance attached to the given document.

Scope: invoices:write
Endpoint: POST /api/documents/{id}/clearance

Example request

curl -X POST "https://guliel.com/api/documents/abc123/clearance" \
  -H "Authorization: Bearer $GULIEL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "id": "abc123"
}'

Request body

idreq
string
action
enum<2>
submit · retry

Response (200/201)

successreq
booleanTrue iff the country handler reports APPROVED on this submission.
resultreq
objectFull clearance result from the country handler.

Error responses

`400`	Validation
`401`	Unauthenticated
`403`	Forbidden
`429`	RateLimit
`500`	Internal

GET/api/documents/{id}/events#

List events for a document

scope · invoices:read

Returns every events row associated with the given document.

Scope: invoices:read
Endpoint: GET /api/documents/{id}/events

Example request

curl "https://guliel.com/api/documents/abc123/events?id=value" \
  -H "Authorization: Bearer $GULIEL_API_KEY"

Query parameters

idreq
string
pagereq
integer
limitreq
integer

Response (200/201)

eventsreq
array<object>
- idreq
  string
- documentIdreq
  string
- organizationIdreq
  string
- typereq
  stringDocumentEventType — see DOCUMENT_EVENTS.md §4.
- actorUserIdreq
  string | nullnull = a system event.
- actorreq
  object | null
- payloadreq
  object | nullEvent-specific data — shape depends on `type` (§4).
- createdAtreq
  string
paginationreq
object
- pagereq
  integer
- limitreq
  integer
- totalreq
  integer
- totalPagesreq
  integer

Error responses

`400`	Validation
`401`	Unauthenticated
`403`	Forbidden
`500`	Internal

POST/api/documents/{id}/events#

Attach events to a document

scope · invoices:write

Creates a new events attached to the given document.

Scope: invoices:write
Endpoint: POST /api/documents/{id}/events

Example request

curl -X POST "https://guliel.com/api/documents/abc123/events" \
  -H "Authorization: Bearer $GULIEL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "id": "abc123",
  "type": "DISPUTED"
}'

Request body

idreq
string
typereq
enum<6>
DISPUTED · DISPUTE_COUNTERED · DISPUTE_RESOLVED · COMMENTED · APPROVED · REJECTED
payload
object

Response (200/201)

idreq
string
documentIdreq
string
organizationIdreq
string
typereq
stringDocumentEventType — see DOCUMENT_EVENTS.md §4.
actorUserIdreq
string | nullnull = a system event.
actorreq
object | null
payloadreq
object | nullEvent-specific data — shape depends on `type` (§4).
createdAtreq
string

Error responses

`400`	Validation
`401`	Unauthenticated
`403`	Forbidden
`429`	RateLimit
`500`	Internal

POST/api/documents/{id}/manual-allocation#

Attach manual allocation to a document

scope · invoices:write

Creates a new manual-allocation attached to the given document.

Scope: invoices:write
Endpoint: POST /api/documents/{id}/manual-allocation

Example request

curl -X POST "https://guliel.com/api/documents/abc123/manual-allocation" \
  -H "Authorization: Bearer $GULIEL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "id": "abc123",
  "allocationNumber": "string"
}'

Request body

idreq
string
allocationNumberreq
string

Response (200/201)

successreq
boolean
allocationNumberreq
stringDigits-only allocation number after stripping non-digit characters.

Error responses

`400`	Validation
`401`	Unauthenticated
`403`	Forbidden
`429`	RateLimit
`500`	Internal

POST/api/documents/{id}/mark-paid#

Update the document status

scope · invoices:write

Mutates the state machine of the document. Some transitions are restricted by role.

Scope: invoices:write
Endpoint: POST /api/documents/{id}/mark-paid

Example request

curl -X POST "https://guliel.com/api/documents/abc123/mark-paid" \
  -H "Authorization: Bearer $GULIEL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "id": "abc123",
  "paymentDate": "string",
  "paymentMethod": "string",
  "generateReceipt": true,
  "sendReceiptEmail": false
}'

Request body

idreq
string
paymentDatereq
string
paymentMethodreq
string
generateReceiptreq
boolean
sendReceiptEmailreq
boolean

Response (200/201)

Error responses

`400`	Validation
`401`	Unauthenticated
`403`	Forbidden
`429`	RateLimit
`500`	Internal

POST/api/documents/{id}/send#

Send a document by email

scope · invoices:write

Renders the document as a PDF, attaches it, and emails it to the configured recipients.

Scope: invoices:write
Endpoint: POST /api/documents/{id}/send

Example request

curl -X POST "https://guliel.com/api/documents/abc123/send" \
  -H "Authorization: Bearer $GULIEL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "id": "abc123"
}'

Request body

idreq
string

Response (200/201)

successreq
boolean
sentreq
integer
failedreq
integer
totalRecipientsreq
integer

Error responses

`400`	Validation
`401`	Unauthenticated
`403`	Forbidden
`429`	RateLimit
`500`	Internal

POST/api/orders/{id}/invoice#

Attach invoice to an order

scope · invoices:writerole · CONTRIBUTOR+

Creates a new invoice attached to the given order.

Scope: invoices:write
Min role: CONTRIBUTOR or higher
Endpoint: POST /api/orders/{id}/invoice

Example request

curl -X POST "https://guliel.com/api/orders/abc123/invoice" \
  -H "Authorization: Bearer $GULIEL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "id": "abc123"
}'

Request body

idreq
string

Response (200/201)

invoicereq
objectThe freshly-created invoice. See /api/documents/[id] GET for the canonical shape.
redirectUrlreq
stringPath the UI should navigate to so the user can edit the new invoice.

Error responses

`400`	Validation
`401`	Unauthenticated
`403`	Forbidden
`429`	RateLimit
`500`	Internal