Skip to main content
A custom integration packages your connection to Retainful — its API keys, its event types, its configuration — as a named app inside the dashboard. It’s the right structure when you’re connecting a real system (a booking platform, a subscription service, an internal CRM) rather than making ad-hoc API calls.

​
Why bother with the wrapper?

  • Scoped credentials — each integration has its own API keys, independently rotatable and revocable.
  • Named events — events you register under the integration show up in the automation builder grouped under your integration’s name, with their fields typed and pickable.
  • Status & health — the dashboard shows the integration’s connection state where merchants expect it.

​
Create one

1

Create the app

Go to Integrations → Create app. Name it after the system it represents — “Bookings”, “Subscription billing”.
2

Generate credentials

Create an API key for it — see Authentication.
3

Register your events

Call POST /events/register for each event type your system emits, with a representative payload.
4

Ship the data flow

From your system, create contacts and send events as things happen.

​
Integration patterns

Send trial_started, subscription_activated, subscription_renewed, subscription_cancelled. Build onboarding flows on trial start, renewal thank-yous, and cancellation win-backs — each with the plan and value data in filters.
Send appointment_booked, appointment_completed, appointment_no_show. Automate reminders before, review requests after, and re-booking nudges for lapsed clients.
Your backend forwards checkout and order activity as events, and creates contacts at signup with proper consent flags. Note that the deep cart-recovery integration (recovery URLs, store-generated coupons) is built around the native Shopify and WooCommerce connections.

​
Checklist before production

  • API key stored server-side in a secrets manager — never in client code.
  • Retry-with-backoff on 429/5xx — see Rate limits and Errors.
  • Consent (email_opt_in) set honestly at contact creation — see Contacts API.
  • Event names stable and documented for the marketing team.
  • A staging organization for testing, so test events never trigger production automations.