Skip to content

Integrating Recurly

Auth: API key · Partner program: not required · Setup time: about 10 minutes · Last verified: 2026-05-15

Mid-market subscription-billing platform — strong dunning and revenue-recognition tooling. Sits on top of an underlying gateway (Stripe, Adyen, Braintree, Authorize.Net, …) like Chargebee.

HTTP Basic with the Private API key as the username (password blank). Generate under Integrations → API Credentials.

  • Charge.gateway = 'recurly', NOT the underlying processor. Same convention as Chargebee — biller is the recorded gateway, metadata.processor names the actual money-mover. The same charge may appear via both Recurly and (e.g.) Stripe if both connections are configured.
  • Versioned API. Recurly v3 pins the version via Accept: application/vnd.recurly.v2021-02-25+json. Bump after re-testing.
  • Webhooks are unsigned XML. Recurly doesn’t cryptographically sign deliveries. Standard practice is to allow-list source IPs and put the webhook URL behind a hard-to-guess path. The adapter parses both signed-JSON (newer) and unsigned-XML (legacy) shapes.
  • Cancel vs terminate. cancelSubscription({ atPeriodEnd: true }) schedules cancellation for the end of the current term; atPeriodEnd: false calls terminate for immediate cancellation. Pick deliberately.