# Create a subscription

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


[Idempotency Supported](/docs/api/v1/idempotency)

**Note:** This operation optionally supports 3DS verification flow. To achieve the same, create the [Payment Intent](/docs/api/getting-started) and pass it as input parameter to this API.

Creates a new subscription along with the customer. You can attach a plan, plan quantity, one or more addons and coupon while creating this subscription.

#### Future Subscriptions[](#future-subscriptions)

If the **start\_date** is specified, the subscription will be created in 'future' state (.ie, instead of starting immediately it will be scheduled to start at the specified 'start\_date'). Besides if 'trial' is specified (plan configuration or specified explicitly using trial\_end), the subscription will go into 'trial' state when it starts. Otherwise it will directly become 'active' when it starts.

#### Trial Period[](#trial-period)

If the plan has trial period or if the trial\_end is specified explicitly, the subscription will be created in 'in\_trial' state.

If the card details are passed, it is not charged until the end of the trial period. Incase you need to verify the card you could enable the ['card verification option'](https://www.chargebee.com/docs/cards.html#card-verification) in the gateway settings.

#### Invoice[](#invoice)

If the plan does not have a trial period and if any of the recurring items has charges, then a invoice would be raised immediately. If 'auto\_collection' is turned 'on', then card attributes are mandatory and subscription will be created only if the payment was successful.

#### Card details[](#card-details)

Passing card details to this API involves PCI liability at your end as sensitive card information passes through your servers. If you wish to avoid that, you can use one of the following integration methodologies if applicable

-   If you are using Stripe gateway, you can use [Stripe.js](https://stripe.com/docs/stripe.js) with your checkout form. Take a look at this [Stripe tutorial](https://stripe.com/docs/payments/accept-a-payment-charges) for more details.
-   If you are using Braintree gateway, you can use [Braintree.js](https://www.braintreepayments.com/docs/javascript) with your checkout form. Please refer this [tutorial](https://www.chargebee.com/tutorials/braintree-js-example.html) for more details. You can also use our [Hosted Pages](https://www.chargebee.com/docs/billing/2.0/hosted-capabilities/hosted-capabilities) based integration.

#### Billing Address[](#billing-address)

-   The Billing Address is significant especially when EU VAT or Customized Tax options are in use, because tax calculations will be based on this address.
-   In the case of EU VAT, for customers without Billing Address, taxes will not be included.
-   In the case of Customized Tax option, the billing address will be used to determine tax if shipping address is not available for the customer. If both addresses are not available, tax calculation will not happen.

**Note:** For the sites created before 1st Mar 2014, customer's billing address and 'vat\_number' will be replaced automatically whenever the associated card gets updated. i.e existing values for billing address and 'vat\_number' will be cleared and the new values will be set. This behaviour is changed now - The VAT number should always be passed along billing address and not with card address. Both the addresses have to be dealt separately.

Billing Address attributes shall be explicitly passed for customers paying offline(Cash, Check, Bank Transfer etc).

#### Shipping Address[](#shipping-address)

The Shipping Address is significant for the Customized Tax option, because tax calculations will be based on this address. For customers without Shipping Address, Billing Address details will be used to calculate taxes. If neither of the addresses are available for a customer, taxes will not be calculated for him/her.

#### Related Tutorials[](#related-tutorials)

-   [Check out this tutorial to create trial signup with custom fields.](https://www.chargebee.com/tutorials/custom-fields-recurring-billing-example.html)
-   [Learn how to implement a in-app checkout flow that allows your customers to select addons and apply coupons. Estimate API is used to dynamically calculate the order summary shown to the customer.](https://www.chargebee.com/tutorials/in-app-checkout-page-using-estimate-api-example.html)

## Sample Request

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v1/subscriptions \
     -u {site_api_key}:\
     -d plan_id="no_trial" \
     -d "customer[first_name]"="John" \
     -d "customer[last_name]"="Doe" \
     -d "customer[email]"="john@user.com" \
     -d "billing_address[first_name]"="John" \
     -d "billing_address[last_name]"="Doe" \
     -d "billing_address[line1]"="PO Box 9999" \
     -d "billing_address[city]"="Walnut" \
     -d "billing_address[state]"="California" \
     -d "billing_address[zip]"="91789" \
     -d "billing_address[country]"="US" \
     -d "customer[auto_collection]"="OFF"
```

#### .NET

```dotnet
using ChargeBee.Api;
using ChargeBee.Models;
using ChargeBee.Models.Enums;

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Subscription.Create()
		.PlanId("no_trial")
		.CustomerFirstName("John")
		.CustomerLastName("Doe")
		.CustomerEmail("john@user.com")
		.CustomerAutoCollection(AutoCollectionEnum.Off)
		.BillingAddressFirstName("John")
		.BillingAddressLastName("Doe")
		.BillingAddressLine1("PO Box 9999")
		.BillingAddressCity("Walnut")
		.BillingAddressState("California")
		.BillingAddressZip("91789")
		.BillingAddressCountry("US")
		.Request();

Subscription subscription = result.Subscription;
Customer customer = result.Customer;
Card card = result.Card;
Invoice invoice = result.Invoice;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    subscriptionAction "github.com/chargebee/chargebee-go/v3/actions/subscription"
    "github.com/chargebee/chargebee-go/v3/models/subscription"
    enum "github.com/chargebee/chargebee-go/v3/enum"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := subscriptionAction.Create(&subscription.CreateRequestParams{
        PlanId : "no_trial",
        Customer : &subscription.CreateCustomerParams{
            FirstName : "John",
            LastName : "Doe",
            Email : "john@user.com",
            AutoCollection : enum.AutoCollectionOff,
        },
        BillingAddress : &subscription.CreateBillingAddressParams{
            FirstName : "John",
            LastName : "Doe",
            Line1 : "PO Box 9999",
            City : "Walnut",
            State : "California",
            Zip : "91789",
            Country : "US",
        },
    }).Request()
    if err != nil {
        fmt.Println(err)
    } else {
        Subscription := res.Subscription
        Customer := res.Customer
        Card := res.Card
        Invoice := res.Invoice
    }
}
```

#### Go

```go
package main

import (
  "fmt"
  "github.com/chargebee/chargebee-go/v4"
)

func main() {
  config := &chargebee.ClientConfig{
    SiteName: "{site}",
    ApiKey: "{site_api_key}",
  }    
  client := chargebee.NewClient(config)
  req := &chargebee.SubscriptionCreateRequest{
    PlanId : "no_trial",
    Customer : &chargebee.SubscriptionCreateCustomer{
        FirstName : "John",
        LastName : "Doe",
        Email : "john@user.com",
        AutoCollection : chargebee.AutoCollectionOff,
    },
    BillingAddress : &chargebee.SubscriptionCreateBillingAddress{
        FirstName : "John",
        LastName : "Doe",
        Line1 : "PO Box 9999",
        City : "Walnut",
        State : "California",
        Zip : "91789",
        Country : "US",
    },
}
  res, err := client.Subscription.Create(req)
      if err != nil {
        fmt.Println(err)
    } else {
        Subscription := res.Subscription
        Customer := res.Customer
        Card := res.Card
        Invoice := res.Invoice
    }
}
```

#### Java

```java
import com.chargebee.*;
import com.chargebee.ListResult;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
import java.io.IOException;

public class Sample {

    public static void main(String args[]) throws IOException, Exception {
        Environment.configure("{site}", "{site_api_key}");
        Result result = Subscription.create()
            .planId("no_trial")
            .customerFirstName("John")
            .customerLastName("Doe")
            .customerEmail("john@user.com")
            .customerAutoCollection(AutoCollection.OFF)
            .billingAddressFirstName("John")
            .billingAddressLastName("Doe")
            .billingAddressLine1("PO Box 9999")
            .billingAddressCity("Walnut")
            .billingAddressState("California")
            .billingAddressZip("91789")
            .billingAddressCountry("US")
            .request();

        Subscription subscription = result.subscription();
        Customer customer = result.customer();
        Card card = result.card();
        Invoice invoice = result.invoice();
    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.card.Card;
import com.chargebee.v4.models.customer.Customer;
import com.chargebee.v4.models.invoice.Invoice;
import com.chargebee.v4.models.subscription.Subscription;
import com.chargebee.v4.models.subscription.params.SubscriptionCreateParams;
import com.chargebee.v4.models.subscription.responses.SubscriptionCreateResponse;

public class SubscriptionCreate {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        SubscriptionCreateParams.CustomerParams customerParams =
            SubscriptionCreateParams.CustomerParams.builder()
                .firstName("John")
                .lastName("Doe")
                .email("john@user.com")
                .autoCollection(SubscriptionCreateParams.CustomerParams.AutoCollection.OFF)
                .build();

        SubscriptionCreateParams.BillingAddressParams billingAddressParams =
            SubscriptionCreateParams.BillingAddressParams.builder()
                .firstName("John")
                .lastName("Doe")
                .line1("PO Box 9999")
                .city("Walnut")
                .state("California")
                .zip("91789")
                .country("US")
                .build();

        SubscriptionCreateParams params = SubscriptionCreateParams.builder()
            .planId("no_trial")
            .customer(customerParams)
            .billingAddress(billingAddressParams)
            .build();

        SubscriptionCreateResponse response = client.subscriptions().create(params);

        Subscription subscription = response.getSubscription();
        Customer customer = response.getCustomer();
        Card card = response.getCard();
        Invoice invoice = response.getInvoice();
    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

const chargebee = new Chargebee({
    site: "{site}",
    apiKey: "{site_api_key}",
});

try {
    const result = await chargebee.subscription.create({
        plan_id: "no_trial",
        customer: {
            first_name: "John",
            last_name: "Doe",
            email: "john@user.com",
            auto_collection: "off"
        },
        billing_address: {
            first_name: "John",
            last_name: "Doe",
            line1: "PO Box 9999",
            city: "Walnut",
            state: "California",
            zip: 91789,
            country: "US"
        }
    });

    console.log(result);
    const subscription = result.subscription;
    const customer = result.customer;
    const card = result.card;
    const invoice = result.invoice;
} catch (err) {
    console.log(err);
}
```

#### PHP

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->subscription()->create([
    "plan_id" => "no_trial",
    "customer" => [
        "first_name" => "John",
        "last_name" => "Doe",
        "email" => "john@user.com",
        "auto_collection" => "off"
    ],
    "billing_address" => [
        "first_name" => "John",
        "last_name" => "Doe",
        "line1" => "PO Box 9999",
        "city" => "Walnut",
        "state" => "California",
        "zip" => "91789",
        "country" => "US"
    ]
]);
$subscription = $result->subscription;
$customer = $result->customer;
$card = $result->card;
$invoice = $result->invoice;
```

#### Python

```python
import chargebee
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.Subscription.create(
    cb_client.Subscription.CreateParams(
        plan_id="no_trial",
        customer=cb_client.Subscription.CreateCustomerParams(
            first_name="John",
            last_name="Doe",
            email="john@user.com",
            auto_collection=chargebee.AutoCollection.OFF
        ),
        billing_address=cb_client.Subscription.CreateBillingAddressParams(
            first_name="John",
            last_name="Doe",
            line1="PO Box 9999",
            city="Walnut",
            state="California",
            zip="91789",
            country="US"
        )
    )
)
subscription = response.subscription
customer = response.customer
card = response.card
invoice = response.invoice
```

#### Ruby

```ruby
require 'chargebee'

ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")

result = ChargeBee::Subscription.create({
  :plan_id => "no_trial",
  :customer => {
    :first_name => "John",
    :last_name => "Doe",
    :email => "john@user.com",
    :auto_collection => "OFF"
  },
  :billing_address => {
    :first_name => "John",
    :last_name => "Doe",
    :line1 => "PO Box 9999",
    :city => "Walnut",
    :state => "California",
    :zip => "91789",
    :country => "US"
  }
})

subscription = result.subscription
customer = result.customer
card = result.card
invoice = result.invoice
```

## Sample Response

```json
{
  "customer": {
    "account_credits": 0,
    "allow_direct_debit": false,
    "auto_collection": "off",
    "billing_address": {
      "city": "Walnut",
      "country": "US",
      "first_name": "John",
      "last_name": "Doe",
      "line1": "PO Box 9999",
      "object": "billing_address",
      "state": "California",
      "state_code": "CA",
      "zip": "91789"
    },
    "card_status": "no_card",
    "created_at": 1517506669,
    "email": "john@user.com",
    "excess_payments": 0,
    "first_name": "John",
    "id": "__test__5SK0bLNFRFuBv6r6j",
    "last_name": "Doe",
    "object": "customer",
    "refundable_credits": 0,
    "taxability": "taxable"
  },
  "invoice": {
    "amount": 895,
    "amount_adjusted": 0,
    "amount_due": 895,
    "amount_paid": 0,
    "billing_address": {
      "city": "Walnut",
      "country": "US",
      "first_name": "John",
      "last_name": "Doe",
      "line1": "PO Box 9999",
      "object": "billing_address",
      "state": "California",
      "state_code": "CA",
      "zip": "91789"
    },
    "credits_applied": 0,
    "currency_code": "USD",
    "customer_id": "__test__5SK0bLNFRFuBv6r6j",
    "end_date": 1517506669,
    "first_invoice": true,
    "id": "__demo_inv__7",
    "line_items": [
      {
        "amount": 895,
        "date_from": 1517506669,
        "date_to": 1519925869,
        "description": "No Trial",
        "entity_id": "no_trial",
        "entity_type": "plan",
        "is_taxed": false,
        "object": "line_item",
        "quantity": 1,
        "tax": 0,
        "type": "charge",
        "unit_amount": 895
      },
      {..}
    ],
    "linked_orders": {},
    "linked_transactions": {},
    "object": "invoice",
    "price_type": "tax_exclusive",
    "recurring": true,
    "start_date": 1517506669,
    "status": "payment_due",
    "sub_total": 895,
    "subscription_id": "__test__5SK0bLNFRFuBv6r6j",
    "tax": 0
  },
  "subscription": {
    "activated_at": 1517506669,
    "created_at": 1517506669,
    "current_term_end": 1519925869,
    "current_term_start": 1517506669,
    "due_invoices_count": 1,
    "due_since": 1517506669,
    "has_scheduled_changes": false,
    "id": "__test__5SK0bLNFRFuBv6r6j",
    "object": "subscription",
    "plan_id": "no_trial",
    "plan_quantity": 1,
    "started_at": 1517506669,
    "status": "active",
    "total_dues": 895
  }
}
```

## URL Format

**POST** https://[site].chargebee.com/api/v1/subscriptions

## Input Parameters

- `id` (optional, string, max chars=50)
  A unique and immutable identifier for the subscription. If not provided, it is autogenerated.

- `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.

- `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. If not provided, the subscription starts immediately. You can provide a value in the past as well. This is called backdating the subscription creation and is done when the subscription has already been provisioned but its billing has been delayed. Backdating is allowed only when the following prerequisites are met:
  
  -   Backdating is enabled for subscription creation operations.
  -   The current day of the month does not exceed the limit set in Chargebee for backdating such operations. This day is typically the day of the month by which the accounting for the previous month must be closed.
  -   The date is not more than duration X into the past, where X is the billing period of the plan. For example, if the period of the plan in the subscription is 2 months and today is 14th April, `start_date` cannot be earlier than 14th February. .

- `coupon` (optional, string, max chars=100)
  The id of the coupon. For validating the coupon code provided by the user , use the following codes in combination with the param attribute in the error response.
  
  -   **resource\_not\_found :** Returned if the coupon is not present.
  -   **resource\_limit\_exhausted :** Returned if the coupon has expired or the maximum redemption for the coupon has already been reached.
  -   **invalid\_request :** Returned if the coupon is not applicable for the particular plan/addon.

- `po_number` (optional, string, max chars=100)
  Purchase order number for this subscription.

- `affiliate_token` (optional, string, max chars=250)
  A unique tracking token.

- `created_from_ip` (optional, string, max chars=50)
  The IP address of the user. Used primarly in Refersion integration. Refersion uses this field to track/log affiliate subscription.

- `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](/docs/api/invoices/invoice-object#notes) displayed on the invoice PDF.

- `meta_data` (optional, jsonobject)
  A set of key-value pairs stored as additional information for the subscription. [Learn more](/docs/api/v1/subscriptions) .

- `customer` (optional, string)
  Parameters for customer
  - `id` (optional, string, max chars=50)
    The unique ID of the customer for which this `hosted_page` should be created. When not provided, a new customer is created with the ID set to the value provided for `subscription[id]`. If `subscription[id]` is unavailable, then the customer ID is autogenerated.
  - `email` (optional, string, max chars=70)
    Email of the customer. Configured email notifications will be sent to this email.
  - `first_name` (optional, string, max chars=150)
    First name of the customer
  - `last_name` (optional, string, max chars=150)
    Last name of the customer
  - `company` (optional, string, max chars=250)
    Company name of the customer.
  - `phone` (optional, string, max chars=50)
    Phone number of the customer
  - `taxability` (optional, enumerated string, default=taxable)
    Specifies if the customer is liable for tax
    Possible enum values:
      - `taxable`
        Computes tax for the customer based on the [site configuration](https://www.chargebee.com/docs/tax.html). In some cases, depending on the region, shipping\_address is needed. If not provided, then billing\_address is used to compute tax. If that's not available either, the tax is taken as zero.
      - `exempt`
        -   Customer is exempted from tax. When using Chargebee's native [Taxes](https://www.chargebee.com/docs/tax.html) feature or when using the [TaxJar integration](https://www.chargebee.com/docs/taxjar.html), no other action is needed.
        -   However, when using our [Avalara integration](https://www.chargebee.com/docs/avalara.html), optionally, specify `entity_code` or `exempt_number` attributes if you use Chargebee's [AvaTax for Sales](https://www.chargebee.com/docs/avalara.html#configuring-tax-exemption) or specify `exemption_details` attribute if you use [Chargebee's AvaTax for Communications](https://www.chargebee.com/docs/avatax-for-communication.html) integration. Tax may still be applied by Avalara for certain values of `entity_code`/`exempt_number`/`exemption_details` based on the state/region/province of the taxable address.
  - `auto_collection` (optional, enumerated string, default=on)
    Whether payments needs to be collected automatically for this customer
    Possible enum values:
      - `on`
        Whenever an invoice is created, an automatic attempt to charge the customer's payment method is made.
      - `off`
        Automatic collection of charges will not be made. All payments must be recorded offline.
  - `allow_direct_debit` (optional, boolean, default=false)
    Whether the customer can pay via Direct Debit
  - `vat_number` (optional, string, max chars=20)
    The VAT/tax registration number for the customer. For customers with `[billing_address](/docs/api/customers/customer-object#billing_address)`
    
    `country` as `XI` (which is **United Kingdom - Northern Ireland** ), the first two characters of the [full VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) can be overridden by setting `[vat_number_prefix](/docs/api/customers/customer-object#vat_number_prefix)` .

- `card` (optional, enumerated string)
  Parameters for card
  - `gateway` (optional, enumerated string)
    Name of the gateway this payment source is stored with.
    Possible enum values:
      - `chargebee`
        Chargebee test gateway.
      - `stripe`
        Stripe is a payment gateway.
      - `braintree`
        Braintree is a payment gateway.
      - `authorize_net`
        Authorize.net is a payment gateway
      - `paypal_pro`
        PayPal Pro Account is a payment gateway.
      - `pin`
        Pin is a payment gateway
      - `eway`
        eWAY Account is a payment gateway.
      - `eway_rapid`
        eWAY Rapid is a payment gateway.
      - `worldpay`
        WorldPay is a payment gateway
      - `balanced_payments`
        Balanced is a payment gateway
      - `beanstream`
        Bambora(formerly known as Beanstream) is a payment gateway.
      - `bluepay`
        BluePay is a payment gateway.
      - `elavon`
        Elavon Virtual Merchant is a payment solution.
      - `first_data_global`
        First Data Global Gateway Virtual Terminal Account
      - `hdfc`
        HDFC Account is a payment gateway.
      - `migs`
        MasterCard Internet Gateway Service payment gateway.
      - `nmi`
        NMI is a payment gateway.
      - `ogone`
        Ingenico ePayments (formerly known as Ogone) is a payment gateway.
      - `paymill`
        PAYMILL is a payment gateway.
      - `paypal_payflow_pro`
        PayPal Payflow Pro is a payment gateway.
      - `sage_pay`
        Sage Pay is a payment gateway.
      - `tco`
        2Checkout is a payment gateway.
      - `wirecard`
        WireCard Account is a payment service provider.
  - `tmp_token` (optional, string, max chars=300)
    The single-use card token returned by vaults like Stripe/Braintree which act as a substitute for your card details. Before calling this API, you should have submitted your card details to the gateway and gotten this token in return. **Note:** Supported only for Stripe, Braintree and Authorize.Net. If this value is specified, there is no need to specify other card details (like number, cvv, etc).
  - `first_name` (optional, string, max chars=50)
    Cardholder's first name
  - `last_name` (optional, string, max chars=50)
    Cardholder's last name
  - `number` (required if card provided, string, max chars=1500)
    The credit card number without any format. If you are using [Braintree.js](https://developer.paypal.com/braintree/docs/guides/client-sdk/setup/javascript/v2#getting-braintree.js) , you can specify the Braintree encrypted card number here.
  - `expiry_month` (required if card provided, integer, min=1, max=12)
    Card expiry month.
  - `expiry_year` (required if card provided, integer)
    Card expiry year.
  - `cvv` (optional, string, max chars=520)
    The card verification value (CVV). If you are using [Braintree.js](https://developer.paypal.com/braintree/docs/guides/client-sdk/setup/javascript/v2#getting-braintree.js) , you can specify the Braintree encrypted CVV here.
  - `billing_addr1` (optional, string, max chars=150)
    Address line 1, as available in card billing address.
  - `billing_addr2` (optional, string, max chars=150)
    Address line 2, as available in card billing address.
  - `billing_city` (optional, string, max chars=50)
    City, as available in card billing address.
  - `billing_state_code` (optional, string, max chars=50)
    The [ISO 3166-2 state/province code](https://www.iso.org/obp/ui/#search/code) without the country prefix. Currently supported for USA, Canada, India and UAE. For instance, for Arizona (USA), set `billing_state_code` as `AZ` (not `US-AZ` ). For Tamil Nadu (India), set as `TN` (not `IN-TN` ). For British Columbia (Canada), set as `BC` (not `CA-BC` ). For Dubai (UAE), set as `DU` (not `AE-DU` ).
  - `billing_state` (optional, string, max chars=50)
    The state/province name. Is set by Chargebee automatically for US, Canada, India and UAE, if `billing_state_code` is provided.
  - `billing_zip` (optional, string, max chars=20)
    Postal or Zip code, as available in card billing address.
  - `billing_country` (optional, string, max chars=50)
    The billing address country of the customer. Must be one of [ISO 3166 alpha-2 country code](https://www.iso.org/iso-3166-country-codes.html) .
    
    **Note**: If you enter an invalid country code, the system will return an error.
    
    **Brexit**
    
    If you have enabled [EU VAT](https://www.chargebee.com/docs/eu-vat.html) in 2021 or later, or have [manually enable](https://www.chargebee.com/docs/brexit.html#what-needs-to-be-done-in-chargebee) the Brexit configuration, then `XI` (the code for **United Kingdom - Northern Ireland**) is available as an option.
  - `ip_address` (optional, string, max chars=50)
    The IP address of the customer. Used primarily for referral integration and EU VAT validation.

- `payment_method` (optional, enumerated string)
  Parameters for payment\_method
  - `type` (optional, enumerated string)
    The type of payment method. For more details refer [Update payment method for a customer](/docs/api/customers/update-payment-method-for-a-customer) API under Customer resource.
    Possible enum values:
      - `card`
        Card based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.
      - `paypal_express_checkout`
        Payments made via PayPal Express Checkout.
      - `amazon_payments`
        Payments made via Amazon Payments.
      - `direct_debit`
        Represents bank account for which the direct debit or ACH agreement/mandate is created.
      - `automated_bank_transfer`
        Represents virtual bank account using which the payment will be done.
  - `gateway` (optional, enumerated string)
    Name of the gateway the payment method is associated with.
    Possible enum values:
      - `stripe`
        Stripe is a payment gateway.
      - `braintree`
        Braintree is a payment gateway.
      - `authorize_net`
        Authorize.net is a payment gateway
      - `paypal_pro`
        PayPal Pro Account is a payment gateway.
      - `pin`
        Pin is a payment gateway
      - `eway`
        eWAY Account is a payment gateway.
      - `eway_rapid`
        eWAY Rapid is a payment gateway.
      - `worldpay`
        WorldPay is a payment gateway
      - `balanced_payments`
        Balanced is a payment gateway
      - `beanstream`
        Bambora(formerly known as Beanstream) is a payment gateway.
      - `bluepay`
        BluePay is a payment gateway.
      - `elavon`
        Elavon Virtual Merchant is a payment solution.
      - `first_data_global`
        First Data Global Gateway Virtual Terminal Account
      - `hdfc`
        HDFC Account is a payment gateway.
      - `migs`
        MasterCard Internet Gateway Service payment gateway.
      - `nmi`
        NMI is a payment gateway.
      - `ogone`
        Ingenico ePayments (formerly known as Ogone) is a payment gateway.
      - `paymill`
        PAYMILL is a payment gateway.
      - `paypal_payflow_pro`
        PayPal Payflow Pro is a payment gateway.
      - `sage_pay`
        Sage Pay is a payment gateway.
      - `tco`
        2Checkout is a payment gateway.
      - `wirecard`
        WireCard Account is a payment service provider.
  - `reference_id` (optional, string, max chars=200)
    The reference id. In the case of Amazon and Paypal this will be the _billing agreement id_. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource. **Note:** This is not the one time temporary token provided by gateways like Stripe.
    
    For more details refer [Update payment method for a customer](/docs/api/customers/update-payment-method-for-a-customer) API under Customer resource.

- `payment_intent` (optional, string)
  Parameters for payment\_intent
  - `id` (optional, string, max chars=150)
    Identifier for PaymentIntent generated by Chargebee.js. Applicable only when you are using Chargebee.js for completing the 3DS flow. The PaymentIntent should be in 'authorized' state while passing it here. You need not pass other PaymentIntent parameters if this is passed.
  - `gateway_account_id` (required if payment intent token provided, string, max chars=50)
    The gateway account used for performing the 3DS flow.
  - `gw_token` (optional, string, max chars=65k)
    Identifier for 3DS transaction/verification object at the gateway. Can be passed only after successfully completing the 3DS flow. Refer [3DS implementation in Chargebee](/docs/api/3ds_card_payments) to find out the gateway-specific gw\_token format. Applicable when you are using gateway APIs directly for completing the 3DS flow.
  - `reference_id` (optional, string, max chars=65k)
    Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.

- `billing_address` (optional, string)
  Parameters for billing\_address
  - `first_name` (optional, string, max chars=150)
    The first name of the billing contact.
  - `last_name` (optional, string, max chars=150)
    The last name of the billing contact.
  - `email` (optional, string, max chars=70)
    The email address.
  - `company` (optional, string, max chars=250)
    The company name.
  - `phone` (optional, string, max chars=50)
    The phone number.
  - `line1` (optional, string, max chars=150)
    Address line 1
  - `line2` (optional, string, max chars=150)
    Address line 2
  - `line3` (optional, string, max chars=150)
    Address line 3
  - `city` (optional, string, max chars=50)
    The name of the city.
  - `state_code` (optional, string, max chars=50)
    The [ISO 3166-2 state/province code](https://www.iso.org/obp/ui/#search/code) without the country prefix. Currently supported for USA, Canada, India and UAE. For instance, for Arizona (USA), set `state_code` as `AZ` (not `US-AZ` ). For Tamil Nadu (India), set as `TN` (not `IN-TN` ). For British Columbia (Canada), set as `BC` (not `CA-BC` ). For Dubai (UAE), set as `DU` (not `AE-DU` ).
  - `state` (optional, string, max chars=50)
    The state/province name. Is set by Chargebee automatically for US, Canada, India and UAE, if `state_code` is provided.
  - `zip` (optional, string, max chars=20)
    Zip or postal code. The number of characters is validated according to the rules [specified here](https://chromium-i18n.appspot.com/ssl-address) .
  - `country` (optional, string, max chars=50)
    The billing address country of the customer. Must be one of [ISO 3166 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) .
    
    **Brexit**
    
    If you have enabled [EU VAT](https://www.chargebee.com/docs/eu-vat.html) in 2021 or later, or have [manually enable](https://www.chargebee.com/docs/brexit.html#what-needs-to-be-done-in-chargebee) the Brexit configuration, then `XI` (the code for **United Kingdom - Northern Ireland**) is available as an option.

- `shipping_address` (optional, string)
  Parameters for shipping\_address
  - `first_name` (optional, string, max chars=150)
    The first name of the contact.
  - `last_name` (optional, string, max chars=150)
    The last name of the contact.
  - `email` (optional, string, max chars=70)
    The email address.
  - `company` (optional, string, max chars=250)
    The company name.
  - `phone` (optional, string, max chars=50)
    The phone number.
  - `line1` (optional, string, max chars=150)
    Address line 1
  - `line2` (optional, string, max chars=150)
    Address line 2
  - `line3` (optional, string, max chars=150)
    Address line 3
  - `city` (optional, string, max chars=50)
    The name of the city.
  - `state_code` (optional, string, max chars=50)
    The [ISO 3166-2 state/province code](https://www.iso.org/obp/ui/#search/code) without the country prefix. Currently supported for USA, Canada, India and UAE. For instance, for Arizona (USA), set `state_code` as `AZ` (not `US-AZ` ). For Tamil Nadu (India), set as `TN` (not `IN-TN` ). For British Columbia (Canada), set as `BC` (not `CA-BC` ). For Dubai (UAE), set as `DU` (not `AE-DU` ).
  - `state` (optional, string, max chars=50)
    The state/province name. Is set by Chargebee automatically for US, Canada, India and UAE, if `state_code` is provided.
  - `zip` (optional, string, max chars=20)
    Zip or postal code. The number of characters is validated according to the rules [specified here](https://chromium-i18n.appspot.com/ssl-address) .
  - `country` (optional, string, max chars=50)
    The billing address country of the customer. Must be one of [ISO 3166 alpha-2 country code](https://www.iso.org/iso-3166-country-codes.html) .
    
    **Note**: If you enter an invalid country code, the system will return an error.
    
    **Brexit**
    
    If you have enabled [EU VAT](https://www.chargebee.com/docs/eu-vat.html) in 2021 or later, or have [manually enable](https://www.chargebee.com/docs/brexit.html#what-needs-to-be-done-in-chargebee) the Brexit configuration, then `XI` (the code for **United Kingdom - Northern Ireland**) is available as an option.

- `addons` (optional, array)
  Parameters for addons
  - `id` (optional, string, max chars=100)
    Identifier of the addon. Multiple addons can be passed.
  - `quantity` (optional, integer)
    Quantity of the addon. Applicable for addons with `pricing_model` other than `flat_fee` .

## 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