Import a subscription

Idempotency Supported

Imports a subscription into Chargebee.

Sample Request

Sample Result[JSON]

URL Format

POST https://[site].chargebee.com/api/v2/subscriptions/import_subscription

Input Parameters

optional, string, max chars=50

Id for the new subscription. If not given, this will be auto-generated.

client_profile_id

optional, string, max chars=50

Indicates the Client profile id for the customer. This is applicable only if you use Chargebee's AvaTax for Communications integration.

plan_id

required, string, max chars=100

Identifier of the plan for this subscription.

plan_quantity

optional, integer, default=1, min=1

Plan quantity for this subscription.

plan_quantity_in_decimal

optional, string, max chars=33

The decimal representation of the quantity of the plan purchased. Can be provided for quantity-based plans and only when multi-decimal pricing is enabled.

plan_unit_price

optional, in cents, min=0

Amount that will override the Plan's default price. The unit depends on the type of currency .

plan_unit_price_in_decimal

optional, string, max chars=39

When price overriding is enabled for the site, the price or per-unit price of the plan can be set here. The value set for the plan is used by default. Provide the value as a decimal string in major units of the currency. Can be provided only when multi-decimal pricing is enabled.

setup_fee

optional, in cents, min=0

Amount that will override the default setup fee. The unit depends on the type of currency .

trial_end

optional, timestamp(UTC) in seconds

The time at which the trial ends for this subscription. Can be specified to override the default trial period.If '0' is passed, the subscription will be activated immediately.

billing_cycles

optional, integer, min=0

Number of cycles(plan interval) this subscription should be charged. After the billing cycles exhausted, the subscription will be cancelled.

start_date

optional, timestamp(UTC) in seconds

The date/time at which the subscription is to start or has started. If not provided, the subscription starts immediately.

auto_collection

optional, enumerated string

Defines whether payments need to be collected automatically for this subscription. Overrides customer's auto-collection property.

Enum Values

Whenever an invoice is created for this subscription, an automatic charge will be attempted on the payment method available.

off

Automatic collection of charges will not be made for this subscription. Use this for offline payments.

po_number

optional, string, max chars=100

Purchase order number for this subscription.

coupon_ids

optional, string, max chars=100

List of coupons to be applied to this subscription. You can provide coupon ids or coupon codes.

contract_term_billing_cycle_on_renewal

optional, integer, min=1, max=100

Number of billing cycles the new contract term should run for, on contract renewal. The default value is the same as billing_cycles or a custom value depending on the site configuration .

status

required, enumerated string

Current state of the subscription.

Enum Values

future

The subscription is scheduled to start at a future date.

in_trial

The subscription is in trial.

active

The subscription is active and will be charged for automatically based on the items in it.

non_renewing

The subscription will be canceled at the end of the current term.

paused

The subscription is paused. The subscription will not renew while in this state.

cancelled

The subscription has been canceled and is no longer in service.

transferred

The subscription has been transferred to another business entity within the organization.

current_term_end

optional, timestamp(UTC) in seconds

End of the current billing term. Subscription is renewed immediately after this. If not given, this will be calculated based on plan billing cycle.

Note:

For subscription status: non_renewing, active, and paused, current_term_end is required.

current_term_start

optional, timestamp(UTC) in seconds

Start of the current billing period of the subscription. This is required when the subscription status is paused. When the status is active or non_renewing , it defaults to the current time.

trial_start

optional, timestamp(UTC) in seconds

Start of the trial period for the subscription. When not passed, it is assumed to be current time. When passed for a future subscription, it implies that the subscription goes into in_trial when it starts.

cancelled_at

optional, timestamp(UTC) in seconds

Time at which subscription was cancelled or is set to be cancelled.

started_at

optional, timestamp(UTC) in seconds

Time at which the subscription was started. Is null for future subscriptions as it is yet to be started.

activated_at

optional, timestamp(UTC) in seconds

The time at which the subscription was activated. A subscription is "activated" when its status changes from any other, to either active or non_renewing.

The following conditions must be satisfied when passing this parameter:

When status is active, non_renewing, or paused, activated_at must be on or after trial_end or started_at. Additionally, activated_at must be on or before current_term_start.
When status is in_trial, activated_at must precede trial_start

Note:

This parameter should not be provided when passing status as future or cancelled.

pause_date

optional, timestamp(UTC) in seconds

When a pause has been scheduled, it is the date/time of scheduled pause. When the subscription is in the paused state, it is the date/time when the subscription was paused.

resume_date

optional, timestamp(UTC) in seconds

For a paused subscription, it is the date/time when the subscription is scheduled to resume. If the pause is for an indefinite period, this value is not returned.

create_current_term_invoice

optional, boolean, default=false

Set as true if you want an invoice to be created for the subscription.

The invoice will be created for the subscription only if it has an active or non_renewing status.
The period of the invoice is from current_term_start to current_term_end.
The invoice will not be generated if the subscription amount is zero dollars (for that period) and 'Hide Zero Value Line Items' option is enabled in site settings.

affiliate_token

optional, string, max chars=250

A unique tracking token.

invoice_notes

optional, string, max chars=2000

A customer-facing note added to all invoices associated with this subscription. This note is one among all the notes displayed on the invoice PDF.

meta_data

optional, jsonobject

A collection of key-value pairs that provides extra information about the subscription.

Note: There's a character limit of 65,535.

Learn more .

customer

Parameters for customer

pass parameters as customer[<param name>]

contract_term

Parameters for contract_term

pass parameters as contract_term[<param name>]

card

Parameters for card

pass parameters as card[<param name>]

payment_method

Parameters for payment_method

pass parameters as payment_method[<param name>]

billing_address

Parameters for billing_address

pass parameters as billing_address[<param name>]

shipping_address

Parameters for shipping_address

pass parameters as shipping_address[<param name>]

transaction

Parameters for transaction

pass parameters as transaction[<param name>]

addons[0..n]

Parameters for addons. Multiple addons can be passed by specifying unique indices.

pass parameters as addons[<param name>][<idx:0..n>]

event_based_addons[0..n]

Parameters for event_based_addons. Multiple event_based_addons can be passed by specifying unique indices.

pass parameters as event_based_addons[<param name>][<idx:0..n>]

charged_event_based_addons[0..n]

Parameters for charged_event_based_addons. Multiple charged_event_based_addons can be passed by specifying unique indices.

pass parameters as charged_event_based_addons[<param name>][<idx:0..n>]

Returns

subscription

Subscription object

Resource object representing subscription

customer

Customer object

Resource object representing customer

card

Card object

Resource object representing card

invoice

Invoice object

Resource object representing invoice