MACRO NEPAL
Enterprise Subscription Management: Integrating Recurly with Java Applications
awiskar acharya
November 22, 2025
3:33 pm

Article

In the subscription economy, managing recurring billing, subscriptions, and revenue operations requires specialized tools. Recurly is a powerful enterprise-grade subscription management platform that handles billing, payments, and revenue operations, while Java provides the robust backend infrastructure needed for scalable subscription businesses. Integrating Recurly with Java applications enables companies to automate complex billing scenarios while maintaining control over their subscription logic.

What is Recurly?

Recurly is a subscription management platform that provides:

  • Recurring Billing: Automated invoicing and payment collection
  • Subscription Lifecycle Management: Handle upgrades, downgrades, and cancellations
  • Revenue Optimization: Reduce churn and increase lifetime value
  • Multiple Payment Gateways: Support for various payment methods
  • Dunning Management: Automated failed payment recovery
  • Analytics and Reporting: Revenue recognition and business insights

Why Recurly with Java?

  1. Complex Billing Scenarios: Handle usage-based pricing, tiers, and add-ons
  2. Enterprise Scale: Manage millions of subscriptions reliably
  3. Revenue Operations: Automated invoicing, taxes, and revenue recognition
  4. Payment Optimization: Reduce failed payments and churn
  5. Compliance: PCI DSS compliant, SOC 1 & 2 certified

Recurly Architecture for Java Applications

Java Application → Recurly Java Client → Recurly REST API → Subscription Management
↓
Webhooks → Event Processing → Database
↓
Payment Gateways → Transaction Processing

Setting Up Recurly Java Client

1. Add Dependencies:

<!-- pom.xml -->
<dependencies>
<!-- Recurly Official Client -->
<dependency>
<groupId>com.recurly</groupId>
<artifactId>recurly-client</artifactId>
<version>3.35.0</version>
</dependency>
<!-- Spring Boot Starters -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<!-- Database -->
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<scope>runtime</scope>
</dependency>
<!-- Validation -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<!-- JSON Processing -->
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
</dependency>
</dependencies>

2. Configuration Properties:

# application.yml
recurly:
api-key: ${RECURLY_API_KEY:your-recurly-api-key}
subdomain: ${RECURLY_SUBDOMAIN:your-company}
default-currency: ${RECURLY_DEFAULT_CURRENCY:USD}
timeout-ms: 30000
page-size: 50
app:
base-url: ${APP_BASE_URL:http://localhost:8080}
webhook-secret: ${WEBHOOK_SECRET:your-webhook-secret}

3. Recurly Configuration:

@Configuration
@ConfigurationProperties(prefix = "recurly")
@Data
public class RecurlyConfig {
private String apiKey;
private String subdomain;
private String defaultCurrency;
private Integer timeoutMs;
private Integer pageSize;
@Bean
public com.recurly.v3.Client recurlyClient() {
return new com.recurly.v3.Client(apiKey);
}
@Bean
public com.recurly.v3.resources.Subscriptions subscriptionsClient() {
return recurlyClient().newSubscriptions();
}
@Bean
public com.recurly.v3.resources.Accounts accountsClient() {
return recurlyClient().newAccounts();
}
@Bean
public com.recurly.v3.resources.Plans plansClient() {
return recurlyClient().newPlans();
}
}

Core Subscription Service

1. Account Management Service:

@Service
@Slf4j
public class RecurlyAccountService {
private final com.recurly.v3.resources.Accounts accountsClient;
private final AccountRepository accountRepository;
private final RecurlyConfig recurlyConfig;
public RecurlyAccountService(com.recurly.v3.resources.Accounts accountsClient,
AccountRepository accountRepository,
RecurlyConfig recurlyConfig) {
this.accountsClient = accountsClient;
this.accountRepository = accountRepository;
this.recurlyConfig = recurlyConfig;
}
public Account createAccount(CreateAccountRequest request) {
try {
AccountCreate accountCreate = new AccountCreate();
accountCreate.setCode(request.getAccountCode());
accountCreate.setEmail(request.getEmail());
accountCreate.setFirstName(request.getFirstName());
accountCreate.setLastName(request.getLastName());
accountCreate.setCompany(request.getCompany());
// Set billing info if provided
if (request.getBillingInfo() != null) {
accountCreate.setBillingInfo(createBillingInfo(request.getBillingInfo()));
}
Account account = accountsClient.createAccount(accountCreate);
// Save to local database
saveLocalAccountRecord(account, request);
log.info("Created Recurly account: {}", account.getCode());
return account;
} catch (com.recurly.v3.exception.ApiException e) {
log.error("Failed to create Recurly account", e);
throw new RecurlyServiceException("Failed to create account: " + e.getMessage(), e);
}
}
public Account getAccount(String accountCode) {
try {
return accountsClient.getAccount(accountCode);
} catch (com.recurly.v3.exception.ApiException e) {
log.error("Failed to get Recurly account: {}", accountCode, e);
throw new RecurlyServiceException("Failed to get account: " + e.getMessage(), e);
}
}
public Account updateAccount(String accountCode, UpdateAccountRequest request) {
try {
AccountUpdate accountUpdate = new AccountUpdate();
accountUpdate.setEmail(request.getEmail());
accountUpdate.setFirstName(request.getFirstName());
accountUpdate.setLastName(request.getLastName());
accountUpdate.setCompany(request.getCompany());
Account account = accountsClient.updateAccount(accountCode, accountUpdate);
// Update local database
updateLocalAccountRecord(account);
log.info("Updated Recurly account: {}", accountCode);
return account;
} catch (com.recurly.v3.exception.ApiException e) {
log.error("Failed to update Recurly account: {}", accountCode, e);
throw new RecurlyServiceException("Failed to update account: " + e.getMessage(), e);
}
}
public void closeAccount(String accountCode) {
try {
accountsClient.closeAccount(accountCode);
// Update local database
closeLocalAccountRecord(accountCode);
log.info("Closed Recurly account: {}", accountCode);
} catch (com.recurly.v3.exception.ApiException e) {
log.error("Failed to close Recurly account: {}", accountCode, e);
throw new RecurlyServiceException("Failed to close account: " + e.getMessage(), e);
}
}
public BillingInfo updateBillingInfo(String accountCode, BillingInfoRequest request) {
try {
BillingInfoCreate billingInfoCreate = createBillingInfo(request);
BillingInfo billingInfo = accountsClient.createBillingInfo(accountCode, billingInfoCreate);
log.info("Updated billing info for account: {}", accountCode);
return billingInfo;
} catch (com.recurly.v3.exception.ApiException e) {
log.error("Failed to update billing info for account: {}", accountCode, e);
throw new RecurlyServiceException("Failed to update billing info: " + e.getMessage(), e);
}
}
private BillingInfoCreate createBillingInfo(BillingInfoRequest request) {
BillingInfoCreate billingInfo = new BillingInfoCreate();
billingInfo.setFirstName(request.getFirstName());
billingInfo.setLastName(request.getLastName());
billingInfo.setNumber(request.getCardNumber());
billingInfo.setMonth(request.getExpMonth());
billingInfo.setYear(request.getExpYear());
billingInfo.setCvv(request.getCvv());
billingInfo.setAddress(request.getAddress().getStreet1());
billingInfo.setCity(request.getAddress().getCity());
billingInfo.setState(request.getAddress().getState());
billingInfo.setZip(request.getAddress().getPostalCode());
billingInfo.setCountry(request.getAddress().getCountry());
return billingInfo;
}
private void saveLocalAccountRecord(Account account, CreateAccountRequest request) {
AccountRecord record = AccountRecord.builder()
.accountCode(account.getCode())
.email(account.getEmail())
.firstName(account.getFirstName())
.lastName(account.getLastName())
.company(account.getCompany())
.state(account.getState())
.createdAt(Instant.now())
.build();
accountRepository.save(record);
}
private void updateLocalAccountRecord(Account account) {
accountRepository.findByAccountCode(account.getCode())
.ifPresent(record -> {
record.setEmail(account.getEmail());
record.setFirstName(account.getFirstName());
record.setLastName(account.getLastName());
record.setCompany(account.getCompany());
record.setState(account.getState());
record.setUpdatedAt(Instant.now());
accountRepository.save(record);
});
}
private void closeLocalAccountRecord(String accountCode) {
accountRepository.findByAccountCode(accountCode)
.ifPresent(record -> {
record.setState("closed");
record.setUpdatedAt(Instant.now());
accountRepository.save(record);
});
}
}

2. Subscription Management Service:

@Service
@Slf4j
public class RecurlySubscriptionService {
private final com.recurly.v3.resources.Subscriptions subscriptionsClient;
private final com.recurly.v3.resources.Plans plansClient;
private final SubscriptionRepository subscriptionRepository;
private final RecurlyConfig recurlyConfig;
public RecurlySubscriptionService(com.recurly.v3.resources.Subscriptions subscriptionsClient,
com.recurly.v3.resources.Plans plansClient,
SubscriptionRepository subscriptionRepository,
RecurlyConfig recurlyConfig) {
this.subscriptionsClient = subscriptionsClient;
this.plansClient = plansClient;
this.subscriptionRepository = subscriptionRepository;
this.recurlyConfig = recurlyConfig;
}
public Subscription createSubscription(CreateSubscriptionRequest request) {
try {
SubscriptionCreate subscriptionCreate = new SubscriptionCreate();
subscriptionCreate.setAccount(createAccountReference(request.getAccountCode()));
subscriptionCreate.setPlanCode(request.getPlanCode());
subscriptionCreate.setCurrency(recurlyConfig.getDefaultCurrency());
subscriptionCreate.setUnitAmount(request.getUnitAmount());
// Set custom fields if provided
if (request.getCustomFields() != null) {
subscriptionCreate.setCustomFields(createCustomFields(request.getCustomFields()));
}
// Set add-ons if provided
if (request.getAddOns() != null && !request.getAddOns().isEmpty()) {
subscriptionCreate.setAddOns(createSubscriptionAddOns(request.getAddOns()));
}
// Set billing info if provided
if (request.getBillingInfo() != null) {
subscriptionCreate.setBillingInfo(createBillingInfo(request.getBillingInfo()));
}
Subscription subscription = subscriptionsClient.createSubscription(subscriptionCreate);
// Save to local database
saveLocalSubscriptionRecord(subscription, request);
log.info("Created subscription: {} for account: {}", 
subscription.getId(), request.getAccountCode());
return subscription;
} catch (com.recurly.v3.exception.ApiException e) {
log.error("Failed to create subscription for account: {}", request.getAccountCode(), e);
throw new RecurlyServiceException("Failed to create subscription: " + e.getMessage(), e);
}
}
public Subscription getSubscription(String subscriptionId) {
try {
return subscriptionsClient.getSubscription(subscriptionId);
} catch (com.recurly.v3.exception.ApiException e) {
log.error("Failed to get subscription: {}", subscriptionId, e);
throw new RecurlyServiceException("Failed to get subscription: " + e.getMessage(), e);
}
}
public Subscription updateSubscription(String subscriptionId, UpdateSubscriptionRequest request) {
try {
SubscriptionUpdate subscriptionUpdate = new SubscriptionUpdate();
if (request.getPlanCode() != null) {
subscriptionUpdate.setPlanCode(request.getPlanCode());
}
if (request.getUnitAmount() != null) {
subscriptionUpdate.setUnitAmount(request.getUnitAmount());
}
if (request.getAddOns() != null) {
subscriptionUpdate.setAddOns(createSubscriptionAddOns(request.getAddOns()));
}
Subscription subscription = subscriptionsClient.updateSubscription(subscriptionId, subscriptionUpdate);
// Update local database
updateLocalSubscriptionRecord(subscription);
log.info("Updated subscription: {}", subscriptionId);
return subscription;
} catch (com.recurly.v3.exception.ApiException e) {
log.error("Failed to update subscription: {}", subscriptionId, e);
throw new RecurlyServiceException("Failed to update subscription: " + e.getMessage(), e);
}
}
public Subscription cancelSubscription(String subscriptionId, CancelSubscriptionRequest request) {
try {
SubscriptionCancel subscriptionCancel = new SubscriptionCancel();
if (request.getTimeframe() != null) {
subscriptionCancel.setTimeframe(SubscriptionCancel.Timeframe.fromValue(request.getTimeframe()));
}
Subscription subscription = subscriptionsClient.cancelSubscription(subscriptionId, subscriptionCancel);
// Update local database
cancelLocalSubscriptionRecord(subscriptionId);
log.info("Canceled subscription: {}", subscriptionId);
return subscription;
} catch (com.recurly.v3.exception.ApiException e) {
log.error("Failed to cancel subscription: {}", subscriptionId, e);
throw new RecurlyServiceException("Failed to cancel subscription: " + e.getMessage(), e);
}
}
public Subscription reactivateSubscription(String subscriptionId) {
try {
Subscription subscription = subscriptionsClient.reactivateSubscription(subscriptionId);
// Update local database
reactivateLocalSubscriptionRecord(subscriptionId);
log.info("Reactivated subscription: {}", subscriptionId);
return subscription;
} catch (com.recurly.v3.exception.ApiException e) {
log.error("Failed to reactivate subscription: {}", subscriptionId, e);
throw new RecurlyServiceException("Failed to reactivate subscription: " + e.getMessage(), e);
}
}
public Pause cancelSubscriptionPause(String subscriptionId) {
try {
Pause pause = subscriptionsClient.removeSubscriptionPause(subscriptionId);
log.info("Removed pause from subscription: {}", subscriptionId);
return pause;
} catch (com.recurly.v3.exception.ApiException e) {
log.error("Failed to remove subscription pause: {}", subscriptionId, e);
throw new RecurlyServiceException("Failed to remove subscription pause: " + e.getMessage(), e);
}
}
public List<Subscription> getAccountSubscriptions(String accountCode) {
try {
SubscriptionList result = subscriptionsClient.listSubscriptions(
new QueryParams().withLimit(recurlyConfig.getPageSize())
.withParam("account", accountCode)
);
return result.getData();
} catch (com.recurly.v3.exception.ApiException e) {
log.error("Failed to get subscriptions for account: {}", accountCode, e);
throw new RecurlyServiceException("Failed to get subscriptions: " + e.getMessage(), e);
}
}
private AccountPurchase createAccountReference(String accountCode) {
AccountPurchase accountRef = new AccountPurchase();
accountRef.setCode(accountCode);
return accountRef;
}
private List<SubscriptionAddOn> createSubscriptionAddOns(List<AddOnRequest> addOns) {
return addOns.stream()
.map(this::createSubscriptionAddOn)
.collect(Collectors.toList());
}
private SubscriptionAddOn createSubscriptionAddOn(AddOnRequest addOn) {
SubscriptionAddOn subscriptionAddOn = new SubscriptionAddOn();
subscriptionAddOn.setCode(addOn.getCode());
subscriptionAddOn.setUnitAmount(addOn.getUnitAmount());
subscriptionAddOn.setQuantity(addOn.getQuantity());
return subscriptionAddOn;
}
private BillingInfoCreate createBillingInfo(BillingInfoRequest request) {
BillingInfoCreate billingInfo = new BillingInfoCreate();
billingInfo.setFirstName(request.getFirstName());
billingInfo.setLastName(request.getLastName());
billingInfo.setNumber(request.getCardNumber());
billingInfo.setMonth(request.getExpMonth());
billingInfo.setYear(request.getExpYear());
billingInfo.setCvv(request.getCvv());
return billingInfo;
}
private List<CustomField> createCustomFields(Map<String, String> customFields) {
return customFields.entrySet().stream()
.map(entry -> {
CustomField field = new CustomField();
field.setName(entry.getKey());
field.setValue(entry.getValue());
return field;
})
.collect(Collectors.toList());
}
private void saveLocalSubscriptionRecord(Subscription subscription, CreateSubscriptionRequest request) {
SubscriptionRecord record = SubscriptionRecord.builder()
.subscriptionId(subscription.getId())
.accountCode(request.getAccountCode())
.planCode(request.getPlanCode())
.state(subscription.getState())
.unitAmount(request.getUnitAmount())
.currency(recurlyConfig.getDefaultCurrency())
.startDate(subscription.getCurrentPeriodStartedAt().toInstant())
.createdAt(Instant.now())
.build();
subscriptionRepository.save(record);
}
private void updateLocalSubscriptionRecord(Subscription subscription) {
subscriptionRepository.findBySubscriptionId(subscription.getId())
.ifPresent(record -> {
record.setState(subscription.getState());
record.setUnitAmount(subscription.getUnitAmount());
record.setUpdatedAt(Instant.now());
subscriptionRepository.save(record);
});
}
private void cancelLocalSubscriptionRecord(String subscriptionId) {
subscriptionRepository.findBySubscriptionId(subscriptionId)
.ifPresent(record -> {
record.setState("canceled");
record.setUpdatedAt(Instant.now());
subscriptionRepository.save(record);
});
}
private void reactivateLocalSubscriptionRecord(String subscriptionId) {
subscriptionRepository.findBySubscriptionId(subscriptionId)
.ifPresent(record -> {
record.setState("active");
record.setUpdatedAt(Instant.now());
subscriptionRepository.save(record);
});
}
}

Plan and Pricing Management

1. Plan Management Service:

@Service
@Slf4j
public class RecurlyPlanService {
private final com.recurly.v3.resources.Plans plansClient;
private final PlanRepository planRepository;
public RecurlyPlanService(com.recurly.v3.resources.Plans plansClient,
PlanRepository planRepository) {
this.plansClient = plansClient;
this.planRepository = planRepository;
}
public Plan createPlan(CreatePlanRequest request) {
try {
PlanCreate planCreate = new PlanCreate();
planCreate.setCode(request.getCode());
planCreate.setName(request.getName());
planCreate.setDescription(request.getDescription());
planCreate.setIntervalUnit(PlanCreate.IntervalUnit.fromValue(request.getIntervalUnit()));
planCreate.setIntervalLength(request.getIntervalLength());
// Set pricing
List<Pricing> pricingList = new ArrayList<>();
Pricing pricing = new Pricing();
pricing.setCurrency(request.getCurrency());
pricing.setUnitAmount(request.getUnitAmount());
pricingList.add(pricing);
planCreate.setCurrencies(pricingList);
// Set trial if provided
if (request.getTrialUnit() != null && request.getTrialLength() != null) {
planCreate.setTrialUnit(PlanCreate.TrialUnit.fromValue(request.getTrialUnit()));
planCreate.setTrialLength(request.getTrialLength());
}
Plan plan = plansClient.createPlan(planCreate);
// Save to local database
saveLocalPlanRecord(plan);
log.info("Created plan: {}", plan.getCode());
return plan;
} catch (com.recurly.v3.exception.ApiException e) {
log.error("Failed to create plan: {}", request.getCode(), e);
throw new RecurlyServiceException("Failed to create plan: " + e.getMessage(), e);
}
}
public Plan getPlan(String planCode) {
try {
return plansClient.getPlan(planCode);
} catch (com.recurly.v3.exception.ApiException e) {
log.error("Failed to get plan: {}", planCode, e);
throw new RecurlyServiceException("Failed to get plan: " + e.getMessage(), e);
}
}
public List<Plan> getAllPlans() {
try {
PlanList result = plansClient.listPlans(
new QueryParams().withLimit(100) // Adjust based on your needs
);
return result.getData();
} catch (com.recurly.v3.exception.ApiException e) {
log.error("Failed to list plans", e);
throw new RecurlyServiceException("Failed to list plans: " + e.getMessage(), e);
}
}
public Plan updatePlan(String planCode, UpdatePlanRequest request) {
try {
PlanUpdate planUpdate = new PlanUpdate();
planUpdate.setName(request.getName());
planUpdate.setDescription(request.getDescription());
Plan plan = plansClient.updatePlan(planCode, planUpdate);
// Update local database
updateLocalPlanRecord(plan);
log.info("Updated plan: {}", planCode);
return plan;
} catch (com.recurly.v3.exception.ApiException e) {
log.error("Failed to update plan: {}", planCode, e);
throw new RecurlyServiceException("Failed to update plan: " + e.getMessage(), e);
}
}
public void deletePlan(String planCode) {
try {
plansClient.deactivatePlan(planCode);
// Update local database
deactivateLocalPlanRecord(planCode);
log.info("Deleted plan: {}", planCode);
} catch (com.recurly.v3.exception.ApiException e) {
log.error("Failed to delete plan: {}", planCode, e);
throw new RecurlyServiceException("Failed to delete plan: " + e.getMessage(), e);
}
}
private void saveLocalPlanRecord(Plan plan) {
PlanRecord record = PlanRecord.builder()
.planCode(plan.getCode())
.name(plan.getName())
.description(plan.getDescription())
.intervalUnit(plan.getIntervalUnit().toString())
.intervalLength(plan.getIntervalLength())
.state(plan.getState())
.createdAt(Instant.now())
.build();
planRepository.save(record);
}
private void updateLocalPlanRecord(Plan plan) {
planRepository.findByPlanCode(plan.getCode())
.ifPresent(record -> {
record.setName(plan.getName());
record.setDescription(plan.getDescription());
record.setState(plan.getState());
record.setUpdatedAt(Instant.now());
planRepository.save(record);
});
}
private void deactivateLocalPlanRecord(String planCode) {
planRepository.findByPlanCode(planCode)
.ifPresent(record -> {
record.setState("inactive");
record.setUpdatedAt(Instant.now());
planRepository.save(record);
});
}
}

Data Models

1. Request/Response Models:

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class CreateAccountRequest {
@NotBlank
private String accountCode;
@Email
@NotBlank
private String email;
@NotBlank
private String firstName;
@NotBlank
private String lastName;
private String company;
private BillingInfoRequest billingInfo;
}
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class CreateSubscriptionRequest {
@NotBlank
private String accountCode;
@NotBlank
private String planCode;
@NotNull
private Integer unitAmount;
private BillingInfoRequest billingInfo;
private List<AddOnRequest> addOns;
private Map<String, String> customFields;
}
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class BillingInfoRequest {
@NotBlank
private String firstName;
@NotBlank
private String lastName;
@NotBlank
private String cardNumber;
@NotBlank
private String expMonth;
@NotBlank
private String expYear;
private String cvv;
private AddressRequest address;
}
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class AddOnRequest {
@NotBlank
private String code;
@NotNull
private Integer unitAmount;
@NotNull
private Integer quantity;
}
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class CreatePlanRequest {
@NotBlank
private String code;
@NotBlank
private String name;
private String description;
@NotBlank
private String intervalUnit; // "months" or "days"
@NotNull
private Integer intervalLength;
@NotBlank
private String currency;
@NotNull
private Integer unitAmount;
private String trialUnit;
private Integer trialLength;
}

2. Database Entities:

@Entity
@Table(name = "account_records")
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class AccountRecord {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(name = "account_code", unique = true, nullable = false)
private String accountCode;
@Column(name = "email")
private String email;
@Column(name = "first_name")
private String firstName;
@Column(name = "last_name")
private String lastName;
@Column(name = "company")
private String company;
@Column(name = "state")
private String state;
@Column(name = "created_at")
private Instant createdAt;
@Column(name = "updated_at")
private Instant updatedAt;
@PrePersist
protected void onCreate() {
createdAt = Instant.now();
}
@PreUpdate
protected void onUpdate() {
updatedAt = Instant.now();
}
}
@Entity
@Table(name = "subscription_records")
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class SubscriptionRecord {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(name = "subscription_id", unique = true, nullable = false)
private String subscriptionId;
@Column(name = "account_code", nullable = false)
private String accountCode;
@Column(name = "plan_code", nullable = false)
private String planCode;
@Column(name = "state")
private String state;
@Column(name = "unit_amount")
private Integer unitAmount;
@Column(name = "currency")
private String currency;
@Column(name = "start_date")
private Instant startDate;
@Column(name = "created_at")
private Instant createdAt;
@Column(name = "updated_at")
private Instant updatedAt;
@PrePersist
protected void onCreate() {
createdAt = Instant.now();
}
@PreUpdate
protected void onUpdate() {
updatedAt = Instant.now();
}
}

REST Controllers

1. Account Controller:

@RestController
@RequestMapping("/api/accounts")
@Slf4j
@Validated
public class AccountController {
private final RecurlyAccountService accountService;
public AccountController(RecurlyAccountService accountService) {
this.accountService = accountService;
}
@PostMapping
public ResponseEntity<Account> createAccount(@Valid @RequestBody CreateAccountRequest request) {
try {
Account account = accountService.createAccount(request);
return ResponseEntity.status(HttpStatus.CREATED).body(account);
} catch (RecurlyServiceException e) {
log.error("Account creation failed", e);
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
}
}
@GetMapping("/{accountCode}")
public ResponseEntity<Account> getAccount(@PathVariable String accountCode) {
try {
Account account = accountService.getAccount(accountCode);
return ResponseEntity.ok(account);
} catch (RecurlyServiceException e) {
log.error("Failed to get account: {}", accountCode, e);
return ResponseEntity.notFound().build();
}
}
@PutMapping("/{accountCode}")
public ResponseEntity<Account> updateAccount(@PathVariable String accountCode,
@Valid @RequestBody UpdateAccountRequest request) {
try {
Account account = accountService.updateAccount(accountCode, request);
return ResponseEntity.ok(account);
} catch (RecurlyServiceException e) {
log.error("Failed to update account: {}", accountCode, e);
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
}
}
@DeleteMapping("/{accountCode}")
public ResponseEntity<Void> closeAccount(@PathVariable String accountCode) {
try {
accountService.closeAccount(accountCode);
return ResponseEntity.noContent().build();
} catch (RecurlyServiceException e) {
log.error("Failed to close account: {}", accountCode, e);
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
}
}
@PutMapping("/{accountCode}/billing-info")
public ResponseEntity<BillingInfo> updateBillingInfo(@PathVariable String accountCode,
@Valid @RequestBody BillingInfoRequest request) {
try {
BillingInfo billingInfo = accountService.updateBillingInfo(accountCode, request);
return ResponseEntity.ok(billingInfo);
} catch (RecurlyServiceException e) {
log.error("Failed to update billing info for account: {}", accountCode, e);
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
}
}
}

2. Subscription Controller:

@RestController
@RequestMapping("/api/subscriptions")
@Slf4j
@Validated
public class SubscriptionController {
private final RecurlySubscriptionService subscriptionService;
public SubscriptionController(RecurlySubscriptionService subscriptionService) {
this.subscriptionService = subscriptionService;
}
@PostMapping
public ResponseEntity<Subscription> createSubscription(@Valid @RequestBody CreateSubscriptionRequest request) {
try {
Subscription subscription = subscriptionService.createSubscription(request);
return ResponseEntity.status(HttpStatus.CREATED).body(subscription);
} catch (RecurlyServiceException e) {
log.error("Subscription creation failed", e);
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
}
}
@GetMapping("/{subscriptionId}")
public ResponseEntity<Subscription> getSubscription(@PathVariable String subscriptionId) {
try {
Subscription subscription = subscriptionService.getSubscription(subscriptionId);
return ResponseEntity.ok(subscription);
} catch (RecurlyServiceException e) {
log.error("Failed to get subscription: {}", subscriptionId, e);
return ResponseEntity.notFound().build();
}
}
@PutMapping("/{subscriptionId}")
public ResponseEntity<Subscription> updateSubscription(@PathVariable String subscriptionId,
@Valid @RequestBody UpdateSubscriptionRequest request) {
try {
Subscription subscription = subscriptionService.updateSubscription(subscriptionId, request);
return ResponseEntity.ok(subscription);
} catch (RecurlyServiceException e) {
log.error("Failed to update subscription: {}", subscriptionId, e);
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
}
}
@PostMapping("/{subscriptionId}/cancel")
public ResponseEntity<Subscription> cancelSubscription(@PathVariable String subscriptionId,
@Valid @RequestBody CancelSubscriptionRequest request) {
try {
Subscription subscription = subscriptionService.cancelSubscription(subscriptionId, request);
return ResponseEntity.ok(subscription);
} catch (RecurlyServiceException e) {
log.error("Failed to cancel subscription: {}", subscriptionId, e);
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
}
}
@PostMapping("/{subscriptionId}/reactivate")
public ResponseEntity<Subscription> reactivateSubscription(@PathVariable String subscriptionId) {
try {
Subscription subscription = subscriptionService.reactivateSubscription(subscriptionId);
return ResponseEntity.ok(subscription);
} catch (RecurlyServiceException e) {
log.error("Failed to reactivate subscription: {}", subscriptionId, e);
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
}
}
@GetMapping("/account/{accountCode}")
public ResponseEntity<List<Subscription>> getAccountSubscriptions(@PathVariable String accountCode) {
try {
List<Subscription> subscriptions = subscriptionService.getAccountSubscriptions(accountCode);
return ResponseEntity.ok(subscriptions);
} catch (RecurlyServiceException e) {
log.error("Failed to get subscriptions for account: {}", accountCode, e);
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
}
}
}

Webhook Handling

1. Webhook Controller:

@RestController
@RequestMapping("/webhooks/recurly")
@Slf4j
public class RecurlyWebhookController {
private final SubscriptionRepository subscriptionRepository;
private final AccountRepository accountRepository;
public RecurlyWebhookController(SubscriptionRepository subscriptionRepository,
AccountRepository accountRepository) {
this.subscriptionRepository = subscriptionRepository;
this.accountRepository = accountRepository;
}
@PostMapping
public ResponseEntity<String> handleWebhook(@RequestBody String payload,
@RequestHeader("Recurly-Signature") String signature) {
try {
// Verify webhook signature (simplified - use proper verification in production)
if (!verifyWebhookSignature(payload, signature)) {
log.warn("Invalid webhook signature");
return ResponseEntity.status(HttpStatus.BAD_REQUEST).build();
}
// Parse webhook notification
JsonNode notification = new ObjectMapper().readTree(payload);
String type = notification.get("type").asText();
log.info("Received Recurly webhook: {}", type);
// Handle different webhook types
switch (type) {
case "new_subscription_notification":
handleNewSubscription(notification);
break;
case "updated_subscription_notification":
handleUpdatedSubscription(notification);
break;
case "canceled_subscription_notification":
handleCanceledSubscription(notification);
break;
case "renewed_subscription_notification":
handleRenewedSubscription(notification);
break;
case "successful_payment_notification":
handleSuccessfulPayment(notification);
break;
case "failed_payment_notification":
handleFailedPayment(notification);
break;
default:
log.debug("Unhandled webhook type: {}", type);
}
return ResponseEntity.ok("Webhook processed");
} catch (Exception e) {
log.error("Webhook processing failed", e);
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
}
}
private boolean verifyWebhookSignature(String payload, String signature) {
// Implement proper webhook signature verification
// Recurly provides signatures for verification
return true; // Simplified for example
}
private void handleNewSubscription(JsonNode notification) {
JsonNode subscription = notification.get("subscription");
String subscriptionId = subscription.get("uuid").asText();
String accountCode = subscription.get("account").get("code").asText();
subscriptionRepository.findBySubscriptionId(subscriptionId)
.ifPresentOrElse(
record -> log.info("Subscription already exists: {}", subscriptionId),
() -> {
// Create new subscription record
SubscriptionRecord newRecord = SubscriptionRecord.builder()
.subscriptionId(subscriptionId)
.accountCode(accountCode)
.planCode(subscription.get("plan").get("code").asText())
.state(subscription.get("state").asText())
.unitAmount(subscription.get("unit_amount").asInt())
.currency(subscription.get("currency").asText())
.startDate(Instant.parse(subscription.get("activated_at").asText()))
.createdAt(Instant.now())
.build();
subscriptionRepository.save(newRecord);
log.info("Created subscription record from webhook: {}", subscriptionId);
}
);
}
private void handleUpdatedSubscription(JsonNode notification) {
JsonNode subscription = notification.get("subscription");
String subscriptionId = subscription.get("uuid").asText();
subscriptionRepository.findBySubscriptionId(subscriptionId)
.ifPresent(record -> {
record.setState(subscription.get("state").asText());
record.setUnitAmount(subscription.get("unit_amount").asInt());
record.setUpdatedAt(Instant.now());
subscriptionRepository.save(record);
log.info("Updated subscription from webhook: {}", subscriptionId);
});
}
private void handleCanceledSubscription(JsonNode notification) {
JsonNode subscription = notification.get("subscription");
String subscriptionId = subscription.get("uuid").asText();
subscriptionRepository.findBySubscriptionId(subscriptionId)
.ifPresent(record -> {
record.setState("canceled");
record.setUpdatedAt(Instant.now());
subscriptionRepository.save(record);
log.info("Canceled subscription from webhook: {}", subscriptionId);
});
}
private void handleRenewedSubscription(JsonNode notification) {
JsonNode subscription = notification.get("subscription");
String subscriptionId = subscription.get("uuid").asText();
log.info("Subscription renewed: {}", subscriptionId);
// Handle renewal logic
}
private void handleSuccessfulPayment(JsonNode notification) {
JsonNode transaction = notification.get("transaction");
String accountCode = transaction.get("account").get("code").asText();
log.info("Successful payment for account: {}", accountCode);
// Handle successful payment logic
}
private void handleFailedPayment(JsonNode notification) {
JsonNode transaction = notification.get("transaction");
String accountCode = transaction.get("account").get("code").asText();
log.warn("Failed payment for account: {}", accountCode);
// Handle failed payment logic
}
}

Error Handling

1. Custom Exceptions:

public class RecurlyServiceException extends RuntimeException {
public RecurlyServiceException(String message) {
super(message);
}
public RecurlyServiceException(String message, Throwable cause) {
super(message, cause);
}
}
@RestControllerAdvice
@Slf4j
public class RecurlyExceptionHandler {
@ExceptionHandler(RecurlyServiceException.class)
public ResponseEntity<ErrorResponse> handleRecurlyException(RecurlyServiceException e) {
log.error("Recurly service error", e);
ErrorResponse error = ErrorResponse.builder()
.code("RECURLY_SERVICE_ERROR")
.message("Subscription service temporarily unavailable")
.timestamp(Instant.now())
.build();
return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).body(error);
}
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ErrorResponse> handleValidationException(MethodArgumentNotValidException e) {
List<String> errors = e.getBindingResult()
.getFieldErrors()
.stream()
.map(error -> error.getField() + ": " + error.getDefaultMessage())
.collect(Collectors.toList());
ErrorResponse error = ErrorResponse.builder()
.code("VALIDATION_ERROR")
.message("Invalid request parameters")
.details(errors)
.timestamp(Instant.now())
.build();
return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(error);
}
}
@Data
@Builder
class ErrorResponse {
private String code;
private String message;
private Object details;
private Instant timestamp;
}

Best Practices

1. Health Check:

@Component
public class RecurlyHealthIndicator implements HealthIndicator {
private final RecurlyPlanService planService;
public RecurlyHealthIndicator(RecurlyPlanService planService) {
this.planService = planService;
}
@Override
public Health health() {
try {
// Try to list plans to verify connectivity
planService.getAllPlans();
return Health.up().withDetail("recurly", "connected").build();
} catch (Exception e) {
return Health.down()
.withDetail("recurly", "disconnected")
.withDetail("error", e.getMessage())
.build();
}
}
}

Conclusion

Integrating Recurly with Java applications provides a robust foundation for managing complex subscription businesses at scale. The combination of Recurly's enterprise-grade subscription management with Java's reliability and performance creates a powerful platform for SaaS companies, subscription services, and any business relying on recurring revenue models.

By leveraging the Recurly Java client, developers can implement sophisticated billing scenarios, handle subscription lifecycle events, and maintain synchronization between Recurly and their application data. The comprehensive webhook support enables real-time updates and ensures data consistency across systems, making it possible to build responsive, event-driven subscription management systems that scale with business growth.

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper