key option or store it on the account; the plugin sends it as the X-API-Key header.
Simplero documents 1134 routes across every part of the platform. This plugin wraps a working set around contacts and what they buy: contacts, email lists, tags, products, purchases and subscriptions. Pages, courses, funnels, automations and the rest are not wrapped.
Things to know before you write:
- Contact creates need both required fields. Simplero requires
emailandlead_scoreon a contact, so a create must send a score. Sending a score replaces it. adjustLeadScoreis notupdate. The action addsamount(negative to subtract) to the stored score and records it, with an optionalexplanation, in the contact’s history;customers.updatereplaces the score outright.- Tag actions take one or many.
customers.addTagandcustomers.removeTagaccepttag_idortag_ids, never both and never neither; the schema rejects either mistake. Tag changes can start or stop the automations attached to that tag. - PATCH changes only what it sends. An omitted field keeps its stored value, unlike a PUT.
purchases.updateandsubscriptions.updateare limited to buyer details and tracking data. - Subscription state is an action, not a field.
subscriptions.updatecannot subscribe or unsubscribe anyone; that issubscriptions.unsubscribeandsubscriptions.resubscribe, and unsubscribing is reversible. - Money movements are not wrapped. Refunding, cancelling, capturing and changing a purchase price are separate Simplero actions that move funds, so they are deliberately left out.
- Paging.
pagecounts from 1 andper_pageis 1 to 100, defaulting to 20.afteris the cursor form: passpagination.next_afterandtotalandtotal_pagescome back null, because counting is skipped. - Errors. A 401 is
{ "error": "Bad API key" }; a 422 is{ "errors": ["…"] }, which the plugin joins into one message. A 503 can mean the idempotency store could not be checked, in which case nothing ran.
- 27 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the Simplero API key before the first call: More: API Key
pnpm corsair setup --plugin=simplero --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
List contacts on a listWhat’s next
API reference
Every
simplero.api.* operation with input and output types.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.