Create Subscription

post/subscriptions

Create Subscription

Body ParametersExpand Collapse

rate_card_id: string

The ID of the rate card to use for the subscription.

subject_id: string

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

checkout_callback_urls: optional CheckoutCallback { cancelled_url, success_url }

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

create_checkout_session: optional "when_required" or "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"

fixed_rate_quantities: optional map[number or string]

The quantities of the fixed rates to use for the subscription. Each quantity should be specified as a key-value pair, where the key is the code of the fixed rate and the value is the quantity. All fixed rates must have a quantity specified.

Accepts one of the following:

UnionMember0 = number

UnionMember1 = string

metadata: optional map[string]

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

rate_price_multipliers: optional map[number or string]

Pricing multipliers to apply to the rate amounts. Each price multiplier should be specified as a key-value pair, where the key is the code of the rate and the value is the price multiplier. Typically, pricing multipliers are used to apply a discount to a rate. For example, if a rate is $10 per seat and the price multiplier for the seats rate is 0.5, the discounted rate amount will be $5 per seat.

Accepts one of the following:

UnionMember0 = number

UnionMember1 = string

subscription_timeline_id: optional string

The ID of the subscription timeline to use for the subscription.

ReturnsExpand Collapse

result: object { action, result_type } or object { result_type, subscription }

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:

RequiresAction = object { action, result_type }

action: object { checkout_url, requires_action_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.

requires_action_type: "checkout"

result_type: "requires_action"

Success = object { result_type, subscription }

result_type: "success"

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

The created 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: object { end, start, inclusive_end, inclusive_start }

The current period of the subscription if it is active.

end: string

formatdate-time

start: string

formatdate-time

inclusive_end: optional boolean

inclusive_start: optional boolean

cycles_next_at: string

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: map[string]

The quantities of the fixed rates of the subscription.

metadata: map[string]

rate_card_id: string

The ID of the rate card of the subscription.

rate_price_multipliers: map[string]

The price multipliers of the rates of the subscription.

status: "active" or "cancelled" or "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.

Create Subscription

curl https://api.uselark.ai/subscriptions \
    -H 'Content-Type: application/json' \
    -H "X-API-Key: $LARK_API_KEY" \
    -d '{
          "rate_card_id": "rc_AJWMxR81jxoRlli6p13uf3JB",
          "subject_id": "subj_VyX6Q96h5avMho8O7QWlKeXE"
        }'

{
  "result": {
    "action": {
      "checkout_url": "checkout_url",
      "requires_action_type": "checkout"
    },
    "result_type": "requires_action"
  }
}

Returns Examples

{
  "result": {
    "action": {
      "checkout_url": "checkout_url",
      "requires_action_type": "checkout"
    },
    "result_type": "requires_action"
  }
}