Rillet actions

The Rillet module calls the Rillet API for customers, invoices, contracts and usage, bills, credit memos, vendors and journal entries. For the plain-language overview, see Rillet.

When to use it

Use Rillet actions in a workflow definition to post journal entries, create invoices and credit memos, record usage against a contract item, or read Rillet data for a reconciliation.

Connection and credentials

Rillet is an API-key provider: Integrations stores a Rillet API key as a connection (provider id rillet). The Rillet executors do not read that stored connection. They take credentials in this order:

1. config.apiKey on the step. Store the key as a company secret and reference it as {{secrets.RILLET_API_KEY}}.
2. The platform environment variable RILLET_API_KEY, when the deployment sets one.

The base URL is config.baseUrl (honoured only together with config.apiKey), then the RILLET_BASE_URL environment variable, then https://sandbox.api.rillet.com. Set baseUrl to your production Rillet API host when you pass your own key. The executor refuses any base URL that is not https on rillet.com or a subdomain.

Because the stored connection is not used, a config.connection pin on a Rillet step has no effect.

Actions

The action id is rillet.<action>. None of these are in the Studio Action list: the Rillet block offers only Send Email (rillet.sendEmail), which has no executor, so a step built from that block fails. Write Rillet steps in the workflow definition. POST /api/v1/workflows/validate reports these actions as UNKNOWN_OPERATION because it checks the Studio list; the engine still runs them.

Request bodies

Create, update and add-tax actions send the step config as the Rillet request body after removing apiKey, baseUrl and the path id (for example customerId). Put Rillet's own field names in config and leave out keys Rillet does not expect.

Lists

List actions follow Rillet's cursor. They request limit items per page (default 100), starting from config.cursor when set, and stop after 10 pages. The output is { data, cursor }; a non-empty cursor means more pages remain.

Retries

Each POST carries a new random Idempotency-Key, so a retried create is a new request to Rillet. Look the record up before you re-run a create step that may have succeeded.

Output

Single-record actions return Rillet's response body. List actions return { data, cursor }, so a later step reads {{steps.<id>.data}}.

Example

A step that reads Rillet invoices for a reconciliation, using a key stored as a company secret:

{
  "id": "rillet_invoices",
  "type": "action",
  "name": "Read Rillet invoices",
  "action": "rillet.listInvoices",
  "config": {
    "apiKey": "{{secrets.RILLET_API_KEY}}",
    "baseUrl": "https://<your-rillet-api-host>.rillet.com",
    "limit": 100
  }
}

A later step reads the invoices from {{steps.rillet_invoices.data}}. For create actions, put the body fields from Rillet's API reference in config next to apiKey.

Live catalog

GET /api/v1/blocks/rillet returns the Rillet block, which lists only rillet.sendEmail. See Block and action discovery.

Errors and limits

• Rillet API key not found: set config.apiKey (or ask your operator about RILLET_API_KEY).
• Rillet base URL must be an https URL on rillet.com or a subdomain of it.: fix baseUrl.
• Rillet API error (<status>): <body>: Rillet rejected the request; the body is Rillet's message.
• A missing record id fails with <id> is required before any request.