API Version
Product Catalog
Library

These credits can be provided to the customer for promoting the product. You can use Promotional Credits to offer referral bonuses, cash back offers and more. When a customer has promotional credits, it is automatically applied whenever a new invoice is created.

Sample promotional credit [ JSON ]

{ "amount": 100, "closing_balance": 100, "created_at": 1517501388, "credit_type": "general", "currency_code": "USD", "customer_id": "__test__KyVnHhSBWStxi4s", "description": "add promotional credits", "done_by": "full_access_key_v1", "id": "pc___test__KyVnHhSBWStz44u", "object": "promotional_credit", "type": "increment" }

API Index URL GET

https://{site}.chargebee.com/api/v2/promotional_credits

Model Class

id
string, max chars=150
Unique reference ID provided for promotional credits
customer_id
string, max chars=50
Identifier of the customer.
type
enumerated string
Type of promotional credits
Possible values are
incrementIncrementdecrementDecrement
Show all values[+]
amount_in_decimal
optional, string, max chars=33
Amount in decimal
amount
in cents, min=0
Promotional credits amount
currency_code
string, max chars=3
The currency code (ISO 4217 format) for promotional credit
description
string, max chars=250
Detailed description of this promotional credits.
credit_type
enumerated string, default=general
Type of promotional credits provided to customer
Possible values are
loyalty_creditsLoyalty Creditsreferral_rewardsReferralgeneralGeneral
Show all values[+]
reference
optional, string, max chars=500
Describes why promotional credits were provided
closing_balance
in cents, min=0
Closing balance as on end date.
done_by
optional, string, max chars=100
The user who added/deducted the credit. If created via API, this contains the name given for the API key used.
created_at
timestamp(UTC) in seconds
Timestamp indicating when this promotional credit resource is created.
id id
string, max chars=150
Unique reference ID provided for promotional credits
customer_id customer_id
string, max chars=50
Identifier of the customer.
type type
enumerated string
Type of promotional credits
amount_in_decimal amount_in_decimal
optional, string, max chars=33
Amount in decimal
amount amount
in cents, min=0
Promotional credits amount
currency_code currency_code
string, max chars=3
The currency code (ISO 4217 format) for promotional credit
description description
string, max chars=250
Detailed description of this promotional credits.
credit_type credit_type
enumerated string, default=general
Type of promotional credits provided to customer
reference reference
optional, string, max chars=500
Describes why promotional credits were provided
closing_balance closing_balance
in cents, min=0
Closing balance as on end date.
done_by done_by
optional, string, max chars=100
The user who added/deducted the credit. If created via API, this contains the name given for the API key used.
created_at created_at
timestamp(UTC) in seconds
Timestamp indicating when this promotional credit resource is created.

This API call can be used to add promotional credits to a customer. Learn more about Promotional Credits.

For example, if a customer has credits of $10, if you pass the amount as $10, then the customer’s credit balance would become $20.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/promotional_credits/add \
     -u {site_api_key}:\
     -d customer_id="__test__KyVnHhSBWStxi4s" \
     -d amount=100 \
     -d description="add promotional credits"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "balances": [
            {
                "balance_currency_code": "USD",
                "currency_code": "USD",
                "excess_payments": 0,
                "object": "customer_balance",
                "promotional_credits": 100,
                "refundable_credits": 0,
                "unbilled_charges": 0
            },
            {..}
        ],
        "card_status": "no_card",
        "created_at": 1517501388,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Mikel",
        "id": "__test__KyVnHhSBWStxi4s",
        "last_name": "Fox",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 100,
        "refundable_credits": 0,
        "resource_version": 1517501388000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517501388
    },
    "promotional_credit": {
        "amount": 100,
        "closing_balance": 100,
        "created_at": 1517501388,
        "credit_type": "general",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWStxi4s",
        "description": "add promotional credits",
        "done_by": "full_access_key_v1",
        "id": "pc___test__KyVnHhSBWStz44u",
        "object": "promotional_credit",
        "type": "increment"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/promotional_credits/add

Method

customer_id[]
required, string, max chars=50
Identifier of the customer.
amount[]
optional, in cents, min=0
Promotional credits amount.
amount_in_decimal[]
optional, string, max chars=33
Amount in decimal.
currency_code[]
required if Multicurrency is enabled, string, max chars=3
The currency code (ISO 4217 format) for promotional credit.
description[]
required, string, max chars=250
Detailed description of this promotional credits.
credit_type[]
optional, enumerated string, default=general
Type of promotional credits provided to customer.
Possible values are
loyalty_creditsLoyalty Creditsreferral_rewardsReferralgeneralGeneral
Show all values[+]
reference[]
optional, string, max chars=500
Describes why promotional credits were provided.
customer customer
always returned
Resource object representing customer
promotional_credit promotional_credit
always returned
Resource object representing promotional_credit

Sample admin console URL

https://{site}.chargebee.com/admin-console/promotional_credits/123x

This API call can be used to deduct promotional credits for a customer. Learn more about Promotional Credits.

For example, if a customer has a credit balance of $20, if you pass the amount as $5, then the customer’s credit balance would become $15.

If you do not pass any amount as the input parameter then, it will deduct the whole available amount from the credit balance.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/promotional_credits/deduct \
     -u {site_api_key}:\
     -d customer_id="__test__KyVnHhSBWSuFQ4x" \
     -d amount=100 \
     -d description="deduct promotional credits"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "card_status": "no_card",
        "created_at": 1517501389,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Mikel",
        "id": "__test__KyVnHhSBWSuFQ4x",
        "last_name": "Fox",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "resource_version": 1517501389000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517501389
    },
    "promotional_credit": {
        "amount": 100,
        "closing_balance": 0,
        "created_at": 1517501389,
        "credit_type": "general",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWSuFQ4x",
        "description": "deduct promotional credits",
        "done_by": "full_access_key_v1",
        "id": "pc___test__KyVnHhSBWSuGz52",
        "object": "promotional_credit",
        "type": "decrement"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/promotional_credits/deduct

Method

customer_id[]
required, string, max chars=50
Identifier of the customer.
amount[]
optional, in cents, min=0
Promotional credits amount.
amount_in_decimal[]
optional, string, max chars=33
Amount in decimal.
currency_code[]
required if Multicurrency is enabled, string, max chars=3
The currency code (ISO 4217 format) for promotional credit.
description[]
required, string, max chars=250
Detailed description of this promotional credits.
credit_type[]
optional, enumerated string, default=general
Type of promotional credits provided to customer.
Possible values are
loyalty_creditsLoyalty Creditsreferral_rewardsReferralgeneralGeneral
Show all values[+]
reference[]
optional, string, max chars=500
Describes why promotional credits were provided.
customer customer
always returned
Resource object representing customer
promotional_credit promotional_credit
always returned
Resource object representing promotional_credit

Sample admin console URL

https://{site}.chargebee.com/admin-console/promotional_credits/123x

This API call can be used to set the promotional credits balance of a customer. Learn more about Promotional Credits.

For example, if a customer has a credit balance of $10 and if you would like to set the balance to $100, you could pass the amount as $100.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/promotional_credits/set \
     -u {site_api_key}:\
     -d customer_id="__test__KyVnHhSBWSuPk5A" \
     -d amount=100 \
     -d description="set promotional credits"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "customer": {
        "allow_direct_debit": false,
        "auto_collection": "on",
        "balances": [
            {
                "balance_currency_code": "USD",
                "currency_code": "USD",
                "excess_payments": 0,
                "object": "customer_balance",
                "promotional_credits": 100,
                "refundable_credits": 0,
                "unbilled_charges": 0
            },
            {..}
        ],
        "card_status": "no_card",
        "created_at": 1517501390,
        "deleted": false,
        "excess_payments": 0,
        "first_name": "Mikel",
        "id": "__test__KyVnHhSBWSuPk5A",
        "last_name": "Fox",
        "net_term_days": 0,
        "object": "customer",
        "pii_cleared": "active",
        "preferred_currency_code": "USD",
        "promotional_credits": 100,
        "refundable_credits": 0,
        "resource_version": 1517501390000,
        "taxability": "taxable",
        "unbilled_charges": 0,
        "updated_at": 1517501390
    },
    "promotional_credit": {
        "amount": 100,
        "closing_balance": 100,
        "created_at": 1517501390,
        "credit_type": "general",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWSuPk5A",
        "description": "set promotional credits",
        "done_by": "full_access_key_v1",
        "id": "pc___test__KyVnHhSBWSuQc5C",
        "object": "promotional_credit",
        "type": "increment"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/promotional_credits/set

Method

customer_id[]
required, string, max chars=50
Identifier of the customer.
amount[]
optional, in cents, min=0
Promotional credits amount.
amount_in_decimal[]
optional, string, max chars=33
Amount in decimal.
currency_code[]
required if Multicurrency is enabled, string, max chars=3
The currency code (ISO 4217 format) for promotional credit.
description[]
required, string, max chars=250
Detailed description of this promotional credits.
credit_type[]
optional, enumerated string, default=general
Type of promotional credits provided to customer.
Possible values are
loyalty_creditsLoyalty Creditsreferral_rewardsReferralgeneralGeneral
Show all values[+]
reference[]
optional, string, max chars=500
Describes why promotional credits were provided.
customer customer
always returned
Resource object representing customer
promotional_credit promotional_credit
always returned
Resource object representing promotional_credit

Sample admin console URL

https://{site}.chargebee.com/admin-console/promotional_credits/123x
This endpoint lists the promotional credits set for a customer

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/promotional_credits \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=5
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "list": [
        {
            "promotional_credit": {
                "amount": 100,
                "closing_balance": 0,
                "created_at": 1517501389,
                "credit_type": "general",
                "currency_code": "USD",
                "customer_id": "__test__KyVnHhSBWSuFQ4x",
                "description": "deduct promotional credits",
                "done_by": "full_access_key_v1",
                "id": "pc___test__KyVnHhSBWSuGz52",
                "object": "promotional_credit",
                "type": "decrement"
            }
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v2/promotional_credits

Method

limit[]
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset[]
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
Filter Params
For operator usages, see the Pagination and Filtering section.
id[<operator>]
optional, string filter
Unique reference ID provided for promotional credits. Possible values are :
Supported operators : is, is_not, starts_with

Example id[is] = "1bkfc8dw2o"
id[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
id[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
id[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
created_at[<operator>]
optional, timestamp(UTC) in seconds filter
Timestamp indicating when this promotional credit resource is created. Possible values are :
Supported operators : after, before, on, between

Example created_at[after] = "1435054328"
created_at[after][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
created_at[before][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
created_at[on][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
created_at[between][operator]
optional, string filter
Possible values are :
Supported operators :

Example
type[<operator>]
optional, enumerated string filter
Type of promotional credits. Possible values are : increment, decrement
Supported operators : is, is_not, in, not_in

Example type[is] = "increment"
type[is][operator]
optional, enumerated string filter
Possible values are : increment, decrement
Supported operators :

Example
type[is_not][operator]
optional, enumerated string filter
Possible values are : increment, decrement
Supported operators :

Example
type[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
type[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
customer_id[<operator>]
optional, string filter
Identifier of the customer. Possible values are :
Supported operators : is, is_not, starts_with

Example customer_id[is] = "4gkYnd21ouvW"
customer_id[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
customer_id[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
customer_id[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
promotional_credit promotional_credit
always returned
Resource object representing promotional_credit
next_offset next_offset
optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.

Sample admin console URL

https://{site}.chargebee.com/admin-console/promotional_credits/123x
This endpoint retrieves the promotional credit based on the promotional credit id

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/promotional_credits/pc___test__KyVnHhSBWSuN257 \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "promotional_credit": {
        "amount": 100,
        "closing_balance": 100,
        "created_at": 1517501390,
        "credit_type": "general",
        "currency_code": "USD",
        "customer_id": "__test__KyVnHhSBWSuLo55",
        "description": "set promotional credits",
        "done_by": "full_access_key_v1",
        "id": "pc___test__KyVnHhSBWSuN257",
        "object": "promotional_credit",
        "type": "increment"
    }
}

URL Format GET

https://{site}.chargebee.com/api/v2/promotional_credits/{account-credit-id}

Method

promotional_credit promotional_credit
always returned
Resource object representing promotional_credit

Sample admin console URL

https://{site}.chargebee.com/admin-console/promotional_credits/123x