Skip to content
Lark
Join our SlackContact usGet started
API Reference
Subscriptions

Create Subscription

subscriptions.create(SubscriptionCreateParams**kwargs) -> SubscriptionCreateResponse
post/subscriptions

Create Subscription

ParametersExpand Collapse
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 use for the subscription.

subject_id: str

The ID or external ID of the subject to create the subscription for.

create_checkout_session: Optional[Literal["when_required", "always"]]

Determines whether a checkout session is always required even if the subject has a payment method on file. By default, if the subject has a payment method on file or the subscription is for a free plan, the subscription will be created and billed for immediately (if for a paid plan).

Accepts one of the following:
"when_required"
"always"
metadata: Optional[Dict[str, str]]

Additional metadata about the subscription. You may use this to store any custom data about the subscription.

ReturnsExpand Collapse
class SubscriptionCreateResponse: …
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 ResultCreateSubscriptionRequiresActionResponse: …
action: ResultCreateSubscriptionRequiresActionResponseAction

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.

requires_action_type: Literal["checkout"]
Accepts one of the following:
"checkout"
result_type: Literal["requires_action"]
Accepts one of the following:
"requires_action"
class ResultCreateSubscriptionSuccessResponse: …
result_type: Literal["success"]
Accepts one of the following:
"success"
subscription: SubscriptionResource

The created 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.

Create Subscription
from lark import Lark

client = Lark(
    api_key="My API Key",
)
subscription = client.subscriptions.create(
    checkout_callback_urls={
        "cancelled_url": "https://example.com/try-again",
        "success_url": "https://example.com/welcome",
    },
    rate_card_id="rc_AJWMxR81jxoRlli6p13uf3JB",
    subject_id="subj_VyX6Q96h5avMho8O7QWlKeXE",
    metadata={},
)
print(subscription.result)
{
  "result": {
    "result_type": "success",
    "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"
    }
  }
}
Returns Examples
{
  "result": {
    "result_type": "success",
    "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"
    }
  }
}