Promotional credits

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

Add Promotional Credits

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
Identifier of the customer.
required, string, max chars=50
amount
Promotional credits amount.
optional, in cents, min=0
amount_in_decimal
Amount in decimal.
optional, string, max chars=11
currency_code
The currency code (ISO 4217 format) for promotional credit.
required if Multicurrency is enabled, string, max chars=3
description
Detailed description of this promotional credits.
required, string, max chars=250
credit_type
Type of promotional credits provided to customer.
optional, enumerated string, default=general
Possible values are
loyalty_creditsLoyalty Credits.referral_rewardsReferral.generalGeneral.
reference
Describes why promotional credits were provided.
optional, string, max chars=500

Returns

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

Deduct Promotional Credits

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.

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
Identifier of the customer.
required, string, max chars=50
amount
Promotional credits amount.
optional, in cents, min=0
amount_in_decimal
Amount in decimal.
optional, string, max chars=11
currency_code
The currency code (ISO 4217 format) for promotional credit.
required if Multicurrency is enabled, string, max chars=3
description
Detailed description of this promotional credits.
required, string, max chars=250
credit_type
Type of promotional credits provided to customer.
optional, enumerated string, default=general
Possible values are
loyalty_creditsLoyalty Credits.referral_rewardsReferral.generalGeneral.
reference
Describes why promotional credits were provided.
optional, string, max chars=500

Returns

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

Set Promotional Credits

This API call can be used to set the promotional credits balnce 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
Identifier of the customer.
required, string, max chars=50
amount
Promotional credits amount.
optional, in cents, min=0
amount_in_decimal
Amount in decimal.
optional, string, max chars=11
currency_code
The currency code (ISO 4217 format) for promotional credit.
required if Multicurrency is enabled, string, max chars=3
description
Detailed description of this promotional credits.
required, string, max chars=250
credit_type
Type of promotional credits provided to customer.
optional, enumerated string, default=general
Possible values are
loyalty_creditsLoyalty Credits.referral_rewardsReferral.generalGeneral.
reference
Describes why promotional credits were provided.
optional, string, max chars=500

Returns

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

List promotional credits

List Promotional Credit.
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
The number of resources to be returned.
optional, integer, default=10, min=1, max=100
offset
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.
optional, string, max chars=1000
Filter Params
For operator usages, see the Pagination and Filtering section.
id[<operator>]
Unique reference ID provided for promotional credits.
Supported operators : is, is_not, starts_with

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

Example → created_at[after] = "1435054328"
optional, timestamp(UTC) in seconds filter
type[<operator>]
Type of promotional credits. Possible values are : increment, decrement.
Supported operators : is, is_not, in, not_in

Example → type[is] = "increment"
optional, enumerated string filter
customer_id[<operator>]
Identifier of the customer.
Supported operators : is, is_not, starts_with

Example → customer_id[is_not] = "4gkYnd21ouvW"
optional, string filter

Returns

promotional_credit
Resource object representing promotional_credit.
always returned
next_offset
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”.
optional, string, max chars=1000

Retrieve a promotional credit

Retrieves the promotional credits.
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
Resource object representing promotional_credit.
always returned