Product Catalog
    Library
You are viewing the documentation for Chargebee API V2. If you're using the older version (V1), click here.

Promotional credits

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

Promotional credit attributes

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
incrementIncrement.decrementDecrement.
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 Credits.referral_rewardsReferral.generalGeneral.
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.

Add Promotional Credits

Idempotency Supported

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.

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

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

Input Parameters

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
reference
optional, string, max chars=500
Describes why promotional credits were provided.

Returns

customer
always returned
Resource object representing customer
promotional_credit
always returned
Resource object representing promotional_credit

Deduct Promotional Credits

Idempotency Supported

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.

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

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

Input Parameters

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
reference
optional, string, max chars=500
Describes why promotional credits were provided.

Returns

customer
always returned
Resource object representing customer
promotional_credit
always returned
Resource object representing promotional_credit

Set Promotional Credits

Idempotency Supported

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.

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

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

Input Parameters

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
reference
optional, string, max chars=500
Describes why promotional credits were provided.

Returns

customer
always returned
Resource object representing customer
promotional_credit
always returned
Resource object representing promotional_credit

List promotional credits

This endpoint lists the promotional credits set for a customer
Sample Request 
curl  https://{site}.chargebee.com/api/v2/promotional_credits \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=5
copy
curl  https://{site}.chargebee.com/api/v2/promotional_credits \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=5

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

Input Parameters

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.
Supported operators : is, is_not, starts_with

Example → id[is_not] = "1bkfc8dw2o"
created_at[<operator>]
optional, timestamp(UTC) in seconds filter
Timestamp indicating when this promotional credit resource is created.
Supported operators : after, before, on, between

Example → created_at[after] = "1435054328"
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"
customer_id[<operator>]
optional, string filter
Identifier of the customer.
Supported operators : is, is_not, starts_with

Example → customer_id[is] = "4gkYnd21ouvW"

Returns

promotional_credit
always returned
Resource object representing promotional_credit
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”.

Retrieve a promotional credit

This endpoint retrieves the promotional credit based on the promotional credit id
Sample Request 
curl  https://{site}.chargebee.com/api/v2/promotional_credits/pc___test__KyVnHhSBWSuN257 \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/promotional_credits/pc___test__KyVnHhSBWSuN257 \
     -u {site_api_key}:

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}

Returns

promotional_credit
always returned
Resource object representing promotional_credit