Versions Compared

Old Version 7

changes.mady.by.user John M

Saved on

compared with

New Version Current

changes.mady.by.user John M

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Language fixes.

Overview

This document provides information on the changes made to the Chargebee Public APIs for specifying payment terms (Net D) at the subscription level.

The Net D feature helps define the number of days within which a closed invoice must be paid. Net D can be defined at the customer level so that all the customer’s invoices follow this setting.

With this new feature, you can define Net D for any subscription so that all its invoices follow the defined setting.

Change Summary

Subscription resource

New attribute added

Name

Description

net_term_days

Status
colourPurple
titleinteger
Status
colourYellow
titleoptional

The Net D value explicitly set for this subscription. Net D is the number of days within which any invoice raised against for the subscription must be paid. When an invoice is raised, and this value is unavailable, the net_term_days defined at the customer level is considered.

Sample

Expand
Code Block
languagejson
{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "off",
        "card_status": "no_card",
        "created_at": 1612890938,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__8asukSOXe0QYSR",
        "last_name": "Doe",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1612890938000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1612890938
    },
    "subscription": {
        "activated_at": 1612890938,
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1612890938,
        "currency_code": "USD",
        "current_term_end": 1615310138,
        "current_term_start": 1612890938,
        "customer_id": "__test__8asukSOXe0QYSR",
        "deleted": false,
        "due_invoices_count": 1,
        "due_since": 1612890938,
        "has_scheduled_changes": false,
        "id": "__test__8asukSOXe0W3SU",
        "mrr": 0,
        "next_billing_at": 1615310138,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1612890938000,
        "started_at": 1612890938,
        "status": "active",
        "subscription_items": [
            {
                "amount": 1000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 1,
                "unit_price": 1000
            },
            {..}
        ],
        "total_dues": 1100,
        "updated_at": 1612890938,
        "net_term_days": 10
    }
}

Subscription endpoints

Create a subscription for items

Status
colourGreen
titlepost
https://{site}.chargebee.com/api/v2/customers/{customer_id}/subscription_for_items

New body parameter added

Name

Description

net_term_days

Status
colourPurple
titleinteger
Status
colourYellow
titleoptional

Defines Net D for the subscription. Net D is the number of days within which any invoice raised against for the subscription must be paid.

  • If a value is provided: Net D is set explicitly for the subscription to the value provided. The value must be one among those provided defined in the site configuration.

  • If not provided: The attribute is not set and therefore not returned by the API. In this case, when an invoice is raised – whether now or later – the net_term_days defined at the customer level is considered.

Samples

Expand
title200 OK (Creating a subscription and setting its payment terms to Net 7.)
Request
Code Block
languagebash
curl --location --request POST 'https://{site}.chargebee.com/api/v2/customers/__dev__XpbGQ95SyMWBe81r/subscription_for_items' \
--header 'Authorization: Basic dGVzdF9fX2Rldl9fR3RjdUdRV2RLajVaRjdiRmNvNE15amN1d0s2Y2RRdkxjdWJtOjo=' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'subscription_items[item_price_id][0]=plan1-USD-Monthly' \
--data-urlencode 'subscription_items[unit_price][0]=100' \
--data-urlencode 'auto_collection=off' \
--data-urlencode 'net_term_days=7'
Response
Code Block
languagejson
{
	"subscription": {
		"id": "__dev__XpbGQ95SyMjI0G2G",
		"billing_period": 1,
		"billing_period_unit": "month",
		"auto_collection": "off",
		"customer_id": "__dev__XpbGQ95SyMWBe81r",
		"status": "active",
		"current_term_start": 1645710439,
		"current_term_end": 1648129639,
		"next_billing_at": 1648129639,
		"created_at": 1645710439,
		"started_at": 1645710439,
		"activated_at": 1645710439,
		"updated_at": 1645710440,
		"has_scheduled_changes": false,
		"channel": "web",
		"net_term_days": 7,
		"resource_version": 1645710440229,
		"deleted": false,
		"object": "subscription",
		"currency_code": "USD",
		"subscription_items": [{
			"item_price_id": "plan1-USD-Monthly",
			"item_type": "plan",
			"quantity": 1,
			"unit_price": 100,
			"amount": 100,
			"free_quantity": 0,
			"object": "subscription_item"
		}],
		"due_invoices_count": 0,
		"mrr": 0,
		"override_relationship": false
	},
	"customer": {
		"id": "__dev__XpbGQ95SyMWBe81r",
		"first_name": "surya",
		"last_name": "Doe",
		"email": "john@test.com",
		"auto_collection": "off",
		"net_term_days": 7,
		"allow_direct_debit": false,
		"created_at": 1645707316,
		"taxability": "taxable",
		"updated_at": 1645707317,
		"pii_cleared": "active",
		"channel": "web",
		"resource_version": 1645707317008,
		"deleted": false,
		"object": "customer",
		"billing_address": {
			"country": "US",
			"validation_status": "not_validated",
			"object": "billing_address"
		},
		"card_status": "no_card",
		"promotional_credits": 0,
		"refundable_credits": 0,
		"excess_payments": 0,
		"unbilled_charges": 0,
		"preferred_currency_code": "USD"
	},
	"invoice": {
		"id": "7",
		"customer_id": "__dev__XpbGQ95SyMWBe81r",
		"subscription_id": "__dev__XpbGQ95SyMjI0G2G",
		"recurring": true,
		"status": "posted",
		"price_type": "tax_exclusive",
		"date": 1645710439,
		"due_date": 1646315239,
		"net_term_days": 7,
		"exchange_rate": 1.0,
		"total": 100,
		"amount_paid": 0,
		"amount_adjusted": 0,
		"write_off_amount": 0,
		"credits_applied": 0,
		"amount_due": 100,
		"updated_at": 1645710440,
		"resource_version": 1645710440174,
		"deleted": false,
		"object": "invoice",
		"first_invoice": true,
		"amount_to_collect": 100,
		"round_off_amount": 0,
		"new_sales_amount": 100,
		"has_advance_charges": false,
		"currency_code": "USD",
		"base_currency_code": "USD",
		"generated_at": 1645710439,
		"is_gifted": false,
		"term_finalized": true,
		"channel": "web",
		"tax": 0,
		"line_items": [{
			"id": "li___dev__XpbGQ95SyMjI4O2I",
			"date_from": 1645710439,
			"date_to": 1648129639,
			"unit_amount": 100,
			"quantity": 1,
			"amount": 100,
			"pricing_model": "flat_fee",
			"is_taxed": false,
			"tax_amount": 0,
			"object": "line_item",
			"subscription_id": "__dev__XpbGQ95SyMjI0G2G",
			"customer_id": "__dev__XpbGQ95SyMWBe81r",
			"description": "plan1",
			"entity_type": "plan_item_price",
			"entity_id": "plan1-USD-Monthly",
			"tax_exempt_reason": "tax_not_configured",
			"discount_amount": 0,
			"item_level_discount_amount": 0
		}],
		"sub_total": 100,
		"linked_payments": [],
		"applied_credits": [],
		"adjustment_credit_notes": [],
		"issued_credit_notes": [],
		"linked_orders": [],
		"dunning_attempts": [],
		"billing_address": {
			"first_name": "surya",
			"last_name": "Doe",
			"country": "US",
			"validation_status": "not_validated",
			"object": "billing_address"
		}
	}
}

Expand
title400 Bad Request (Creating a subscription and setting its payment terms to an improper value.)
Request
Code Block
languagebash
curl --location --request POST 'https://{site}.chargebee.com/api/v2/customers/__dev__XpbGQ95SyMWBe81r/subscription_for_items' \
--header 'Authorization: Basic dGVzdF9fX2Rldl9fR3RjdUdRV2RLajVaRjdiRmNvNE15amN1d0s2Y2RRdkxjdWJtOjo=' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'subscription_items[item_price_id][0]=plan1-USD-Monthly' \
--data-urlencode 'subscription_items[unit_price][0]=100' \
--data-urlencode 'auto_collection=off' \
--data-urlencode 'net_term_days= -1'

Response
Code Block
languagejson
{
    "message": "net_term_days : The value -1 is invalid",
    "type": "invalid_request",
    "api_error_code": "param_wrong_value",
    "param": "net_term_days",
    "error_code": "param_invalid",
    "error_msg": "The value -1 is invalid",
    "error_param": "net_term_days",
    "http_status_code": 400
}

Update subscription for items

Status
colourGreen
titlepost
https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/update_for_items

New body parameter added

Name

Description

net_term_days

Status
colourPurple
titleinteger
Status
colourYellow
titleoptional

Updates Net D for the subscription. Net D is the number of days within which any invoice raised against for the subscription must be paid.

  • If the value is 0 or a positive integer: Net D is set explicitly for the subscription to the value provided. The value must be one among of those provided defined in the site configuration.

  • If the value is -1: The attribute is reset and therefore not returned by the API. In this case, when an invoice is raised – whether now or later – the net_term_days defined at the customer level is considered.

  • If the value is not provided: The attribute is left unaltered.

Samples

Expand
title200 OK (Updating a subscription and setting its payment terms to Net 7.)
Request
Code Block
languagebash
curl --location --request POST 'https://{site}.chargebee.com/api/v2/subscriptions/__dev__XpbGQ95SyMjeq32U/update_for_items' \
--header 'Authorization: Basic dGVzdF9fX2Rldl9fR3RjdUdRV2RLajVaRjdiRmNvNE15amN1d0s2Y2RRdkxjdWJtOjo=' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'subscription_items[item_price_id][0]=plan1-USD-Monthly' \
--data-urlencode 'subscription_items[unit_price][0]=430' \
--data-urlencode 'net_term_days=7' \
--data-urlencode 'auto_collection=off'
Response
Code Block
languagejson
{
	"subscription": {
		"id": "__dev__XpbGQ95SyMjeq32U",
		"billing_period": 1,
		"billing_period_unit": "month",
		"auto_collection": "off",
		"customer_id": "__dev__XpbGQ95SyMWBe81r",
		"status": "active",
		"current_term_start": 1645710527,
		"current_term_end": 1648129727,
		"next_billing_at": 1648129727,
		"created_at": 1645710527,
		"started_at": 1645710527,
		"activated_at": 1645710527,
		"updated_at": 1645710865,
		"has_scheduled_changes": false,
		"channel": "web",
		"net_term_days": 7,
		"resource_version": 1645710865084,
		"deleted": false,
		"object": "subscription",
		"currency_code": "USD",
		"subscription_items": [{
			"item_price_id": "plan1-USD-Monthly",
			"item_type": "plan",
			"quantity": 1,
			"unit_price": 430,
			"amount": 430,
			"free_quantity": 0,
			"object": "subscription_item"
		}],
		"due_invoices_count": 0,
		"mrr": 430,
		"exchange_rate": 1.0,
		"base_currency_code": "USD",
		"override_relationship": false
	},
	"customer": {
		"id": "__dev__XpbGQ95SyMWBe81r",
		"first_name": "surya",
		"last_name": "Doe",
		"email": "john@test.com",
		"auto_collection": "off",
		"net_term_days": 7,
		"allow_direct_debit": false,
		"created_at": 1645707316,
		"taxability": "taxable",
		"updated_at": 1645707317,
		"pii_cleared": "active",
		"channel": "web",
		"resource_version": 1645707317008,
		"deleted": false,
		"object": "customer",
		"billing_address": {
			"country": "US",
			"validation_status": "not_validated",
			"object": "billing_address"
		},
		"card_status": "no_card",
		"promotional_credits": 0,
		"refundable_credits": 0,
		"excess_payments": 0,
		"unbilled_charges": 0,
		"preferred_currency_code": "USD"
	},
	"credit_notes": []
}

Expand
title200 OK (Updating a subscription and setting its payment terms to follow the setting defined for the customer.)
Request
Code Block
languagebash
curl --location --request POST 'https://{site}.chargebee.com/api/v2/subscriptions/__dev__XpbGQ95SyMjeq32U/update_for_items' \
--header 'Authorization: Basic dGVzdF9fX2Rldl9fR3RjdUdRV2RLajVaRjdiRmNvNE15amN1d0s2Y2RRdkxjdWJtOjo=' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'subscription_items[item_price_id][0]=plan1-USD-Monthly' \
--data-urlencode 'subscription_items[unit_price][0]=430' \
--data-urlencode 'net_term_days=-1' \
--data-urlencode 'auto_collection=off'

Response

Code Block
{
	"subscription": {
		"id": "__dev__XpbGQ95SyMjeq32U",
		"billing_period": 1,
		"billing_period_unit": "month",
		"auto_collection": "off",
		"customer_id": "__dev__XpbGQ95SyMWBe81r",
		"status": "active",
		"current_term_start": 1645710527,
		"current_term_end": 1648129727,
		"next_billing_at": 1648129727,
		"created_at": 1645710527,
		"started_at": 1645710527,
		"activated_at": 1645710527,
		"updated_at": 1645710907,
		"has_scheduled_changes": false,
		"channel": "web",
		"resource_version": 1645710907301,
		"deleted": false,
		"object": "subscription",
		"currency_code": "USD",
		"subscription_items": [{
			"item_price_id": "plan1-USD-Monthly",
			"item_type": "plan",
			"quantity": 1,
			"unit_price": 430,
			"amount": 430,
			"free_quantity": 0,
			"object": "subscription_item"
		}],
		"due_invoices_count": 0,
		"mrr": 430,
		"exchange_rate": 1.0,
		"base_currency_code": "USD",
		"override_relationship": false
	},
	"customer": {
		"id": "__dev__XpbGQ95SyMWBe81r",
		"first_name": "surya",
		"last_name": "Doe",
		"email": "john@test.com",
		"auto_collection": "off",
		"net_term_days": 7,
		"allow_direct_debit": false,
		"created_at": 1645707316,
		"taxability": "taxable",
		"updated_at": 1645707317,
		"pii_cleared": "active",
		"channel": "web",
		"resource_version": 1645707317008,
		"deleted": false,
		"object": "customer",
		"billing_address": {
			"country": "US",
			"validation_status": "not_validated",
			"object": "billing_address"
		},
		"card_status": "no_card",
		"promotional_credits": 0,
		"refundable_credits": 0,
		"excess_payments": 0,
		"unbilled_charges": 0,
		"preferred_currency_code": "USD"
	},
	"credit_notes": []
}

Expand
title400 Bad Request (Updating a subscription and setting its payment terms to an improper value.)
Request
Code Block
languagebash
curl --location --request POST 'https://{site}.chargebee.com/api/v2/subscriptions/__dev__XpbGQ95SyMjeq32U/update_for_items' \
    --header 'Authorization: Basic dGVzdF9fX2Rldl9fR3RjdUdRV2RLajVaRjdiRmNvNE15amN1d0s2Y2RRdkxjdWJtOjo=' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'subscription_items[item_price_id][0]=plan1-USD-Monthly' \
    --data-urlencode 'subscription_items[unit_price][0]=430' \
    --data-urlencode 'net_term_days=5' \
    --data-urlencode 'auto_collection=off'
Response
Code Block
languagejson
{
	"message": "net_term_days : The value 5 is invalid",
	"type": "invalid_request",
	"api_error_code": "param_wrong_value",
	"param": "net_term_days",
	"error_code": "param_invalid",
	"error_msg": "The value 5 is invalid",
	"error_param": "net_term_days",
	"http_status_code": 400
}

Import subscription for items

Status
colourGreen
titlepost
https://{site}.chargebee.com/api/v2/customers/{customer_id}/import_for_items

New body parameter added

Name

Description

net_term_days

Status
colourPurple
titleinteger
Status
colourYellow
titleoptional

Defines Net D for the subscription. Net D is the number of days within which any invoice raised against for the subscription must be paid.

  • If a value is provided: Net D is set explicitly for the subscription to the value provided. The value must be one among of those provided defined in the site configuration.

  • If not provided: The attribute is not set and therefore not returned by the API. In this case, when an invoice is raised – whether now or later – the net_term_days defined at the customer level is considered.

Samples

Expand
title200 OK (Importing a subscription with payment terms set to Net 10.)
Request
Code Block
languagebash
curl --location --request POST 'https://{site}.chargebee.com/api/v2/customers/__dev__XpbGQ95SyMWBe81r/import_for_items' /
--header 'Authorization: Basic dGVzdF9fX2Rldl9fR3RjdUdRV2RLajVaRjdiRmNvNE15amN1d0s2Y2RRdkxjdWJtOg==' /
--header 'Content-Type: application/x-www-form-urlencoded' /
--data-urlencode 'subscription_items[item_price_id][0]=cbdemo_advanced-USD-monthly' /
--data-urlencode 'subscription_items[quantity][0]=1' /
--data-urlencode 'status=active' /
--data-urlencode 'current_term_end=1646298374' /
--data-urlencode 'net_term_days=10'
Response
Code Block
languagejson
{
	"subscription": {
		"id": "__dev__XpbGQ95SyMmu3s3K",
		"billing_period": 1,
		"billing_period_unit": "month",
		"customer_id": "__dev__XpbGQ95SyMWBe81r",
		"status": "active",
		"current_term_start": 1645711300,
		"current_term_end": 1646298374,
		"next_billing_at": 1646298374,
		"created_at": 1645711300,
		"started_at": 1645711300,
		"activated_at": 1645711300,
		"updated_at": 1645711301,
		"has_scheduled_changes": false,
		"net_term_days": 10,
		"resource_version": 1645711301078,
		"deleted": false,
		"object": "subscription",
		"currency_code": "USD",
		"subscription_items": [{
			"item_price_id": "cbdemo_advanced-USD-monthly",
			"item_type": "plan",
			"quantity": 1,
			"unit_price": 75000,
			"amount": 0,
			"free_quantity": 3,
			"object": "subscription_item"
		}],
		"due_invoices_count": 0,
		"mrr": 0,
		"override_relationship": false,
		"channel": "web"
	},
	"customer": {
		"id": "__dev__XpbGQ95SyMWBe81r",
		"first_name": "surya",
		"last_name": "Doe",
		"email": "john@test.com",
		"auto_collection": "off",
		"net_term_days": 7,
		"allow_direct_debit": false,
		"created_at": 1645707316,
		"taxability": "taxable",
		"updated_at": 1645707317,
		"pii_cleared": "active",
		"channel": "web",
		"resource_version": 1645707317008,
		"deleted": false,
		"object": "customer",
		"billing_address": {
			"country": "US",
			"validation_status": "not_validated",
			"object": "billing_address"
		},
		"card_status": "no_card",
		"promotional_credits": 0,
		"refundable_credits": 0,
		"excess_payments": 0,
		"unbilled_charges": 0,
		"preferred_currency_code": "USD"
	}
}
Expand
title400 Bad Request (Importing a subscription with payment terms set to an improper value.)
Request
Code Block
languagebash
curl --location --request POST 'https://{site}.chargebee.com/api/v2/customers/__dev__XpbGQ95SyMWBe81r/import_for_items' /
--header 'Authorization: Basic dGVzdF9fX2Rldl9fR3RjdUdRV2RLajVaRjdiRmNvNE15amN1d0s2Y2RRdkxjdWJtOg==' /
--header 'Content-Type: application/x-www-form-urlencoded' /
--data-urlencode 'subscription_items[item_price_id][0]=cbdemo_advanced-USD-monthly' /
--data-urlencode 'subscription_items[quantity][0]=1' /
--data-urlencode 'status=active' /
--data-urlencode 'current_term_end=1646298374' /
--data-urlencode 'net_term_days=-1'
Response
Code Block
languagejson
{
	"message": "net_term_days : The value -1 is invalid",
	"type": "invalid_request",
	"api_error_code": "param_wrong_value",
	"param": "net_term_days",
	"error_code": "param_invalid",
	"error_msg": "The value -1 is invalid",
	"error_param": "net_term_days",
	"http_status_code": 400
}
Table of Contents
minLevel1
maxLevel4