Change Subscription Rate Card

subscriptions.change_rate_card(, ) -> SubscriptionChangeRateCardResponse

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

ParametersExpand Collapse

subscription_id: str

checkout_callback_urls: CheckoutCallbackParam

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

cancelled_url: str

The URL to redirect to after the checkout is cancelled.

minLength1

formaturi

success_url: str

The URL to redirect to after the checkout is successful.

minLength1

formaturi

rate_card_id: str

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

upgrade_behavior: Optional[Literal["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

class SubscriptionChangeRateCardResponse: …

result: Result

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:

class ResultChangeSubscriptionRateCardRequiresActionResponse: …

action: ResultChangeSubscriptionRateCardRequiresActionResponseAction

The action to take to complete the request.

checkout_url: str

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

type: Literal["checkout"]

Accepts one of the following:

"checkout"

type: Literal["requires_action"]

Accepts one of the following:

"requires_action"

class ResultChangeSubscriptionRateCardSuccessResponse: …

subscription: SubscriptionResource

The updated subscription resource.

id: str

The ID of the subscription.

cancels_at_end_of_cycle: bool

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

current_period: Optional[CurrentPeriod]

The current period of the subscription if it is active.

end: datetime

formatdate-time

start: datetime

formatdate-time

inclusive_end: Optional[bool]

inclusive_start: Optional[bool]

cycles_next_at: Optional[datetime]

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

formatdate-time

effective_at: datetime

The date and time the subscription became effective.

formatdate-time

metadata: Dict[str, str]

rate_card_id: str

The ID of the rate card of the subscription.

status: Literal["active", "cancelled", "paused"]

The status of the subscription.

Accepts one of the following:

"active"

"cancelled"

"paused"

subject_id: str

The ID of the subject that the subscription is for.

type: Literal["success"]

Accepts one of the following:

"success"

Change Subscription Rate Card

from lark import Lark

client = Lark(
    api_key="My API Key",
)
response = client.subscriptions.change_rate_card(
    subscription_id="subscription_id",
    checkout_callback_urls={
        "cancelled_url": "https://example.com/try-again",
        "success_url": "https://example.com/completed",
    },
    rate_card_id="rc_jQK2n0wutCj6bBcAIrL6o07g",
    upgrade_behavior="prorate",
)
print(response.result)

{
  "result": {
    "subscription": {
      "id": "rc_sub_PuLvkNSP3IBCvjayBD3TXNQ6",
      "cancels_at_end_of_cycle": false,
      "current_period": {
        "end": "2025-11-01T00:00:00Z",
        "start": "2025-10-01T00:00:00Z",
        "inclusive_end": false,
        "inclusive_start": true
      },
      "cycles_next_at": "2025-11-01T00:00:00Z",
      "effective_at": "2025-10-01T00:00:00Z",
      "metadata": {},
      "rate_card_id": "rc_AJWMxR81jxoRlli6p13uf3JB",
      "status": "active",
      "subject_id": "subj_VyX6Q96h5avMho8O7QWlKeXE"
    },
    "type": "success"
  }
}

Returns Examples

{
  "result": {
    "subscription": {
      "id": "rc_sub_PuLvkNSP3IBCvjayBD3TXNQ6",
      "cancels_at_end_of_cycle": false,
      "current_period": {
        "end": "2025-11-01T00:00:00Z",
        "start": "2025-10-01T00:00:00Z",
        "inclusive_end": false,
        "inclusive_start": true
      },
      "cycles_next_at": "2025-11-01T00:00:00Z",
      "effective_at": "2025-10-01T00:00:00Z",
      "metadata": {},
      "rate_card_id": "rc_AJWMxR81jxoRlli6p13uf3JB",
      "status": "active",
      "subject_id": "subj_VyX6Q96h5avMho8O7QWlKeXE"
    },
    "type": "success"
  }
}