Recurly Commerce API

Provides Drupal integration with Recurly Commerce (formerly Prive), a Shopify-first subscription management platform acquired by Recurly in 2024. This module enables subscription billing, webhook handling, and customer portal management for sites that need to integrate with Recurly Commerce's REST API.

IMPORTANT: This module is for Recurly Commerce (Shopify integration), NOT standard Recurly. They are completely different products with different APIs, authentication methods, and admin portals. If you need standard Recurly integration, this is not the right module.

Features

This module provides:

• REST API Client: Complete PHP client for Recurly Commerce REST API with Bearer token authentication
• Webhook Handling: Secure webhook endpoint with HMAC-SHA256 signature verification
• Event System: Symfony event dispatching for incoming webhooks, allowing custom modules to react to subscription events
• Drush Commands: Command-line tools for:
  • Testing API connections
  • Listing subscriptions
  • Managing webhooks (create, list, delete)
• Secure Credential Storage: Integration with the Key module for secure API key storage
• Comprehensive Testing: Kernel tests for API service and webhook validation

Use Cases:

• Integrate Drupal with Shopify subscription businesses
• Process subscription lifecycle events (created, updated, cancelled)
• Handle billing events (successful payments, failed attempts)
• Manage customer subscriptions from Drupal
• Sync subscription data between Recurly Commerce and Drupal

Post-Installation

After enabling the module:

1. Configure API Credentials: Navigate to /admin/config/services/recurly-api
2. Create API Key in Recurly Commerce:
   • Log into https://admin.tryprive.com
   • Generate a new API key
   • Copy the Bearer token
3. Store API Key Securely:
   • Install and enable the Key module if not already installed
   • Create a new key at /admin/config/system/keys
   • Select "Configuration" as the key type
   • Paste your Recurly Commerce API key
   • Save the key
4. Configure Module Settings:
   • Select your API key from the dropdown
   • Optionally configure webhook signing key (provided when you create webhooks)
   • Enable webhook logging if desired for debugging
5. Test Connection:
   

   drush recurly:test-connection

6. Create Webhooks (optional, but recommended):
   

   drush recurly:create-webhook https://yoursite.com/recurly/webhook --events="subscriptions/created"
   drush recurly:create-webhook https://yoursite.com/recurly/webhook --events="billingAttempts/failed"

   Note: Recurly Commerce only supports ONE event topic per webhook, so you must create separate webhooks for each event type you want to receive.

7. React to Webhooks (optional): Create an event subscriber in your custom module to process webhook events.

Additional Requirements

Required Modules:

• Key (key) - For secure API credential storage
  • Available at: https://www.drupal.org/project/key

PHP Requirements:

• Drupal 9.4+, 10, or 11
• Guzzle HTTP client (included with Drupal core)

External Services:

• Active Recurly Commerce account (https://admin.tryprive.com)
• Valid API key from Recurly Commerce

Similar projects

Recurly (https://www.drupal.org/project/recurly)

• This is for the standard Recurly platform (v3.recurly.com)
• Uses HTTP Basic Authentication and the recurly/recurly-client PHP library
• If you're using standard Recurly (not Shopify integration), use that module instead
• This module (Recurly Commerce API) is for the Shopify-specific Recurly Commerce platform (formerly Prive)

Key Differences:

Feature Standard Recurly Module This Module (Recurly Commerce) Platform Recurly (universal) Recurly Commerce (Shopify-first) API URL v3.recurly.com subs.api.tryprive.com Auth HTTP Basic Bearer Token Admin recurly.com admin.tryprive.com Library recurly/recurly-client REST API (Guzzle) Webhooks Multiple topics per webhook ONE topic per webhook

Community Documentation

Official Recurly Commerce Documentation:

• Main Docs: https://docs.recurly.com/recurly-commerce/docs
• API Reference: https://docs.recurly.com/recurly-commerce/reference
• Webhook Documentation: https://docs.recurly.com/recurly-commerce/docs/webhooks
• Customer Portal Setup: https://docs.recurly.com/recurly-commerce/docs/customer-portal

Module Documentation:

• Full README with code examples: See README.md in the module
• Drush command reference: Run drush recurly --help
• API usage examples: See README.md "API Usage" section

Quick Start Example

// Get subscriptions
$recurly = \Drupal::service('recurly_commerce_api');
$subscriptions = $recurly->get('/subscriptions', ['limit' => 10]);

// Create webhook
$webhook = $recurly->post('/webhooks', [
  'address' => 'https://example.com/recurly/webhook',
  'topic' => 'subscriptions/created',
]);

// Update subscription status
$result = $recurly->patch('/subscriptions/sub_123/status', [
  'status' => 'paused'
]);