Promotional credits

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

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

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

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.

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

Try in API Explorer

Only for Java

copy full code

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

copy

Click to Copy

Sample Response [ JSON ]

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

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

reference[]

optional, string, max chars=500
Describes why promotional credits were provided.

customer

always returned
Resource object representing customer

promotional_credit

always returned
Resource object representing promotional_credit

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

Try in API Explorer

Only for Java

copy full code

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

copy

Click to Copy

Sample Response [ JSON ]

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

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

reference[]

optional, string, max chars=500
Describes why promotional credits were provided.

customer

always returned
Resource object representing customer

promotional_credit

always returned
Resource object representing promotional_credit

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.
If a customer has a credit balance of $10 and if you would like to set the balance to $5, you could pass the amount as $5.
If a customer has a credit balance of $10 and if you would like to clear the balance, you could pass the amount as $0.

Sample Request

Try in API Explorer

Only for Java

copy full code

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

copy

Click to Copy

Sample Response [ JSON ]

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

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

reference[]

optional, string, max chars=500
Describes why promotional credits were provided.

customer

always returned
Resource object representing customer

promotional_credit

always returned
Resource object representing promotional_credit

This endpoint lists the promotional credits set for a customer

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

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 ]

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

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

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`.

This endpoint retrieves the promotional credit based on the promotional credit id

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/promotional_credits/pc___test__KyVnHhSBWSuN257 \
     -u {site_api_key}:

copy

Click to Copy

Sample Response [ JSON ]

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

promotional_credit

always returned
Resource object representing promotional_credit

Sample promotional credit [ JSON ]

API Index URL GET

Model Class

Promotional credit attributes

Consent Fields for Promotional credit

Custom Fields for Promotional credit

Add Promotional Credits ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Deduct Promotional Credits ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Set Promotional Credits ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List promotional credits ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve a promotional credit ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL