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

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

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 ]

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

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

customer

Resource object representing customer.
always returned

promotional_credit

Resource object representing promotional_credit.
always returned

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 ]

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

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

customer

Resource object representing customer.
always returned

promotional_credit

Resource object representing promotional_credit.
always returned

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 ]

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

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

customer

Resource object representing customer.
always returned

promotional_credit

Resource object representing promotional_credit.
always returned

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 ]

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

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] = "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] = "4gkYnd21ouvW"
optional, string filter

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

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 ]

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

Resource object representing promotional_credit.
always returned

Sample promotional credit [ JSON ]

API Index URL GET

Promotional credit attributes

Add Promotional Credits¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Deduct Promotional Credits¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Set Promotional Credits¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

List promotional credits¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Retrieve a promotional credit¶

Sample Response [ JSON ]

URL Format GET

Returns