Settings
API Version
Product Catalog
Library

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

Model Class

promotionalcredit.PromotionalCredit

Promotional credit attributes

Id
string, max chars=150
Unique reference ID provided for promotional credits
CustomerId
string, max chars=50
Identifier of the customer.
Type
enumerated string
Type of promotional credits
Possible values are
IncrementIncrementDecrementDecrement
IncrementIncrementDecrementDecrement
Show all values[+]
AmountInDecimal
optional, string, max chars=33
Amount in decimal
Amount
in cents, min=0
Promotional credits amount
CurrencyCode
string, max chars=3
The currency code (ISO 4217 format) for promotional credit
Description
string, max chars=250
Detailed description of this promotional credits.
CreditType
enumerated string, default=general
Type of promotional credits provided to customer
Possible values are
LoyaltyCreditsLoyalty CreditsReferralRewardsReferralGeneralGeneral
LoyaltyCreditsLoyalty CreditsReferralRewardsReferralGeneralGeneral
Show all values[+]
Reference
optional, string, max chars=500
Describes why promotional credits were provided
ClosingBalance
in cents, min=0
Closing balance as on end date.
DoneBy
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.
CreatedAt
timestamp(UTC) in seconds
Timestamp indicating when this promotional credit resource is created.
Id Id
string, max chars=150
Unique reference ID provided for promotional credits
CustomerId CustomerId
string, max chars=50
Identifier of the customer.
Type Type
enumerated string
Type of promotional credits
Possible values are
IncrementIncrementDecrementDecrement
IncrementIncrementDecrementDecrement
Show all values[+]
AmountInDecimal AmountInDecimal
optional, string, max chars=33
Amount in decimal
Amount Amount
in cents, min=0
Promotional credits amount
CurrencyCode CurrencyCode
string, max chars=3
The currency code (ISO 4217 format) for promotional credit
Description Description
string, max chars=250
Detailed description of this promotional credits.
CreditType CreditType
enumerated string, default=general
Type of promotional credits provided to customer
Possible values are
LoyaltyCreditsLoyalty CreditsReferralRewardsReferralGeneralGeneral
LoyaltyCreditsLoyalty CreditsReferralRewardsReferralGeneralGeneral
Show all values[+]
Reference Reference
optional, string, max chars=500
Describes why promotional credits were provided
ClosingBalance ClosingBalance
in cents, min=0
Closing balance as on end date.
DoneBy DoneBy
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.
CreatedAt CreatedAt
timestamp(UTC) in seconds
Timestamp indicating when this promotional credit resource is created.

Consent Fields for Promotional credit

Custom Fields for Promotional credit

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.

Notes

Sample Codes 
 

package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    promotionalcreditAction "github.com/chargebee/chargebee-go/v3/actions/promotionalcredit"
    "github.com/chargebee/chargebee-go/v3/models/promotionalcredit"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := promotionalcreditAction.Add(&promotionalcredit.AddRequestParams {
        CustomerId : "__test__KyVnHhSBWStxi4s",
        Amount : chargebee.Int64(100),
        Description : "add promotional credits",
    }).Request()
    if err != nil {
        fmt.Println(err)
    }else{
        Customer := res.Customer
        PromotionalCredit := res.PromotionalCredit
        }
    }
copy
Click to Copy
 

package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    promotionalcreditAction "github.com/chargebee/chargebee-go/v3/actions/promotionalcredit"
    "github.com/chargebee/chargebee-go/v3/models/promotionalcredit"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := promotionalcreditAction.Add(&promotionalcredit.AddRequestParams {
        CustomerId : "__test__KyVnHhSBWStxi4s",
        Amount : chargebee.Int64(100),
        Description : "add promotional credits",
    }).Request()
    if err != nil {
        fmt.Println(err)
    }else{
        Customer := res.Customer
        PromotionalCredit := res.PromotionalCredit
        }
    }

Sample Result [ 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

Method

promotionalCreditAction.Add(&promotionalCredit.AddRequestParams {<param name> : <value>,<param name> : <value> ...}).Request()

Input Parameters

CustomerId[]
required, string, max chars=50
Identifier of the customer.
Amount[]
optional, in cents, min=0
Promotional credits amount.
AmountInDecimal[]
optional, string, max chars=33
Amount in decimal.
CurrencyCode[]
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.
CreditType[]
optional, enumerated string, default=general
Type of promotional credits provided to customer.
Possible values are
LoyaltyCreditsLoyalty CreditsReferralRewardsReferralGeneralGeneral
LoyaltyCreditsLoyalty CreditsReferralRewardsReferralGeneralGeneral
Show all values[+]
Reference[]
optional, string, max chars=500
Describes why promotional credits were provided.

Returns

Customer Customer
always returned
Resource object representing customer
PromotionalCredit PromotionalCredit
always returned
Resource object representing promotional_credit

Sample admin console URL

https://{site}.chargebee.com/admin-console/promotional_credits/123x

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.

Notes

Sample Codes 
 

package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    promotionalcreditAction "github.com/chargebee/chargebee-go/v3/actions/promotionalcredit"
    "github.com/chargebee/chargebee-go/v3/models/promotionalcredit"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := promotionalcreditAction.Deduct(&promotionalcredit.DeductRequestParams {
        CustomerId : "__test__KyVnHhSBWSuFQ4x",
        Amount : chargebee.Int64(100),
        Description : "deduct promotional credits",
    }).Request()
    if err != nil {
        fmt.Println(err)
    }else{
        Customer := res.Customer
        PromotionalCredit := res.PromotionalCredit
        }
    }
copy
Click to Copy
 

package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    promotionalcreditAction "github.com/chargebee/chargebee-go/v3/actions/promotionalcredit"
    "github.com/chargebee/chargebee-go/v3/models/promotionalcredit"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := promotionalcreditAction.Deduct(&promotionalcredit.DeductRequestParams {
        CustomerId : "__test__KyVnHhSBWSuFQ4x",
        Amount : chargebee.Int64(100),
        Description : "deduct promotional credits",
    }).Request()
    if err != nil {
        fmt.Println(err)
    }else{
        Customer := res.Customer
        PromotionalCredit := res.PromotionalCredit
        }
    }

Sample Result [ 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

Method

promotionalCreditAction.Deduct(&promotionalCredit.DeductRequestParams {<param name> : <value>,<param name> : <value> ...}).Request()

Input Parameters

CustomerId[]
required, string, max chars=50
Identifier of the customer.
Amount[]
optional, in cents, min=0
Promotional credits amount.
AmountInDecimal[]
optional, string, max chars=33
Amount in decimal.
CurrencyCode[]
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.
CreditType[]
optional, enumerated string, default=general
Type of promotional credits provided to customer.
Possible values are
LoyaltyCreditsLoyalty CreditsReferralRewardsReferralGeneralGeneral
LoyaltyCreditsLoyalty CreditsReferralRewardsReferralGeneralGeneral
Show all values[+]
Reference[]
optional, string, max chars=500
Describes why promotional credits were provided.

Returns

Customer Customer
always returned
Resource object representing customer
PromotionalCredit PromotionalCredit
always returned
Resource object representing promotional_credit

Sample admin console URL

https://{site}.chargebee.com/admin-console/promotional_credits/123x

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

Notes

Sample Codes 
 

package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    promotionalcreditAction "github.com/chargebee/chargebee-go/v3/actions/promotionalcredit"
    "github.com/chargebee/chargebee-go/v3/models/promotionalcredit"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := promotionalcreditAction.Set(&promotionalcredit.SetRequestParams {
        CustomerId : "__test__KyVnHhSBWSuPk5A",
        Amount : chargebee.Int64(100),
        Description : "set promotional credits",
    }).Request()
    if err != nil {
        fmt.Println(err)
    }else{
        Customer := res.Customer
        PromotionalCredit := res.PromotionalCredit
        }
    }
copy
Click to Copy
 

package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    promotionalcreditAction "github.com/chargebee/chargebee-go/v3/actions/promotionalcredit"
    "github.com/chargebee/chargebee-go/v3/models/promotionalcredit"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := promotionalcreditAction.Set(&promotionalcredit.SetRequestParams {
        CustomerId : "__test__KyVnHhSBWSuPk5A",
        Amount : chargebee.Int64(100),
        Description : "set promotional credits",
    }).Request()
    if err != nil {
        fmt.Println(err)
    }else{
        Customer := res.Customer
        PromotionalCredit := res.PromotionalCredit
        }
    }

Sample Result [ 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

Method

promotionalCreditAction.Set(&promotionalCredit.SetRequestParams {<param name> : <value>,<param name> : <value> ...}).Request()

Input Parameters

CustomerId[]
required, string, max chars=50
Identifier of the customer.
Amount[]
optional, in cents, min=0
Promotional credits amount.
AmountInDecimal[]
optional, string, max chars=33
Amount in decimal.
CurrencyCode[]
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.
CreditType[]
optional, enumerated string, default=general
Type of promotional credits provided to customer.
Possible values are
LoyaltyCreditsLoyalty CreditsReferralRewardsReferralGeneralGeneral
LoyaltyCreditsLoyalty CreditsReferralRewardsReferralGeneralGeneral
Show all values[+]
Reference[]
optional, string, max chars=500
Describes why promotional credits were provided.

Returns

Customer Customer
always returned
Resource object representing customer
PromotionalCredit PromotionalCredit
always returned
Resource object representing promotional_credit

Sample admin console URL

https://{site}.chargebee.com/admin-console/promotional_credits/123x

List promotional credits

This endpoint lists the promotional credits set for a customer

Notes

Sample Codes 
 

package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    "github.com/chargebee/chargebee-go/v3/filter"
    promotionalcreditAction "github.com/chargebee/chargebee-go/v3/actions/promotionalcredit"
    "github.com/chargebee/chargebee-go/v3/models/promotionalcredit"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := promotionalcreditAction.List(&promotionalcredit.ListRequestParams {
        Limit : chargebee.Int32(5),
    }).ListRequest()
    if err != nil {
        fmt.Println(err)
    }else{
        for idx := 0; idx < len(res.List); idx++ {
            PromotionalCredit := res.List[idx].PromotionalCredit
            }
        }
    }
copy
Click to Copy
 

package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    "github.com/chargebee/chargebee-go/v3/filter"
    promotionalcreditAction "github.com/chargebee/chargebee-go/v3/actions/promotionalcredit"
    "github.com/chargebee/chargebee-go/v3/models/promotionalcredit"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := promotionalcreditAction.List(&promotionalcredit.ListRequestParams {
        Limit : chargebee.Int32(5),
    }).ListRequest()
    if err != nil {
        fmt.Println(err)
    }else{
        for idx := 0; idx < len(res.List); idx++ {
            PromotionalCredit := res.List[idx].PromotionalCredit
            }
        }
    }

Sample Result [ 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

Method

promotionalCreditAction.List(&promotionalCredit.ListRequestParams {<param name> : <value>,<param name> : <value> ...}).ListRequest()

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
optional, string filter
Unique reference ID provided for promotional credits. Possible values are :
Supported operators : is, is_not, starts_with

Example → Id : &filter.StringFilter{ Is : "1bkfc8dw2o" }
is
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example →
is_not
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example →
starts_with
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example →
CreatedAt
optional, timestamp(UTC) in seconds filter
Timestamp indicating when this promotional credit resource is created. Possible values are :
Supported operators : after, before, on, between

Example → CreatedAt : &filter.TimestampFilter{ After : chargebee.Int64(1435054328) }
after
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example →
before
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example →
on
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example →
between
optional, string filter
Possible values are :
Supported operators :

Example →
Type
optional, enumerated string filter
Type of promotional credits. Possible values are : Increment, Decrement
Supported operators : is, is_not, in, not_in

Example → Type : &filter.EnumFilter{ Is : "increment" }
is
optional, enumerated string filter
Possible values are : Increment, Decrement
Supported operators :

Example →
is_not
optional, enumerated string filter
Possible values are : increment, decrement
Supported operators :

Example →
in
optional, string filter
Possible values are :
Supported operators :

Example →
not_in
optional, string filter
Possible values are :
Supported operators :

Example →
CustomerId
optional, string filter
Identifier of the customer. Possible values are :
Supported operators : is, is_not, starts_with

Example → CustomerId : &filter.StringFilter{ Is : "4gkYnd21ouvW" }
is
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example →
is_not
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example →
starts_with
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example →

Returns

PromotionalCredit PromotionalCredit
always returned
Resource object representing promotional_credit
NextOffset NextOffset
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`.

Sample admin console URL

https://{site}.chargebee.com/admin-console/promotional_credits/123x

Retrieve a promotional credit

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

Notes

Sample Codes 
 

package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    promotionalcreditAction "github.com/chargebee/chargebee-go/v3/actions/promotionalcredit"
    "github.com/chargebee/chargebee-go/v3/models/promotionalcredit"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := promotionalcreditAction.Retrieve("pc___test__KyVnHhSBWSuN257").Request()
    if err != nil {
        fmt.Println(err)
    }else{
        PromotionalCredit := res.PromotionalCredit
        }
    }
copy
Click to Copy
 

package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    promotionalcreditAction "github.com/chargebee/chargebee-go/v3/actions/promotionalcredit"
    "github.com/chargebee/chargebee-go/v3/models/promotionalcredit"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := promotionalcreditAction.Retrieve("pc___test__KyVnHhSBWSuN257").Request()
    if err != nil {
        fmt.Println(err)
    }else{
        PromotionalCredit := res.PromotionalCredit
        }
    }

Sample Result [ 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}

Method

promotionalCreditAction.Retrieve(<account_credit_id>,&promotionalCredit.RetrieveRequestParams {<param name> : <value>,<param name> : <value> ...}).Request()

Returns

PromotionalCredit PromotionalCredit
always returned
Resource object representing promotional_credit

Sample admin console URL

https://{site}.chargebee.com/admin-console/promotional_credits/123x