> ## Documentation Index
> Fetch the complete documentation index at: https://help.retainful.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom integrations

> Connect your own platform or internal tools to Retainful as a first-class integration.

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](/developers/api/events#register-an-event-schema) 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

<Steps>
  <Step title="Create the app">
    Go to **Integrations → Create app**. Name it after the system it represents — "Bookings", "Subscription billing".
  </Step>

  <Step title="Generate credentials">
    Create an API key for it — see [Authentication](/developers/authentication).
  </Step>

  <Step title="Register your events">
    Call [`POST /events/register`](/developers/api/events#register-an-event-schema) for each event type your system emits, with a representative payload.
  </Step>

  <Step title="Ship the data flow">
    From your system, [create contacts](/developers/api/contacts) and [send events](/developers/api/events) as things happen.
  </Step>
</Steps>

## Integration patterns

<AccordionGroup>
  <Accordion title="SaaS / subscription business">
    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.
  </Accordion>

  <Accordion title="Bookings / services">
    Send `appointment_booked`, `appointment_completed`, `appointment_no_show`. Automate reminders before, review requests after, and re-booking nudges for lapsed clients.
  </Accordion>

  <Accordion title="Custom storefront (headless)">
    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](/integrations/shopify) and [WooCommerce](/integrations/woocommerce) connections.
  </Accordion>
</AccordionGroup>

## 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](/developers/rate-limits) and [Errors](/developers/errors).
* Consent (`email_opt_in`) set honestly at contact creation — see [Contacts API](/developers/api/contacts).
* Event names stable and documented for the marketing team.
* A staging organization for testing, so test events never trigger production automations.