Action endpoints
Common Patterns
For each action, you'll implement an asynchronous function that:
- Accepts relevant parameters
- Performs the action using your payment provider's API
- Returns the updated subscription data
- Handles errors appropriately
Cancel Subscription
The Cancel action cancels a subscription or multiple subscriptions.
Options:
Option | Type | Description |
---|---|---|
customerId | string | The ID of the customer |
subscriptionIds | array | (Optional) Array of subscription IDs to cancel |
scheduledAt | string | When to cancel the subscription ('immediate' or 'end-of-period') |
unpause | boolean | Whether to unpause the subscription on cancel |
function cancelSubscription(options) {
if (options.subscriptionIds) {
return cancelMany(options.subscriptionIds, options);
} else {
return cancelAll(options.customerId, options);
}
}
async function cancelOne(subscription, options) {
switch (options.scheduledAt) {
case 'immediate':
// Implement immediate cancellation
break;
case 'end-of-period':
// Implement end-of-period cancellation
break;
}
}
Apply Coupon
The Apply Coupon action applies a coupon to a subscription or multiple subscriptions.
Options:
Option | Type | Description |
---|---|---|
customerId | string | The ID of the customer |
subscriptionIds | array | (Optional) Array of subscription IDs to apply the coupon to |
id | string | ID of the coupon in the provider system |
function applyCoupon(options) {
if (options.subscriptionIds) {
return applyMany(options.subscriptionIds, options);
} else {
return applyAll(options.customerId, options);
}
}
async function applyOne(subscription, options) {
// Implement coupon application logic
}
Extend Trial
The Extend Trial action extends the trial period of a subscription or multiple subscriptions.
Options:
Option | Type | Description |
---|---|---|
customerId | string | The ID of the customer |
subscriptionIds | array | (Optional) Array of subscription IDs to extend trial |
duration | object | The duration of the trial extension (e.g., { type: 'days', value: 7 }) |
function extendTrial(options) {
if (options.subscriptionIds) {
return extendMany(options.subscriptionIds, options);
} else {
return extendAll(options.customerId, options);
}
}
async function extendOne(subscription, options) {
// Implement trial extension logic based on options.duration
}
Pause Subscription
The Pause action pauses a subscription or multiple subscriptions.
Options:
Option | Type | Description |
---|---|---|
customerId | string | The ID of the customer |
subscriptionIds | array | (Optional) Array of subscription IDs to pause |
duration | object | The duration of the pause |
startDate | string | When to start the pause ('immediate' or 'period-end') |
allowAnnual | boolean | Whether to allow pausing annual subscriptions |
function pauseSubscription(options) {
if (options.subscriptionIds) {
return pauseMany(options.subscriptionIds, options);
} else {
return pauseAll(options.customerId, options);
}
}
async function pauseOne(subscription, options) {
switch (options.startDate) {
case 'immediate':
// Implement immediate pause
break;
case 'period-end':
// Implement end-of-period pause
break;
}
// Handle options.duration and options.allowAnnual
}
Change Price
The Change Price action changes the price of a subscription or multiple subscriptions.
Options:
Option | Type | Description |
---|---|---|
customerId | string | The ID of the customer |
subscriptionIds | array | (Optional) Array of subscription IDs to change price |
newPriceId | string | ID of the new price to apply |
prorate | boolean | Whether to prorate the price change (if supported) |
function changePrice(options) {
if (options.subscriptionIds) {
return changePriceMany(options.subscriptionIds, options);
} else {
return changePriceAll(options.customerId, options);
}
}
async function changePriceOne(subscription, options) {
// Implement price change logic
// Handle options.prorate if supported by your provider
}
Note: The actual options for ChangePrice may vary based on the implementation. This is a general example.
Implementing Actions
When implementing these actions for your payment provider:
- Create functions for each action (e.g.,
cancelSubscription
,applyCoupon
,extendTrial
,pauseSubscription
,changePrice
). - Implement the action-specific logic within the
One
function (e.g.,cancelOne
,applyOne
,extendOne
,pauseOne
,changePriceOne
). - Handle errors appropriately and return updated subscription data if required.
Example implementation for the Cancel action using a hypothetical payment provider:
async function cancelOne(subscription, options) {
try {
const result = await paymentProviderAPI.cancelSubscription(subscription.id, {
cancelAtPeriodEnd: options.scheduledAt === 'end-of-period',
unpause: options.unpause,
});
return result;
} catch (error) {
console.error(`Failed to cancel subscription ${subscription.id}:`, error);
throw error;
}
}
Remember to implement proper error handling, logging, and adapt the code to work with your specific payment provider's API.
In the Integration API Setup section, we'll cover how to bring all these components together into a cohesive integration setup.
Data Retrieval
Retrieval endpoints are responsible for fetching individual items and listing multiple items for each data type. These functions will interact with your payment provider's API and return data in the format expected by Churnkey.
Integration API Setup
This section demonstrates how to set up an Express API that integrates all components of your Churnkey integration. It provides a unified interface for Churnkey to interact with your payment provider. While we use Express in this example, you can use any language or framework as long as you properly expose the required routes.