Retainers

Retainer invoices are upfront payments that secure services for a period of time, guaranteeing payment and priority treatment.

Create Retainer

POST https://api.invoiless.com/v1/invoices

Create a new retainer by including isRetainer: true in the request body.

Example:

{
  "isRetainer": true,
  "customer": {
    "internalId": "INTERNAL_USER_ID",
    "billTo": {
      "company": "Invoiless"
    }
  },
  "items": [
    {
      "name": "Monthly Retainer",
      "quantity": 1,
      "price": 5000
    }
  ],
  "status": "Draft"
}

Body Parameters

Accepts the same parameters as Create Invoice, plus:

Name	Type	Description	Required
isRetainer	bool	Set to true for retainer invoices	Yes

Response HTTP/1.1 201 Created

Returns the created retainer object.

Update Retainer

PUT https://api.invoiless.com/v1/invoices/:id

PATCH https://api.invoiless.com/v1/invoices/:id

Update an existing retainer. See PUT vs PATCH for details on the differences.

Path Parameters

Name	Type	Description	Required
id	string	Retainer id	Yes

Body Parameters

Accepts the same parameters as Create Invoice.

Get Retainer

GET https://api.invoiless.com/v1/invoices/:id

Retrieve a specific retainer by ID.

Path Parameters

Name	Type	Description	Required
id	string	Retainer id	Yes

Get Retainers

GET https://api.invoiless.com/v1/invoices

Retrieve a paginated list of all retainers by filtering for isRetainer: true.

Query Parameters

Name	Type	Description	Required
page	number	Page number	No, default is 1
limit	number	Page limit	No , default is 50
search	number	Search by retainer number, customer name, or tags	No

Send Retainer

POST https://api.invoiless.com/v1/invoices/:id/send

Send a retainer via email to the customer.

Path Parameters

Name	Type	Description	Required
id	string	Retainer id	Yes

Body Parameters

Name	Type	Description	Required
email	string	Email address	No
subject	string	Email subject	No
body	string	Email body	No
date	date	Schedule send	No

Delete Retainer

DELETE https://api.invoiless.com/v1/invoices/:id

Permanently delete a retainer.

Path Parameters

Name	Type	Description	Required
id	string	Retainer id	Yes