More Tutorials

API Quickstart Guide

twitterlinkedinfacebook

The guidelines provided on this page facilitate the initiation of the integration process with Chargebee APIs. Chargebee's server-side Software Development Kits (SDKs) diminish the effort required to utilize our REST APIs. This commences with minimizing the standardized code that you are required to author.

In this quickstart,

  • You will install a Client library.
  • Make calls to our Product Catalog APIs to define a plan-item price.
  • Create a customer record in Chargebee, associating a test card to it.

Finally, you will make one API call which will create both a subscription and the associated invoice.

Select from one of the following SDK depending on your environment.

Step 1: Get your API key

Once you have signed up for a Chargebee account, a test site is created for you. Obtain a full-access API key from your test site for testing and development. You must be an admin or owner of the Chargebee site to see its API keys. Here’s an example of what the key can look like: test_YkiZnDgc1MWyjlWRNBJgHsKCRSSB8cuDlS.

Step 2: Download and set up the SDK

Install the latest version of the library with:

  npm install chargebee
  # or
  yarn add chargebee
  # or
  pnpm install chargebee

Step 3: Create a customer with a payment method

Create a customer named Acme Eastern and associate a test card payment method with them. Enable auto-collection so that the card is charged automatically when you eventually create a subscription.

  const chargebee = require('chargebee');

  chargebee.configure({
    site: '<YOUR_SITE_NAME>',
    api_key: '<YOUR_API_KEY>',
  });

  try {
    const { customer, card } = await chargebee.customer
      .create({
        id: 'acme-east',
        company: 'Acme Eastern',
        auto_collection: 'on',
        card : {
          number : "4111111111111111",
          expiry_month : 12,
          expiry_year : 2028,
          cvv : "100"
        }
      })
      .request();
  } catch (err) {
    // handle error
  }

Step 4: Create an item family

Create an item family. This defines a group of products and services that you sell. In our example, it is Cloud Storage.

  const chargebee = require('chargebee');

  chargebee.configure({
    site: '<YOUR_SITE_NAME>',
    api_key: '<YOUR_API_KEY>',
  });

  try {
    const { item_family } = await chargebee.item_family
      .create({
        id: 'cloud-storage',
        name: 'Cloud Storage'
      })
      .request();
  } catch (err) {
    // handle error
  }

Step 5: Create an item

Now, create an item. An item defines one of the products within the Cloud Storage item family. Set its type to plan. An item of type plan is required to create a subscription. Let’s call it Silver Plan.

  const chargebee = require('chargebee');

  chargebee.configure({
    site: '<YOUR_SITE_NAME>',
    api_key: '<YOUR_API_KEY>',
  });

  try {
    const { item } = await chargebee.item
      .create({
        id : "silver-plan",
        name : "Silver Plan",
        type : "plan",
        item_family_id: 'cloud-storage'
      })
      .request();
  } catch (err) {
    // handle error
  }

Step 6: Create an item price

Item prices define the pricing for an item. They specify how often the customer is charged in a subscription, how much they’re charged, and what currency. Let’s create an item price for Silver Plan, which charges $500 every month, and call it Silver USD monthly.

  const chargebee = require('chargebee');

  chargebee.configure({
    site: '<YOUR_SITE_NAME>',
    api_key: '<YOUR_API_KEY>',
  });

  try {
    const { item } = await chargebee.item_price
      .create({
        id : "silver-plan-USD-monthly",
        item_id : "silver-plan",
        name : "silver USD monthly",
        pricing_model : "per_unit",
        price : 50000,
        external_name : "silver USD",
        period_unit : "month",
        period : 1
      })
      .request();
  } catch (err) {
    // handle error
  }

Step 7: Create a subscription

We’re now ready to create a subscription for Acme Eastern. Let’s subscribe the customer to 5 units of Silver USD monthly.

  const chargebee = require('chargebee');

  chargebee.configure({
    site: '<YOUR_SITE_NAME>',
    api_key: '<YOUR_API_KEY>',
  });

  try {
    const { item } = await chargebee.subscription
      .create_with_items("acme-east", {
        subscription_items: [
          {
            item_price_id: "silver-plan-USD-monthly",
            quantity: 5
          }
        ]
      })
      .request();
  } catch (err) {
    // handle error
  }

The endpoint responds with a payload that carries the following objects:

  • The subscription that was created.
  • The customer for whom it was created.
  • The details of the card that was charged.
  • The invoice that was generated for the charge.
  • A sample response is provided below:
  {
    "subscription": {
      "id": "16Bjl4Sa1y72u3Ppw",
      "billing_period": 1,
      "billing_period_unit": "month",
      "customer_id": "acme-east",
      "status": "active",
      "current_term_start": 1623416481,
      "current_term_end": 1626008481,
      "next_billing_at": 1626008481,
      "created_at": 1623416481,
      "started_at": 1623416481,
      "activated_at": 1623416481,
      "updated_at": 1623416481,
      "has_scheduled_changes": false,
      "resource_version": 1623416481565,
      "deleted": false,
      "object": "subscription",
      "currency_code": "USD",
      "subscription_items": [
        {
          "item_price_id": "silver-plan-USD-monthly",
          "item_type": "plan",
          "quantity": 5,
          "unit_price": 50000,
          "amount": 250000,
          "free_quantity": 0,
          "object": "subscription_item"
        }
      ],
      "due_invoices_count": 0,
      "mrr": 0
    },
    "customer": {
      "id": "acme-east",
      "auto_collection": "on",
      "net_term_days": 0,
      "allow_direct_debit": false,
      "created_at": 1623294986,
      "taxability": "taxable",
      "updated_at": 1623294986,
      "pii_cleared": "active",
      "resource_version": 1623294986772,
      "deleted": false,
      "object": "customer",
      "card_status": "valid",
      "promotional_credits": 0,
      "refundable_credits": 0,
      "excess_payments": 0,
      "unbilled_charges": 0,
      "preferred_currency_code": "USD",
      "primary_payment_source_id": "pm_AzyuEASZtkKjx1wxQ",
      "payment_method": {
        "object": "payment_method",
        "type": "card",
        "reference_id": "tok_AzyuEASZtkKjl1wxP",
        "gateway": "chargebee",
        "gateway_account_id": "gw_AzZhVYSZlfWhVmD9",
        "status": "valid"
      }
    },
    "card": {
      "status": "valid",
      "gateway": "chargebee",
      "gateway_account_id": "gw_AzZhVYSZlfWhVmD9",
      "iin": "411111",
      "last4": "1111",
      "card_type": "visa",
      "funding_type": "credit",
      "expiry_month": 12,
      "expiry_year": 2022,
      "created_at": 1623294986,
      "updated_at": 1623294986,
      "resource_version": 1623294986774,
      "object": "card",
      "masked_number": "************1111",
      "customer_id": "acme-east",
      "payment_source_id": "pm_AzyuEASZtkKjx1wxQ"
    },
    "invoice": {
      "id": "12",
      "customer_id": "acme-east",
      "subscription_id": "16Bjl4Sa1y72u3Ppw",
      "recurring": true,
      "status": "paid",
      "price_type": "tax_exclusive",
      "date": 1623416481,
      "due_date": 1623416481,
      "net_term_days": 0,
      "exchange_rate": 1.0,
      "total": 250000,
      "amount_paid": 250000,
      "amount_adjusted": 0,
      "write_off_amount": 0,
      "credits_applied": 0,
      "amount_due": 0,
      "paid_at": 1623416481,
      "updated_at": 1623416481,
      "resource_version": 1623416481559,
      "deleted": false,
      "object": "invoice",
      "first_invoice": true,
      "amount_to_collect": 0,
      "round_off_amount": 0,
      "new_sales_amount": 250000,
      "has_advance_charges": false,
      "currency_code": "USD",
      "base_currency_code": "USD",
      "is_gifted": false,
      "term_finalized": true,
      "tax": 0,
      "line_items": [
        {
          "id": "li_16Bjl4Sa1y73T3Ppy",
          "date_from": 1623416481,
          "date_to": 1626008481,
          "unit_amount": 50000,
          "quantity": 5,
          "amount": 250000,
          "pricing_model": "per_unit",
          "is_taxed": false,
          "tax_amount": 0,
          "object": "line_item",
          "subscription_id": "16Bjl4Sa1y72u3Ppw",
          "customer_id": "acme-east",
          "description": "Silver USD",
          "entity_type": "plan_item_price",
          "entity_id": "silver-plan-USD-monthly",
          "tax_exempt_reason": "tax_not_configured",
          "discount_amount": 0,
          "item_level_discount_amount": 0
        }
      ],
      "sub_total": 250000,
      "linked_payments": [
        {
          "txn_id": "txn_16Bjl4Sa1y74A3Ppz",
          "applied_amount": 250000,
          "applied_at": 1623416481,
          "txn_status": "success",
          "txn_date": 1623416481,
          "txn_amount": 250000
        }
      ],
      "dunning_attempts": [],
      "applied_credits": [],
      "adjustment_credit_notes": [],
      "issued_credit_notes": [],
      "linked_orders": []
    }
  }

What to do next?

You have successfully created a subscription.

Now, you can explore more subscription and billing use cases by checking out our help docs, guides and developer resources.

Was this tutorial helpful ?
Need more help?

We're always happy to help you with any questions you might have!

support@chargebee.com

In this Page