What we do
Tools
Industries
Department
How we workLet's talk →
Home/Recurly/Recurly API v3
Recurly

Recurly API v3: Pass the Version Check, Then Handle Events in Any Order

Your first call came back 406 and the key looks right. On Recurly's v3 API that's almost always the version header, not the credentials. Once requests go through, the harder part is the events: a single signup can send a subscription notification and a payment notification, and they don't promise to arrive in order.

A v3 request that works

Base URL: https://v3.recurly.com, or https://v3.eu.recurly.com if your site is hosted in the EU.

Auth: HTTP Basic, with the private API key as the username and an empty password. Keys live on the API Credentials page in the Recurly app.

Version: every request needs Accept: application/vnd.recurly.v2021-02-25 (the +json form works too). Leave it off and the call fails. Pin it in production rather than asking for latest.

Limits: sandbox sites get 400 requests a minute across all methods. Production gets 1,000 a minute, and only GETs count. Watch X-RateLimit-Remaining; going over returns a 429.

Why a working sandbox build misbehaves in production

A 406 on every call

How you'll know: The response has error.type set to invalid_api_version.

Fix: Send the Accept header with a real version string. The error body lists the values Recurly accepts. Client library 4.x already targets v2021-02-25, so check you aren't mixing an old library with new code.

A nightly sync that hits 429s

How you'll know: A job walking every account and subscription stalls partway through.

Fix: Reads are what's limited in production, and the limit is measured over a rolling five-minute window. Page with limit and follow next until has_more is false, and slow down when X-RateLimit-Remaining gets low instead of retrying in a tight loop.

Access revoked, then granted back by a stale event

How you'll know: A customer who paid gets locked out, or a canceled one keeps access, after notifications land in the wrong order.

Fix: Treat each JSON notification as a pointer. It carries the event type and object IDs, so fetch the current subscription from the API and act on that, not on the order events arrived in.

The same renewal processed twice

How you'll know: Two welcome emails, or a CRM deal logged twice.

Fix: Recurly retries failed notifications with growing gaps between attempts, so your endpoint has to accept repeats. Record what you've already handled and skip it the second time.

Signatures fail right after someone regenerated the secret

How you'll know: The recurly-signature header has more than one value in it.

Fix: The header holds a millisecond timestamp, then one or more HMAC-SHA256 signatures of timestamp.body. After the secret is regenerated, the header can carry signatures for both the old and new secret for a period, so accept a match on any of them, and reject stale timestamps.

Collecting the card: recurly.js fields or a Recurly-hosted page

The API alone gives you no safe way to take a card number. You need one of these.

recurly.js

Hosted fields inside your own form

  • Card fields sit in your signup or upgrade screen, styled to match it.
  • The card data goes from the browser to Recurly and comes back as a token your server uses in the API call.
  • Raw card numbers never reach your server, which keeps most PCI scope off your plate.
Hosted payment pages

Recurly's own checkout screens

  • You send the customer to a Recurly-hosted URL instead of building a form.
  • Least code to write and maintain.
  • The step looks less like your product, so it suits back-office or low-touch signups better.

Either way, what happens after the card is accepted is up to your code, and that's where the webhook work above begins.

From the test gateway to real money

Recurly's sandbox comes with a test gateway and documented test card numbers, so you can force an approval, a decline or a particular failure code while you build. Use it to rehearse the failure paths, not just the happy one, because those are the notifications your access rules depend on.

Going live also means choosing the gateway Recurly bills through. Recurly isn't the processor. It runs plans, invoices and dunning on top of a gateway such as Braintree, PayPal or Stripe, and that choice affects settlement timing and fees, which finance will want to know before launch. If you're weighing that decision, our Recurly vs. Stripe page lays out the trade.

n-frames builds the parts around the API: the endpoint that checks recurly-signature, refetches the object and updates your app, CRM and support desk, and the integrations that keep subscriber data in the marketing and sales tools your team already uses.

Questions people ask

Does Recurly have a sandbox for testing before going live?

It does: a sandbox site with a test gateway and documented test cards that produce specific results, such as a successful charge, a decline or a given failure code. Sandbox limits differ from production, at 400 requests a minute across every method.

What is recurly.js and do I need it?

It's Recurly's browser library for collecting card details without them passing through your server. You need either recurly.js with its hosted fields, or Recurly's hosted payment pages. The REST API takes the token recurly.js produces, never the raw card.

What triggers a Recurly webhook?

Changes to accounts, subscriptions and payments: a new or updated subscription, a cancellation, a successful or failed payment, and account events such as creation or closure. Older Recurly docs call them push notifications. You pick which types each endpoint gets in the Recurly app, and each endpoint receives JSON or XML, not both.

Does Recurly process payments itself, or does it need a separate gateway?

It needs a gateway. Recurly handles subscriptions, invoicing and dunning, and connects to processors such as Braintree, PayPal and Stripe to actually move the money.

What are Recurly hosted payment pages?

Checkout screens Recurly hosts for you. Instead of embedding a card form with recurly.js, you send the customer to a Recurly URL to enter their details.

Do POST and PUT calls count toward the Recurly rate limit?

Not on a production site, where only GET requests count against the 1,000-a-minute limit. On a sandbox site, every method counts toward 400 a minute.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.