/
Net D for Subscriptions: API Change Summary

Net D for Subscriptions: API Change Summary

Owned by John M
Last updated: Feb 28, 2022Version comment

 

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

integer optional
The Net D value explicitly set for this subscription. Net D is the number of days within which any invoice raised 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

{ "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

post https://{site}.chargebee.com/api/v2/customers/{customer_id}/subscription_for_items

New body parameter added

Name

Description

net_term_days

integer optional
Defines Net D for the subscription. Net D is the number of days within which any invoice raised 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 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

Request
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
{ "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" } } }

 

Request
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
{ "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

post https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/update_for_items

New body parameter added

Name

Description

net_term_days

integer optional
Updates Net D for the subscription. Net D is the number of days within which any invoice raised 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 of those 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

Request
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
{ "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": [] }

 

Request
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

{ "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": [] }

 

Request
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
{ "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

post https://{site}.chargebee.com/api/v2/customers/{customer_id}/import_for_items

New body parameter added

Name

Description

net_term_days

integer optional
Defines Net D for the subscription. Net D is the number of days within which any invoice raised 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 of those 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

Request
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
{ "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" } }
Request
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
{ "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 }