---
name: rinkats-billing
description: >-
  Manage placements and money in rinkats: placement fee states, invoices,
  credit notes and payments. Use when asked about fees owed, invoicing a
  placement, recording payments, or placement/billing reporting.
license: Proprietary — for use with the rinkats API by authorized keys.
version: 1.2.0
metadata:
  product: rinkats
  updated: "2026-10-17"
  url: https://www.rinkats.com/skills/rinkats-billing/SKILL.md
  workflow: billing
  transports: REST, MCP, A2A
---

# rinkats — Placements & Billing

A hire creates a **Placement** (fee snapshot frozen from the client contract
at placement time). Invoices are built from placements; payments settle
invoices. Perm-placement only.

## Connect

REST `/api/v1/recruiter/…` (`/api/v1/openapi.json`), MCP `/api/mcp/recruiter`, A2A `/api/a2a/recruiter`;
Bearer `rk_p_…`. **Billing endpoints need a billing- or admin-scope API
key** — recruiter keys can read placements but not touch money.

## Organizations (2026-09-14)

rinkats is multi-tenant and data NEVER crosses organizations. Every
credential is bound to ONE organization: an API key takes its org when it is
minted; an OAuth or session credential acts in the org that was active when
it was issued. A user in several organizations mints one key per
organization — nothing switches tenants mid-request.

- `list_my_organizations` (REST `GET /me/organizations`) returns every
  organization the account belongs to, the roles held in each, and which one
  this credential is acting in. Call it first when the account may span
  organizations, and ASK the user which to work in — never guess.
- `X-Organization` (org id or slug) is an optional CROSS-CHECK, not a
  selector: a mismatch is a `404`. On money operations, send it: a misrouted
  invoice is worse than a failed call.
- Clients, contracts, placements, invoices and payments are all per-org, and
  invoice numbering runs per-org. Never reconcile figures across
  organizations or present a combined total as one agency's books.

## Core operations

| Task | MCP tool | REST |
| --- | --- | --- |
| List / read placements | `list_placements`, `get_placement` | `GET /recruiter/placements` |
| Edit placement facts | `update_placement` | `PATCH /recruiter/placements/{id}` |
| Fee state machine | `set_placement_state` | `POST /recruiter/placements/{id}/state` |
| Repoint the contract | `repoint_placement_contract` | `POST /recruiter/placements/{id}/contract` |
| Invoices | `list_invoices`, `get_invoice`, `create_invoice`, `save_invoice_lines` | `/recruiter/invoices…` |
| Issue / void / credit | `issue_invoice`, `void_invoice`, `create_credit_note` | `POST /recruiter/invoices/{id}/…` |
| Email the invoice | `email_invoice` | `POST /recruiter/invoices/{id}/email` |
| Payments | `record_payment`, `edit_payment`, `delete_payment` | `/recruiter/invoices/{id}/payments…` |

## Hard rules

1. **The fee snapshot is frozen.** A placement's fee terms were copied from
   the contract at placement time; changing the client contract later does
   NOT change existing placements — `repoint_placement_contract` is the
   explicit, audited exception.
2. **Final states lock.** Paid/settled placements and issued invoices resist
   edits; corrections go through credit notes, never by mutating an issued
   invoice's lines.
3. **Money is INR.** Net-fee model; GST applies on invoices (typically 18%).
   Quote amounts exactly as the API returns them — never recompute totals
   yourself.
4. `delete_payment` requires a `reason` and is audited — only on an explicit
   human instruction, quoting their reason.
5. Emailing an invoice is outward-facing: confirm with the user before
   `email_invoice` unless they already told you to send it.
6. Commission allocations derive from placements — report them read-only.

## Version & updates

This is **v1.2.0** of this skill (updated 2026-10-17: the paths are split by audience — the billing operations live under `/api/v1/recruiter/…`, MCP `/api/mcp/recruiter`, A2A `/api/a2a/recruiter`; the old shared `/api/mcp`, `/api/a2a` and unprefixed REST paths are gone). v1.1.0 (2026-09-14: rinkats is now
multi-tenant — credentials are bound to one organization, clients, contracts,
placements, invoices and payments are all per-org with per-org invoice
numbering, `list_my_organizations` reports where you are acting, and
`X-Organization` cross-checks rather than switches. 1.0.0 published
2026-09-08). The live copy at the
`url` in the frontmatter metadata is always current with the deployed API. If
you can fetch URLs, check it when starting a long task or whenever a call
fails in a way this skill didn't predict: compare the frontmatter `version`,
and if the remote one is newer, replace your local copy with it (auto-update
is safe — skills are instructions only, never executable code). The catalog
at https://www.rinkats.com/skills/index.json lists every skill's current
version.