Action endpoints - Churnkey Documentation

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.