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

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.

business_entity_id

optional, string, max chars=50

The unique identifier of the business entity associated with this promotional credit.

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.

business_entity_id

optional, string, max chars=50

The unique identifier of the business entity associated with this promotional credit.

Try in API Explorer

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

200:

STATUS

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

Try in API Explorer

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

200:

STATUS

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

Try in API Explorer

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

200:

STATUS

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

Try in API Explorer

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

200:

STATUS

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"

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[on] = "1435054328"

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"

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

Try in API Explorer

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

200:

STATUS

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

Model Class

Promotional credit attributes

Consent Fields for Promotional credit

Custom Fields for Promotional credit

Add Promotional Credits ¶

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 ¶

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 ¶

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 ¶

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 ¶

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