Change Subscription Rate Card

client.subscriptions.changeRateCard(, , ?): SubscriptionChangeRateCardResponse { result }

post/subscriptions/{subscription_id}/change-rate-card

ParametersExpand Collapse

subscriptionID: string

body: SubscriptionChangeRateCardParams { rate_card_id, checkout_callback_urls, upgrade_behavior }

rate_card_id: string

The ID of the rate card to change the subscription to.

checkout_callback_urls?: CheckoutCallback { cancelled_url, success_url } | null

The URLs to redirect to after the checkout is completed or cancelled, if a checkout is required.

cancelled_url: string

The URL to redirect to after the checkout is cancelled.

minLength1

formaturi

success_url: string

The URL to redirect to after the checkout is successful.

minLength1

formaturi

upgrade_behavior?: "prorate" | "rate_difference"

The behavior to use when upgrading the subscription. If 'prorate', the customer will be charged for the prorated difference. If 'rate_difference', the customer will be charged for the difference in the rate cards without respect to time.

Accepts one of the following:

"prorate"

"rate_difference"

ReturnsExpand Collapse

SubscriptionChangeRateCardResponse { result }

result: ChangeSubscriptionRateCardRequiresActionResponse { action, type } | ChangeSubscriptionRateCardSuccessResponse { subscription, type }

The result of the request. If the request is successful, the subscription resource will be returned. If the request is requires action, the action to take to complete the request will be returned.

Accepts one of the following:

ChangeSubscriptionRateCardRequiresActionResponse { action, type }

action: Action { checkout_url, type }

The action to take to complete the request.

checkout_url: string

The URL of the checkout page to redirect to in order to complete the request.

type: "checkout"

type: "requires_action"

ChangeSubscriptionRateCardSuccessResponse { subscription, type }

subscription: SubscriptionResource { id, cancels_at_end_of_cycle, current_period, 8 more }

The updated subscription resource.

id: string

The ID of the subscription.

cancels_at_end_of_cycle: boolean

Whether the subscription will be cancelled at the end of the current cycle.

current_period: CurrentPeriod | null

The current period of the subscription if it is active.

end: string

formatdate-time

start: string

formatdate-time

inclusive_end?: boolean

inclusive_start?: boolean

cycles_next_at: string | null

The date and time the next cycle of the subscription will start.

formatdate-time

effective_at: string

The date and time the subscription became effective.

formatdate-time

fixed_rate_quantities: Record<string, string>

The quantities of the fixed rates of the subscription.

metadata: Record<string, string>

rate_card_id: string

The ID of the rate card of the subscription.

rate_price_multipliers: Record<string, string>

The price multipliers of the rates of the subscription.

status: "active" | "cancelled" | "paused"

The status of the subscription.

Accepts one of the following:

"active"

"cancelled"

"paused"

subject_id: string

The ID of the subject that the subscription is for.

type: "success"

Change Subscription Rate Card

import Lark from 'lark-billing';

const client = new Lark({
  apiKey: process.env['LARK_API_KEY'], // This is the default and can be omitted
});

const response = await client.subscriptions.changeRateCard('subscription_id', {
  rate_card_id: 'rc_jQK2n0wutCj6bBcAIrL6o07g',
  checkout_callback_urls: {
    cancelled_url: 'https://example.com/try-again',
    success_url: 'https://example.com/completed',
  },
  upgrade_behavior: 'prorate',
});

console.log(response.result);

{
  "result": {
    "action": {
      "checkout_url": "https://checkout.uselark.ai/...",
      "type": "checkout"
    },
    "type": "requires_action"
  }
}

Returns Examples

{
  "result": {
    "action": {
      "checkout_url": "https://checkout.uselark.ai/...",
      "type": "checkout"
    },
    "type": "requires_action"
  }
}