.png)
Recurly Integration Guide
Integrate Recurly subscription billing data and selected billing events with enterprise systems through its versioned REST API and webhooks.
Recurly integration options at a glance
Recurly provides a versioned REST API for Accounts, Subscriptions, Plans, Invoices, Transactions, Items, Coupons, and related billing resources. Selected billing, subscription, account, invoice, payment, and dunning events can be delivered through Recurly webhooks. API requests use API-key authentication, while inbound webhook processing should validate Recurly signatures. Martini can consume the REST API, receive webhook notifications, orchestrate paginated synchronization, and map Recurly JSON into CRM, ERP, support, commerce, or warehouse models. Because a general-purpose bulk API, file API, GraphQL API, and SOAP API were not confirmed, large data movements should use controlled pagination, checkpoints, throttling, and reconciliation workflows.
| Integration point | Supported by Recurly? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Manage Accounts and Subscriptions, read Plans and Items, retrieve Invoices and Transactions, apply Coupons, and perform permitted billing adjustments or refunds. | Martini can consume Recurly REST endpoints from workflows, handle paginated responses, transform JSON, expose normalized APIs, and orchestrate downstream writes. |
| Webhooks / outbound callbacks | Yes | Receive selected account, subscription, invoice, payment, dunning, and billing lifecycle notifications. | Martini can expose a webhook endpoint or workflow, validate Recurly signatures, route event types, retrieve current resources, and process duplicate or retried deliveries. |
| Authentication | Yes | Authenticate server-to-server REST requests with a Recurly private API key and verify inbound webhook signatures. | Martini can store API keys and signing configuration in secure environment settings or secrets and apply them to outbound and inbound integration flows. |
| Pagination and scheduled synchronization | Yes | Retrieve collection resources page by page and reconcile missed webhook events or synchronize billing data on a schedule. | Martini can schedule workflows, persist cursors or checkpoints, control concurrency, and retry throttled or failed requests with bounded backoff. |
| Bulk / async / batch APIs | Not confirmed | A general-purpose bulk or asynchronous API covering all Recurly resources was not confirmed. | Martini can orchestrate repeated paginated requests and controlled batches, but workflows should not assume a single bulk operation exists for every resource. |
| File / attachment APIs | Not confirmed | A general-purpose file or attachment API for billing resources was not confirmed. | Martini can process files from other supported endpoints when available, but the specific Recurly capability must be verified before designing file exchange. |
| GraphQL APIs | Not confirmed | No official Recurly GraphQL API was confirmed in the reviewed material. | Martini can consume GraphQL APIs generally, but a Recurly integration should use the confirmed REST API instead. |
| SOAP APIs | Not confirmed | No official Recurly SOAP API was confirmed in the reviewed material. | Martini can consume SOAP services generally, but SOAP should not be assumed for Recurly integrations. |
How Recurly exposes data and business events
Recurly REST APIs
Recurly's versioned REST API provides resource-oriented access to Accounts, Subscriptions, Plans, Invoices, Transactions, Items, Coupons, and related billing resources. Collection responses are paginated, and endpoint filtering capabilities should be confirmed for each synchronization use case.
Martini implementation pattern
Martini implementation pattern: A Martini workflow authenticates with a secured Recurly API key, calls the required endpoint, follows pagination, maps the JSON response into a canonical model, applies business rules, and writes to one or more target systems. For write operations, the workflow records the Recurly identifier and handles throttling and retry behavior.
Implementation sequence
Recurly Webhooks
Recurly supports webhook notifications for selected account, subscription, invoice, payment, dunning, and billing events. Webhook coverage is event-specific and should not be assumed for every API operation.
Martini implementation pattern
Martini implementation pattern: Martini exposes an endpoint or webhook-consuming workflow, validates the Recurly signature, acknowledges the request promptly, and routes longer processing into an asynchronous workflow. The workflow can retrieve the current Account, Subscription, Invoice, or Transaction before updating downstream systems.
Implementation sequence
Scheduled reconciliation
Scheduled synchronization supplements webhook processing by detecting missed deliveries and refreshing important financial or subscription data. Recurly collection endpoints should be processed page by page with durable progress state.
Martini implementation pattern
Martini implementation pattern: A scheduled Martini workflow retrieves relevant resources using endpoint-supported filters where available, persists cursor or page checkpoints, compares source identifiers and statuses with downstream state, and retries incomplete pages or target writes without restarting the entire run.
Implementation sequence
Common Recurly integration patterns
Pattern 1: Sync subscription events to a CRM
When to use this pattern
Use this pattern when sales or customer-success teams need near-real-time visibility into new subscriptions, cancellations, renewals, plan changes, or payment-status updates.
Integration direction
Example Mapping
| Recurly Field | Canonical Field | Target Field |
|---|---|---|
| account.code | customer.externalId | Account.Recurly_Account_Id__c |
| subscription.state | subscription.status | Subscription_Status__c |
| subscription.plan.code | subscription.planCode | Plan_Code__c |
| subscription.current_term_ends_at | subscription.termEnd | Renewal_Date__c |
Martini implementation pattern
Martini receives a selected Recurly webhook, validates its signature, retrieves the current Account or Subscription when the event payload is incomplete, maps lifecycle states, and upserts Salesforce data using stable external identifiers. Duplicate deliveries are handled through an event log and idempotent updates; failed writes are retried or routed for review.
Martini capabilities used
- workflows
- API consumption
- webhook reception
- data mapping
- business rules
- error handling
Pattern 2: Synchronize billing data with NetSuite
When to use this pattern
Use this pattern for revenue operations, invoice synchronization, payment reconciliation, refund processing, and finance reporting.
Integration direction
Example Mapping
| Recurly Field | Canonical Field | Target Field |
|---|---|---|
| invoice.number | billingDocument.externalNumber | tranId |
| invoice.total | billingDocument.totalAmount | total |
| invoice.currency | billingDocument.currency | currency |
| transaction.type | financialTransaction.type | custbody_recurly_transaction_type |
Martini implementation pattern
A scheduled Martini workflow retrieves Invoices and Transactions page by page, preserves currency and amount precision, distinguishes invoice and payment states, and maps records to NetSuite finance structures. Durable checkpoints, bounded concurrency, duplicate checks, and retry handling allow a failed run to resume without duplicating downstream records.
Martini capabilities used
- scheduled workflows
- API consumption
- pagination orchestration
- data transformation
- checkpointing
- retry handling
Pattern 3: Synchronize the Recurly catalog
When to use this pattern
Use this pattern when commerce, quoting, or product applications need current Recurly Plans, Items, add-ons, or Coupons without each application implementing its own Recurly integration.
Integration direction
Example Mapping
| Recurly Field | Canonical Field | Target Field |
|---|---|---|
| plan.code | product.externalId | product.handle |
| plan.name | product.name | product.title |
| plan.unit_amount | product.recurringPrice | variant.price |
| plan.trial_length | product.trialDays | metafield.trial_days |
Martini implementation pattern
Martini retrieves catalog resources, maps pricing and trial metadata, applies supported-product, currency, and regional rules, and updates the downstream catalog. It can also expose a normalized API for consumers that need consistent plan information, while logging rejected or incomplete catalog items for correction.
Martini capabilities used
- workflows
- API consumption
- data mapping
- business rules
- API exposure
- monitoring
Pattern 4: Create or change subscriptions from a commerce event
When to use this pattern
Use this pattern when a completed sale, upgrade, downgrade, or cancellation in a commerce or internal application must initiate a controlled Recurly billing action.
Integration direction
Example Mapping
| Recurly Field | Canonical Field | Target Field |
|---|---|---|
| customer.id | customer.externalId | Account.code |
| line_item.plan_code | subscription.planCode | Subscription.plan_code |
| order.currency | billing.currency | Subscription.currency |
| order.id | order.externalId | Account.external_reference |
Martini implementation pattern
Martini receives the originating event, validates the customer, plan, currency, and billing terms, checks for an existing Recurly mapping, and calls the documented Account or Subscription endpoint. The workflow returns the Recurly identifier and status, applies duplicate and cancellation rules, and retries transient failures without repeating an accepted billing action.
Martini capabilities used
- API exposure
- workflows
- validation
- API consumption
- business rules
- idempotency and error handling
Applications commonly integrated with Recurly
Recurly billing data can be orchestrated into customer, finance, commerce, support, tax, and analytics applications. The appropriate direction depends on which system owns customer, subscription, payment, and reporting processes.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize account, subscription status, renewal, cancellation, and payment-lifecycle information with sales and customer-success teams. | Recurly → Martini → Salesforce | Receive selected Recurly webhook events or run a reconciliation workflow, retrieve the current Account or Subscription when needed, map lifecycle states, and upsert Salesforce objects using stable Recurly identifiers. |
| NetSuite | Send Invoices, Transactions, refunds, and customer billing information into finance and ERP processes. | Recurly → Martini → NetSuite | Use a scheduled workflow to page through Recurly billing resources, preserve monetary and currency fields, apply accounting rules, checkpoint progress, and retry failed NetSuite writes. |
| Microsoft Dynamics 365 | Align customer, billing, and subscription information across CRM and finance operations. | Recurly → Martini → Microsoft Dynamics 365 | Expose reusable Martini workflows for inbound customer or subscription actions and scheduled outbound synchronization, with ownership rules determining whether updates flow in one or both directions. |
| Shopify | Connect commerce purchases and customer information to subscription creation or recurring billing workflows. | Shopify → Martini → Recurly | Receive a commerce event, validate customer, plan, currency, and billing terms, call Recurly to create or update an Account or Subscription, and return the Recurly identifier and status. |
| Zendesk | Give support agents subscription, invoice, payment, and account-status context when assisting customers. | Recurly → Martini → Zendesk | Subscribe to relevant Recurly events or reconcile selected resources, normalize billing status and identifiers, and update support-facing customer data while excluding sensitive credentials and payment details. |
| Avalara | Exchange customer, address, transaction, and tax-related data for tax calculation or reporting workflows where the applicable products support the required operations. | Recurly → Martini → Avalara | Map Recurly customer and transaction values into the tax workflow, apply currency and jurisdiction rules, route responses to billing or finance processes, and retain correlation identifiers for reconciliation. |
| Snowflake | Load Accounts, Subscriptions, Invoices, and Transactions into a warehouse for revenue, retention, and cohort analysis. | Recurly → Martini → Snowflake | Run paginated extraction workflows, normalize JSON into warehouse-ready structures, preserve source identifiers and timestamps, and use checkpoints so failed loads can resume safely. |
| Stripe | Coordinate customer or payment data when an organization operates Recurly-managed subscriptions alongside Stripe-based payment flows. | Recurly → Martini → Stripe | Define ownership for each billing responsibility, mediate only the required synchronization through Martini, apply duplicate and conflict rules, and avoid assuming that both systems should process the same payment operation. |
How to build a Recurly integration in Martini
Objective
Configure the Recurly API version, endpoint settings, API key, and webhook verification values without embedding credentials in workflow logic.
Instructions in Martini
- Use Martini REST API configuration for the documented Recurly endpoint
- Store the private API key in secure environment configuration or secrets
- Separate development, test, and production credentials
- Configure webhook signature validation for inbound events
Objective
Select webhooks for selected near-real-time events and schedules for reconciliation or resource synchronization.
Instructions in Martini
- Expose a Martini API or webhook-consuming workflow for Recurly notifications
- Use a scheduler for periodic reconciliation and financial synchronization
- Define which system owns each Account, Subscription, and billing update
Objective
Receive the event or call the required Recurly REST resource, retrieving the current object when the notification does not contain sufficient data.
Instructions in Martini
- Classify the webhook event before performing follow-up work
- Call the relevant Account, Subscription, Invoice, or Transaction endpoint
- Follow collection pagination until the required page set is complete
- Persist cursors and checkpoints after successful downstream processing
Objective
Coordinate validation, enrichment, transformation, target writes, and response handling in a maintainable Martini workflow.
Instructions in Martini
- Keep webhook acknowledgment separate from longer processing where practical
- Use reusable workflow logic for common retrieval and mapping operations
- Route invalid, unsupported, or incomplete events to controlled error handling
- Record correlation identifiers for source events and target requests
Objective
Convert Recurly JSON and billing lifecycle values into canonical and target-specific data models without losing financial meaning.
Instructions in Martini
- Map stable Recurly identifiers to external keys
- Preserve currency, precision, tax, discount, refund, and adjustment fields
- Normalize timestamps while retaining required offsets
- Keep invoice, payment, subscription, and account states distinct
Objective
Enforce ownership, product, currency, regional, duplicate, and lifecycle rules before changing downstream or Recurly data.
Instructions in Martini
- Validate customer, plan, currency, and billing terms before subscription writes
- Use event identifiers or fingerprints to prevent duplicate processing
- Check whether a target object already represents the Recurly resource
- Apply documented endpoint and account permissions to billing operations
Common Recurly data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Accounts | Represent customer billing accounts, billing details, account state, and related customer information. | Salesforce, Microsoft Dynamics 365, Zendesk, NetSuite, Snowflake | Martini retrieves or receives Account data, normalizes identifiers and lifecycle state, filters sensitive fields, and upserts the result using the Recurly account identifier. |
| Subscriptions | Represent recurring subscription agreements, plans, lifecycle changes, trials, and cancellations associated with Accounts. | Salesforce, Microsoft Dynamics 365, Shopify, Snowflake | Martini processes subscription events or paginated resources, maps plan and status values, applies ownership rules, and makes downstream updates idempotent. |
| Plans | Define subscription pricing, trial configuration, billing intervals, and plan metadata. | Shopify, Salesforce, quoting applications, product services, Snowflake | Martini synchronizes plan definitions, applies currency, region, and product eligibility rules, and can expose a normalized catalog API. |
| Invoices | Represent billing documents generated for subscriptions, one-time charges, and adjustments. | NetSuite, Microsoft Dynamics 365, Zendesk, Snowflake | Martini preserves amounts, currency, tax, discount, adjustment, and status fields, then routes invoices to finance, support, or analytical workflows. |
| Transactions | Represent payments, refunds, authorization results, and other financial transaction data. | NetSuite, Avalara, Snowflake, finance applications | Martini extracts transactions with checkpoints, retains source identifiers and timestamps, applies reconciliation rules, and retries downstream writes safely. |
| Items | Represent catalog items used in subscription and charge configuration. | Shopify, product services, quoting applications, Snowflake | Martini maps item identifiers and metadata into downstream product models and applies supported-product and regional business rules. |
Authentication and security considerations
API authentication
Recurly uses API-key authentication for server-to-server API access. Store private keys in Martini secrets or secure environment configuration rather than embedding them in workflows.
Webhook verification
Recurly webhook notifications use signing that receiving systems should validate before accepting events. Restrict inbound endpoints and separate development, test, and production configuration.
Least privilege and sensitive data
- Grant only the API operations required by each workflow.
- Do not write API keys, complete payment details, or unnecessary customer information to logs.
- Protect workflow APIs with appropriate Martini authentication and authorization controls.
Operational considerations for Recurly integrations
Rate limits and pagination
Recurly API requests are subject to rate limiting. Process collections page by page, control concurrency, use bounded retries with backoff, and persist progress only after downstream processing succeeds.
Events and idempotency
Webhook deliveries and reconciliation runs can repeat the same business event. Store stable Recurly identifiers and event fingerprints, validate signatures, acknowledge quickly, and make downstream updates idempotent.
Financial and lifecycle data
Preserve currency, amount precision, tax, discount, refund, adjustment, and timestamp fields. Keep account, subscription, invoice, and payment states distinct because they represent different lifecycle concepts.
Versioning and testing
Configure the selected Recurly API version explicitly, tolerate additive fields and absent optional values, and test subscription states, invoice states, transaction types, currencies, discounts, and webhook retries before production deployment.
Why use Martini instead of scripts or point-to-point integrations?
Orchestration instead of isolated scripts
Martini coordinates Recurly API calls, webhook intake, pagination, target writes, business rules, and reconciliation in workflows that can be reused across billing processes.
Maintainable mappings
Centralized mappings and transformations keep Recurly JSON, canonical models, and target application structures consistent while preserving financial and lifecycle semantics.
Operational control
Martini provides a place to implement secure configuration, checkpoints, retries, duplicate handling, validation, monitoring, and controlled API exposure rather than distributing these concerns across point-to-point scripts.
Reusable integration assets
Teams can consume the documented Recurly REST API, receive selected events, and expose normalized Martini APIs without requiring a dedicated vendor connector.
Frequently asked questions
Recurly can be integrated through its versioned REST API and selected webhook notifications. REST endpoints provide access to Accounts, Subscriptions, Plans, Invoices, Transactions, Items, Coupons, and related resources, while webhooks support selected billing and subscription events. Enterprise workflows commonly combine webhooks, paginated API retrieval, scheduled reconciliation, API-key authentication, and downstream data mapping.
Yes. Martini can consume the Recurly REST API, receive selected Recurly webhook events, validate webhook signatures, orchestrate paginated synchronization, and map Recurly JSON into CRM, ERP, commerce, support, or warehouse systems. A dedicated native Martini Recurly connector is not documented in the supplied product context.
No. A dedicated Recurly connector is not required. Martini can use Recurly's confirmed native integration mechanisms, including its REST API, webhook notifications, API-key authentication, and webhook signature validation.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Recurly. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Recurly, cloud infrastructure, payment providers, or other third-party systems based on their subscriptions, usage, and deployment models.
New implementations should use the versioned Recurly REST API for resource operations and selected webhooks for event-driven processing. Martini can combine both methods, using webhooks for timely changes and scheduled, paginated reconciliation for missed events and important financial data. No official Recurly GraphQL or SOAP API was confirmed.
Yes. Martini can receive selected Recurly webhook notifications and validate their signatures before processing. Because webhook coverage is event-specific and deliveries can be duplicated or missed, implementations should record event identifiers, process resources idempotently, and run scheduled reconciliation using the filters supported by each endpoint.
Martini can retrieve Recurly Accounts, Subscriptions, Plans, Invoices, Transactions, and Items, follow pagination, and map JSON responses into canonical or target-specific models. Workflows can preserve financial precision, normalize timestamps, apply lifecycle and ownership rules, and write idempotent updates to downstream applications.
Martini workflows can classify HTTP and validation failures, apply bounded retries and backoff for transient failures or throttling, and route unrecoverable issues for review. Stable Recurly identifiers, webhook event identifiers or fingerprints, durable checkpoints, and processing logs help prevent duplicate Accounts, Subscriptions, Invoices, and Transactions. Martini can also expose an API façade that normalizes Recurly data for other applications.
Related Martini documentation
Workflows
Connect Recurly with your enterprise systems
Use Martini to orchestrate Recurly REST API calls, selected webhook events, billing synchronization, data transformation, and reliable downstream processing.