Gifts

API Version

Product Catalog

Library

Gift represents a subscription of a customer(recipient) to a 'gift plan' which has been gifted by another customer(gifter). It may also have addons and coupons. Gift will be created only on immediate successful payment collection from the gifter's payment method.

Gift is initially created in 'scheduled' state. The gift can be scheduled to be notified on a particular date to the recipient by passing 'scheduled_at'. If not, the recipient is notified immediately. Gift will be moved to 'unclaimed' state on the date of notification. If you pass auto_claim as true, gift status will be moved to ‘claimed’ immediately, otherwise, the gift will remain 'unclaimed' till the recipient claims the gift.

If the gift is not claimed before the claim_expiry_date, it will be moved to the 'expired' state.

GIFT SUBSCRIPTION

Gift subscriptions will be created in 'future' state. Once the gift is claimed, the subscription will be moved to 'non-renewing' state.

INVOICE

Gift subscriptions will be invoiced immediately. The invoice created has is_gifted as 'true' and term_finalized as 'false'. This is because initially the invoice term_start and term_end are set as the subscription's start_date till the end of the plan period. Once the gift is claimed, the invoice's term_finalized will be marked as 'true'. The term_start will be changed to the actual invoice's term, which is the gift-claim date and the term_end will be changed till plan's period.

Sample gift [ JSON ]

{
    "auto_claim": false,
    "claim_expiry_date": 1525850488,
    "gift_receiver": {
        "customer_id": "receiver",
        "email": "james@user.com",
        "first_name": "James",
        "last_name": "William",
        "object": "gift_receiver",
        "subscription_id": "__test__8asuuSB15GTGh"
    },
    "gift_timelines": [
        {
            "object": "gift_timeline",
            "occurred_at": 1517469689,
            "status": "scheduled"
        }
    ],
    "gifter": {
        "customer_id": "gifter",
        "invoice_id": "__demo_inv__1",
        "object": "gifter",
        "signature": "Sam"
    },
    "id": "__test__8asuuSB15GYVo__test__sfsBDu8yg3K6cFiTkMu3cdNcF5Hz9NufM",
    "no_expiry": false,
    "object": "gift",
    "resource_version": 1517469689000,
    "scheduled_at": 1518074488,
    "status": "scheduled",
    "updated_at": 1517469689
}

Model Class

chargebee.gift

id

string, max chars=150
Uniquely identifies a gift

status

enumerated string
Status of the gift.

Possible values are

scheduledGift has been scheduled.unclaimedGift is not yet claimed and is ready to be claimed.claimedGift is claimed.cancelledGift is cancelled.expiredGift is expired.

scheduled_at

optional, timestamp(UTC) in seconds
Indicates the date on which the gift notification is sent to the receiver. If not passed, the receiver is notified immediately.

auto_claim

boolean, default=false
When true, the claim happens automatically. When not passed, the default value in the site settings is used.

no_expiry

boolean
When true, indicates that the gift does not expire. Do not pass or pass as false when auto_claim is set.

claim_expiry_date

optional, timestamp(UTC) in seconds
The date until which the gift can be claimed. Must be set to a value after scheduled_at. If the gift is not claimed within claim_expiry_date, it will expire and the subscription will move to cancelled state. When not passed, the value specified in the site settings will be used. Pass as NULL or do not pass when auto_claim or no_expiry are set.

resource_version

optional, long
Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.

updated_at

optional, timestamp(UTC) in seconds
Timestamp indicating when this gift resource was last updated.

gifter
Show attributes [+]

required, gifter
Gifter details

gift_receiver
Show attributes [+]

required, gift_receiver
Receiver details

gift_timelines
Show attributes [+]

optional, list of gift_timeline
Gift timeline details

id

string, max chars=150
Uniquely identifies a gift

status

enumerated string
Status of the gift.

Possible values are

scheduledGift has been scheduled.unclaimedGift is not yet claimed and is ready to be claimed.claimedGift is claimed.cancelledGift is cancelled.expiredGift is expired.

scheduled_at

optional, timestamp(UTC) in seconds
Indicates the date on which the gift notification is sent to the receiver. If not passed, the receiver is notified immediately.

auto_claim

boolean, default=false
When true, the claim happens automatically. When not passed, the default value in the site settings is used.

no_expiry

boolean
When true, indicates that the gift does not expire. Do not pass or pass as false when auto_claim is set.

claim_expiry_date

resource_version

updated_at

optional, timestamp(UTC) in seconds
Timestamp indicating when this gift resource was last updated.

gifter

gifter
Gifter details

gift_receiver

gift_receiver
Receiver details

gift_timelines

optional, list of gift_timeline
Gift timeline details

Create a gift subscription with items like plans, addons, or charges and gift it to an existing customer.

Sample Codes

 

import {
  ChargeBee,
  _gift
} from 'chargebee-typescript';

var chargebee = new ChargeBee();

chargebee.configure({site : "{site}",
  api_key : "{site_api_key}"});
chargebee.gift.create_for_items({
  scheduled_at : 1518074488,
  gifter : {
    customer_id : "gifter",
    signature : "Sam"
    },
  gift_receiver : {
    customer_id : "receiver",
    first_name : "James",
    last_name : "William",
    email : "james@user.com"
    },
  subscription_items : [
    {
      item_price_id : "day-pass-USD"
    },
    {
      item_price_id : "basic-USD",
      quantity : 2
    }]
}).request(function(error,result) {
  if(error){
    //handle error
    console.log(error);
  }else{
    console.log(`${result}`);
    var gift: typeof chargebee.gift = result.gift;
    var subscription: typeof chargebee.subscription = result.subscription;
    var invoice: typeof chargebee.invoice = result.invoice;
  }
});

copy

Click to Copy

 

import {
  ChargeBee,
  _gift
} from 'chargebee-typescript';

var chargebee = new ChargeBee();

chargebee.configure({site : "{site}",
  api_key : "{site_api_key}"});
chargebee.gift.create_for_items({
  scheduled_at : 1518074488,
  gifter : {
    customer_id : "gifter",
    signature : "Sam"
    },
  gift_receiver : {
    customer_id : "receiver",
    first_name : "James",
    last_name : "William",
    email : "james@user.com"
    },
  subscription_items : [
    {
      item_price_id : "day-pass-USD"
    },
    {
      item_price_id : "basic-USD",
      quantity : 2
    }]
}).request(function(error,result) {
  if(error){
    //handle error
    console.log(error);
  }else{
    console.log(`${result}`);
    var gift: typeof chargebee.gift = result.gift;
    var subscription: typeof chargebee.subscription = result.subscription;
    var invoice: typeof chargebee.invoice = result.invoice;
  }
});

Sample Result [ JSON ]

{
    "gift": {
        "auto_claim": false,
        "claim_expiry_date": 1525850488,
        "gift_receiver": {
            "customer_id": "receiver",
            "email": "james@user.com",
            "first_name": "James",
            "last_name": "William",
            "object": "gift_receiver",
            "subscription_id": "__test__8asuuSB15GTGh"
        },
        "gift_timelines": [
            {
                "object": "gift_timeline",
                "occurred_at": 1517469689,
                "status": "scheduled"
            },
            {..}
        ],
        "gifter": {
            "customer_id": "gifter",
            "invoice_id": "__demo_inv__1",
            "object": "gifter",
            "signature": "Sam"
        },
        "id": "__test__8asuuSB15GYVo__test__sfsBDu8yg3K6cFiTkMu3cdNcF5Hz9NufM",
        "no_expiry": false,
        "object": "gift",
        "resource_version": 1517469689000,
        "scheduled_at": 1518074488,
        "status": "scheduled",
        "updated_at": 1517469689
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 2500,
        "amount_to_collect": 0,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "gifter",
        "date": 1517469688,
        "deleted": false,
        "due_date": 1517469688,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": true,
        "has_advance_charges": true,
        "id": "__demo_inv__1",
        "is_gifted": true,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 2000,
                "customer_id": "receiver",
                "date_from": 1612768888,
                "date_to": 1615188088,
                "description": "basic USD",
                "discount_amount": 0,
                "entity_id": "basic-USD",
                "entity_type": "plan_item_price",
                "id": "li___test__8asuuSB15GVNj",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 2,
                "subscription_id": "__test__8asuuSB15GTGh",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 2500,
                "applied_at": 1517469689,
                "txn_amount": 2500,
                "txn_date": 1517469689,
                "txn_id": "txn___test__8asuuSB15GXhl",
                "txn_status": "success"
            },
            {..}
        ],
        "net_term_days": 0,
        "new_sales_amount": 2500,
        "object": "invoice",
        "paid_at": 1517469689,
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517469689000,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 2500,
        "tax": 0,
        "term_finalized": false,
        "total": 2500,
        "updated_at": 1517469689,
        "write_off_amount": 0
    },
    "subscription": {
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517469688,
        "currency_code": "USD",
        "customer_id": "receiver",
        "deleted": false,
        "due_invoices_count": 0,
        "gift_id": "__test__8asuuSB15GYVo__test__sfsBDu8yg3K6cFiTkMu3cdNcF5Hz9NufM",
        "has_scheduled_changes": false,
        "id": "__test__8asuuSB15GTGh",
        "next_billing_at": 1615188088,
        "object": "subscription",
        "remaining_billing_cycles": 1,
        "resource_version": 1517469689000,
        "start_date": 1612768888,
        "status": "future",
        "subscription_items": [
            {
                "amount": 2000,
                "billing_cycles": 1,
                "free_quantity": 0,
                "item_price_id": "basic-USD",
                "item_type": "plan",
                "object": "subscription_item",
                "quantity": 2,
                "unit_price": 1000
            },
            {..}
        ],
        "updated_at": 1517469689
    }
}

Method

chargebee.gift.create_for_items({<param name> : <value>,<param name> : <value> ...})

scheduled_at[]

optional, timestamp(UTC) in seconds
Indicates the date on which the gift notification is sent to the receiver. If not passed, the receiver is notified immediately.

auto_claim[]

optional, boolean, default=false
When true, the claim happens automatically. When not passed, the default value in the site settings is used.

no_expiry[]

optional, boolean
When true, indicates that the gift does not expire. Do not pass or pass as false when auto_claim is set. .

claim_expiry_date[]

coupon_ids[]

optional, list of string
List of coupons to be applied to this subscription. You can provide coupon ids or coupon codes.

gifter

Object of parameters for gifter
pass parameters as gifter : { <param name> : "<value>",...}

customer_id

required, string, max chars=50
Gifter customer id.

signature

required, string, max chars=50
Gifter sign-off name

note

optional, string, max chars=500
Personalized message for the gift.

payment_src_id

optional, string, max chars=40
Identifier of the payment source

gift_receiver

Object of parameters for gift_receiver
pass parameters as gift_receiver : { <param name> : "<value>",...}

customer_id

required, string, max chars=50
Receiver customer id.

first_name

required, string, max chars=150
First name of the receiver as given by the gifter.

last_name

required, string, max chars=150
Last name of the receiver as given by the gifter,

email

required, string, max chars=70
Email of the receiver. All gift related emails are sent to this email.

payment_intent

Object of parameters for payment_intent
pass parameters as payment_intent : { <param name> : "<value>",...}

id

optional, string, max chars=150
Identifier for PaymentIntent generated by Chargebee.js. Applicable only when you are using Chargebee.js for completing the 3DS flow. The PaymentIntent should be in 'authorized' state while passing it here. You need not pass other PaymentIntent parameters if this is passed.

gateway_account_id

required if payment intent token provided, string, max chars=50
The gateway account used for performing the 3DS flow.

gw_token

optional, string, max chars=65k
Identifier for 3DS transaction/verification object at the gateway. Can be passed only after successfully completing the 3DS flow. Refer 3DS implementation in Chargebee to find out the gateway-specific gw_token format. Applicable when you are using gateway APIs directly for completing the 3DS flow.

payment_method_type

optional, enumerated string
The list of payment method types (For example, card, ideal, sofort, bancontact, etc.) this Payment Intent is allowed to use. If payment method type is empty, Card is taken as the default type for all gateways except Razorpay.

Possible values are

cardcardidealidealsofortsofortbancontactbancontact

Show all values[+]

reference_id

optional, string, max chars=65k
Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.

additional_information

optional, jsonobject

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.
chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.
bank_of_america: While passing raw card details to Bank of America, your user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
ecentric: This parameter is used to verify and process payment method details in Ecentric. If the merchant_id parameter is included, Chargebee will vault it / perform a lookup and verification against this merchant_id, overriding the one configured in Chargebee. If tokens and processing occur in the same Merchant GUID, you can just skip this part.
- merchant_id: Merchant GUID where the card is vaulted or need to be vaulted.
ebanx: While passing raw card details to EBANX, the user's document is required for some countries and device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- payer: User related information.
  - document: Document is the user's identification number based on their country.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device

shipping_address

Object of parameters for shipping_address
pass parameters as shipping_address : { <param name> : "<value>",...}

first_name

optional, string, max chars=150
The first name of the contact.

last_name

optional, string, max chars=150
The last name of the contact.

email

optional, string, max chars=70
The email address.

company

optional, string, max chars=250
The company name.

phone

optional, string, max chars=50
The phone number.

line1

optional, string, max chars=150
Address line 1

line2

optional, string, max chars=150
Address line 2

line3

optional, string, max chars=150
Address line 3

city

optional, string, max chars=50
The name of the city.

state_code

optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).

state

optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.

zip

optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.

country

optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

validation_status

optional, enumerated string, default=not_validated
The address verification status.

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.

subscription_items

Array containing object of parameters for subscription_items
pass parameters as subscription_items : [{"<param name>" => "<value>",...}, {..}...]

item_price_id

optional, string, max chars=100
The unique identifier of the item price.

quantity

optional, integer, default=1, min=1
The quantity of the item purchased

quantity_in_decimal

optional, string, max chars=33
The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when multi-decimal pricing is enabled.

gift

always returned
Resource object representing gift

subscription

always returned
Resource object representing subscription

invoice

optional
Resource object representing invoice

Retrieves a gift subscription. This API accepts the gift ‘id’ and returns the gift along with the subscription.

Sample Codes

 

import {
  ChargeBee,
  _gift
} from 'chargebee-typescript';

var chargebee = new ChargeBee();

chargebee.configure({site : "{site}",
  api_key : "{site_api_key}"});
chargebee.gift.retrieve("__test__KyVnHhSBWTKhSAD__test__XF08jFEYWbAon3fSbc3IriS1N4UNhacdS").request(function(error,result) {
  if(error){
    //handle error
    console.log(error);
  }else{
    console.log(`${result}`);
    var gift: typeof chargebee.gift = result.gift;
    var subscription: typeof chargebee.subscription = result.subscription;
  }
});

copy

Click to Copy

 

import {
  ChargeBee,
  _gift
} from 'chargebee-typescript';

var chargebee = new ChargeBee();

chargebee.configure({site : "{site}",
  api_key : "{site_api_key}"});
chargebee.gift.retrieve("__test__KyVnHhSBWTKhSAD__test__XF08jFEYWbAon3fSbc3IriS1N4UNhacdS").request(function(error,result) {
  if(error){
    //handle error
    console.log(error);
  }else{
    console.log(`${result}`);
    var gift: typeof chargebee.gift = result.gift;
    var subscription: typeof chargebee.subscription = result.subscription;
  }
});

Sample Result [ JSON ]

{
    "gift": {
        "auto_claim": false,
        "claim_expiry_date": 1525277496,
        "gift_receiver": {
            "customer_id": "receiver",
            "email": "james@user.com",
            "first_name": "James",
            "last_name": "William",
            "object": "gift_receiver",
            "subscription_id": "__test__KyVnHhSBWTKfDA7"
        },
        "gift_timelines": [
            {
                "object": "gift_timeline",
                "occurred_at": 1517501491,
                "status": "scheduled"
            },
            {..}
        ],
        "gifter": {
            "customer_id": "gifter",
            "invoice_id": "__demo_inv__6",
            "object": "gifter",
            "signature": "John"
        },
        "id": "__test__KyVnHhSBWTKhSAD__test__XF08jFEYWbAon3fSbc3IriS1N4UNhacdS",
        "no_expiry": false,
        "object": "gift",
        "resource_version": 1517501491000,
        "scheduled_at": 1517501496,
        "status": "scheduled",
        "updated_at": 1517501491
    },
    "subscription": {
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517501491,
        "currency_code": "USD",
        "customer_id": "receiver",
        "deleted": false,
        "due_invoices_count": 0,
        "gift_id": "__test__KyVnHhSBWTKhSAD__test__XF08jFEYWbAon3fSbc3IriS1N4UNhacdS",
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWTKfDA7",
        "next_billing_at": 1614615096,
        "object": "subscription",
        "plan_amount": 10000,
        "plan_free_quantity": 0,
        "plan_id": "GiftPlan$100",
        "plan_quantity": 1,
        "plan_unit_price": 10000,
        "remaining_billing_cycles": 1,
        "resource_version": 1517501491000,
        "start_date": 1612195896,
        "status": "future",
        "updated_at": 1517501491
    }
}

Method

chargebee.gift.retrieve(<gift_id>,{<param name> : <value>,<param name> : <value> ...})

gift

always returned
Resource object representing gift

subscription

always returned
Resource object representing subscription

Retrieves the list of gifts.

Sample Codes

 

import {
  ChargeBee,
  _gift
} from 'chargebee-typescript';

var chargebee = new ChargeBee();

chargebee.configure({site : "{site}",
  api_key : "{site_api_key}"});
chargebee.gift.list({
  limit : 2,
  status : { is : "scheduled" }
}).request(function(error,result) {
  if(error){
    //handle error
    console.log(error);
  }else{
    for(var i = 0; i < result.list.length;i++){
        var entry=result.list[i]
        console.log(`${entry}`);
        var gift: typeof chargebee.gift = entry.gift;
        var subscription: typeof chargebee.subscription = entry.subscription;
      }
    }
  });

copy

Click to Copy

 

import {
  ChargeBee,
  _gift
} from 'chargebee-typescript';

var chargebee = new ChargeBee();

chargebee.configure({site : "{site}",
  api_key : "{site_api_key}"});
chargebee.gift.list({
  limit : 2,
  status : { is : "scheduled" }
}).request(function(error,result) {
  if(error){
    //handle error
    console.log(error);
  }else{
    for(var i = 0; i < result.list.length;i++){
        var entry=result.list[i]
        console.log(`${entry}`);
        var gift: typeof chargebee.gift = entry.gift;
        var subscription: typeof chargebee.subscription = entry.subscription;
      }
    }
  });

Sample Result [ JSON ]

{
    "list": [
        {
            "gift": {
                "auto_claim": true,
                "gift_receiver": {
                    "customer_id": "receiver",
                    "email": "james@user.com",
                    "first_name": "James",
                    "last_name": "William",
                    "object": "gift_receiver",
                    "subscription_id": "__test__KyVnHhSBWTKZn9w"
                },
                "gift_timelines": [
                    {
                        "object": "gift_timeline",
                        "occurred_at": 1517501490,
                        "status": "scheduled"
                    },
                    {..}
                ],
                "gifter": {
                    "customer_id": "gifter",
                    "invoice_id": "__demo_inv__5",
                    "object": "gifter",
                    "signature": "John"
                },
                "id": "__test__KyVnHhSBWTKc1A2__test__DVeEFlt0Io1pxooTbvEgPrvmsY7vbgk8",
                "no_expiry": false,
                "object": "gift",
                "resource_version": 1517501490000,
                "scheduled_at": 1517501495,
                "status": "scheduled",
                "updated_at": 1517501490
            },
            "subscription": {
                "billing_period": 1,
                "billing_period_unit": "month",
                "created_at": 1517501490,
                "currency_code": "USD",
                "customer_id": "receiver",
                "deleted": false,
                "due_invoices_count": 0,
                "gift_id": "__test__KyVnHhSBWTKc1A2__test__DVeEFlt0Io1pxooTbvEgPrvmsY7vbgk8",
                "has_scheduled_changes": false,
                "id": "__test__KyVnHhSBWTKZn9w",
                "next_billing_at": 1614615095,
                "object": "subscription",
                "plan_amount": 10000,
                "plan_free_quantity": 0,
                "plan_id": "GiftPlan$100",
                "plan_quantity": 1,
                "plan_unit_price": 10000,
                "remaining_billing_cycles": 1,
                "resource_version": 1517501490000,
                "start_date": 1612195895,
                "status": "future",
                "updated_at": 1517501490
            }
        },
        {..}
    ],
    "next_offset": "[\"462000000004\"]"
}

Method

chargebee.gift.list({<param name> : <value>,<param name> : <value> ...})

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.

status

optional, enumerated string filter
Status of the gift. Possible values are : scheduled, unclaimed, claimed, cancelled, expired
Supported operators : is, is_not, in, not_in

Example → status: { is : "claimed" }

gift_receiver

Parameters for gift_receiver
pass parameters as gift_receiver : {"<param name>[<operator>]" : "<value>",...}

email[<operator>]

optional, string filter
Email of the receiver. All gift related emails are sent to this email.
Supported operators : is, is_not, starts_with

Example → "gift_receiver[email][is]" : "john@test.com"

customer_id[<operator>]

optional, string filter
Receiver customer id.
Supported operators : is, is_not, starts_with

Example → "gift_receiver[customer_id][is]" : "1xRt6ifdr"

gifter

Parameters for gifter
pass parameters as gifter : {"<param name>[<operator>]" : "<value>",...}

customer_id[<operator>]

optional, string filter
Gifter customer id.
Supported operators : is, is_not, starts_with

Example → "gifter[customer_id][is]" : "1xRt6ifdr"

gift

always returned
Resource object representing gift

subscription

always returned
Resource object representing subscription

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

Claiming a gift will move the status to ‘claimed’. Only gifts in ‘unclaimed’ state can be claimed.

Sample Codes

 

import {
  ChargeBee,
  _gift
} from 'chargebee-typescript';

var chargebee = new ChargeBee();

chargebee.configure({site : "{site}",
  api_key : "{site_api_key}"});
chargebee.gift.claim("__test__KyVnHhSBWTK3l9N__test__ydFDqluaE3CT6DkcdbI5SNhpzjXlrnh5G").request(function(error,result) {
  if(error){
    //handle error
    console.log(error);
  }else{
    console.log(`${result}`);
    var gift: typeof chargebee.gift = result.gift;
    var subscription: typeof chargebee.subscription = result.subscription;
  }
});

copy

Click to Copy

 

import {
  ChargeBee,
  _gift
} from 'chargebee-typescript';

var chargebee = new ChargeBee();

chargebee.configure({site : "{site}",
  api_key : "{site_api_key}"});
chargebee.gift.claim("__test__KyVnHhSBWTK3l9N__test__ydFDqluaE3CT6DkcdbI5SNhpzjXlrnh5G").request(function(error,result) {
  if(error){
    //handle error
    console.log(error);
  }else{
    console.log(`${result}`);
    var gift: typeof chargebee.gift = result.gift;
    var subscription: typeof chargebee.subscription = result.subscription;
  }
});

Sample Result [ JSON ]

{
    "gift": {
        "auto_claim": false,
        "gift_receiver": {
            "customer_id": "receiver",
            "email": "james@user.com",
            "first_name": "James",
            "last_name": "William",
            "object": "gift_receiver",
            "subscription_id": "__test__KyVnHhSBWTK149H"
        },
        "gift_timelines": [
            {
                "object": "gift_timeline",
                "occurred_at": 1517674289,
                "status": "claimed"
            },
            {..}
        ],
        "gifter": {
            "customer_id": "gifter",
            "invoice_id": "__demo_inv__2",
            "object": "gifter",
            "signature": "John"
        },
        "id": "__test__KyVnHhSBWTK3l9N__test__ydFDqluaE3CT6DkcdbI5SNhpzjXlrnh5G",
        "no_expiry": true,
        "object": "gift",
        "resource_version": 1517674289000,
        "scheduled_at": 1517501493,
        "status": "claimed",
        "updated_at": 1517674289
    },
    "subscription": {
        "activated_at": 1517674289,
        "base_currency_code": "USD",
        "billing_period": 1,
        "billing_period_unit": "month",
        "cancelled_at": 1520093489,
        "created_at": 1517501488,
        "currency_code": "USD",
        "current_term_end": 1520093489,
        "current_term_start": 1517674289,
        "customer_id": "receiver",
        "deleted": false,
        "due_invoices_count": 0,
        "exchange_rate": 1,
        "gift_id": "__test__KyVnHhSBWTK3l9N__test__ydFDqluaE3CT6DkcdbI5SNhpzjXlrnh5G",
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWTK149H",
        "mrr": 0,
        "object": "subscription",
        "plan_amount": 10000,
        "plan_free_quantity": 0,
        "plan_id": "GiftPlan$100",
        "plan_quantity": 1,
        "plan_unit_price": 10000,
        "remaining_billing_cycles": 0,
        "resource_version": 1517674289000,
        "started_at": 1517674289,
        "status": "non_renewing",
        "updated_at": 1517674289
    }
}

Method

chargebee.gift.claim(<gift_id>,{<param name> : <value>,<param name> : <value> ...})

gift

always returned
Resource object representing gift

subscription

always returned
Resource object representing subscription

This API allows to cancel gifts. Only gift in ‘scheduled’ and ‘unclaimed’ states can be cancelled.

Sample Codes

 

import {
  ChargeBee,
  _gift
} from 'chargebee-typescript';

var chargebee = new ChargeBee();

chargebee.configure({site : "{site}",
  api_key : "{site_api_key}"});
chargebee.gift.cancel("__test__KyVnHhSBWTJsq9A__test__Y3tQPFRGBG1DZEFsDztdQMlBxpQcdkTcdM").request(function(error,result) {
  if(error){
    //handle error
    console.log(error);
  }else{
    console.log(`${result}`);
    var gift: typeof chargebee.gift = result.gift;
    var subscription: typeof chargebee.subscription = result.subscription;
  }
});

copy

Click to Copy

 

import {
  ChargeBee,
  _gift
} from 'chargebee-typescript';

var chargebee = new ChargeBee();

chargebee.configure({site : "{site}",
  api_key : "{site_api_key}"});
chargebee.gift.cancel("__test__KyVnHhSBWTJsq9A__test__Y3tQPFRGBG1DZEFsDztdQMlBxpQcdkTcdM").request(function(error,result) {
  if(error){
    //handle error
    console.log(error);
  }else{
    console.log(`${result}`);
    var gift: typeof chargebee.gift = result.gift;
    var subscription: typeof chargebee.subscription = result.subscription;
  }
});

Sample Result [ JSON ]

{
    "gift": {
        "auto_claim": false,
        "gift_receiver": {
            "customer_id": "receiver",
            "email": "james@user.com",
            "first_name": "James",
            "last_name": "William",
            "object": "gift_receiver",
            "subscription_id": "__test__KyVnHhSBWTJpi94"
        },
        "gift_timelines": [
            {
                "object": "gift_timeline",
                "occurred_at": 1517501489,
                "status": "scheduled"
            },
            {..}
        ],
        "gifter": {
            "customer_id": "gifter",
            "invoice_id": "__demo_inv__1",
            "object": "gifter",
            "signature": "John"
        },
        "id": "__test__KyVnHhSBWTJsq9A__test__Y3tQPFRGBG1DZEFsDztdQMlBxpQcdkTcdM",
        "no_expiry": true,
        "object": "gift",
        "resource_version": 1517501489000,
        "scheduled_at": 1517501493,
        "status": "cancelled",
        "updated_at": 1517501489
    },
    "subscription": {
        "billing_period": 1,
        "billing_period_unit": "month",
        "cancelled_at": 1517501489,
        "created_at": 1517501488,
        "currency_code": "USD",
        "customer_id": "receiver",
        "deleted": false,
        "due_invoices_count": 0,
        "gift_id": "__test__KyVnHhSBWTJsq9A__test__Y3tQPFRGBG1DZEFsDztdQMlBxpQcdkTcdM",
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWTJpi94",
        "mrr": 0,
        "object": "subscription",
        "plan_amount": 10000,
        "plan_free_quantity": 0,
        "plan_id": "GiftPlan$100",
        "plan_quantity": 1,
        "plan_unit_price": 10000,
        "resource_version": 1517501489000,
        "status": "cancelled",
        "updated_at": 1517501489
    }
}

Method

chargebee.gift.cancel(<gift_id>,{<param name> : <value>,<param name> : <value> ...})

gift

always returned
Resource object representing gift

subscription

always returned
Resource object representing subscription

Change the date/time at which the gift notification email is to be sent. This only applies to gifts in the scheduled status.

Sample Codes

 

import {
  ChargeBee,
  _gift
} from 'chargebee-typescript';

var chargebee = new ChargeBee();

chargebee.configure({site : "{site}",
  api_key : "{site_api_key}"});
chargebee.gift.update_gift("__test__KyVnHhSBWTKnYAO__test__KdVPIxcd0gzgN1seidYQtm0ScuBcUgc3av",{
  comment : "Customer called and requested the change.",
  scheduled_at : 1517587891
}).request(function(error,result) {
  if(error){
    //handle error
    console.log(error);
  }else{
    console.log(`${result}`);
    var gift: typeof chargebee.gift = result.gift;
    var subscription: typeof chargebee.subscription = result.subscription;
  }
});

copy

Click to Copy

 

import {
  ChargeBee,
  _gift
} from 'chargebee-typescript';

var chargebee = new ChargeBee();

chargebee.configure({site : "{site}",
  api_key : "{site_api_key}"});
chargebee.gift.update_gift("__test__KyVnHhSBWTKnYAO__test__KdVPIxcd0gzgN1seidYQtm0ScuBcUgc3av",{
  comment : "Customer called and requested the change.",
  scheduled_at : 1517587891
}).request(function(error,result) {
  if(error){
    //handle error
    console.log(error);
  }else{
    console.log(`${result}`);
    var gift: typeof chargebee.gift = result.gift;
    var subscription: typeof chargebee.subscription = result.subscription;
  }
});

Sample Result [ JSON ]

{
    "gift": {
        "auto_claim": false,
        "claim_expiry_date": 1525277496,
        "gift_receiver": {
            "customer_id": "receiver",
            "email": "james@user.com",
            "first_name": "James",
            "last_name": "William",
            "object": "gift_receiver",
            "subscription_id": "__test__KyVnHhSBWTKkwAI"
        },
        "gift_timelines": [
            {
                "object": "gift_timeline",
                "occurred_at": 1517501491,
                "status": "scheduled"
            },
            {..}
        ],
        "gifter": {
            "customer_id": "gifter",
            "invoice_id": "__demo_inv__7",
            "object": "gifter",
            "signature": "John"
        },
        "id": "__test__KyVnHhSBWTKnYAO__test__KdVPIxcd0gzgN1seidYQtm0ScuBcUgc3av",
        "no_expiry": false,
        "object": "gift",
        "resource_version": 1517501491000,
        "scheduled_at": 1517587891,
        "status": "scheduled",
        "updated_at": 1517501491
    },
    "subscription": {
        "billing_period": 1,
        "billing_period_unit": "month",
        "created_at": 1517501491,
        "currency_code": "USD",
        "customer_id": "receiver",
        "deleted": false,
        "due_invoices_count": 0,
        "gift_id": "__test__KyVnHhSBWTKnYAO__test__KdVPIxcd0gzgN1seidYQtm0ScuBcUgc3av",
        "has_scheduled_changes": false,
        "id": "__test__KyVnHhSBWTKkwAI",
        "next_billing_at": 1614615096,
        "object": "subscription",
        "plan_amount": 10000,
        "plan_free_quantity": 0,
        "plan_id": "GiftPlan$100",
        "plan_quantity": 1,
        "plan_unit_price": 10000,
        "remaining_billing_cycles": 1,
        "resource_version": 1517501491000,
        "start_date": 1612195896,
        "status": "future",
        "updated_at": 1517501491
    }
}

Method

chargebee.gift.update_gift(<gift_id>,{<param name> : <value>,<param name> : <value> ...})

scheduled_at[]

required, timestamp(UTC) in seconds
The new date/time at which the gift notification email is to be sent. The value must be greater than current time. If no_expiry is false then the value must also be less than claim_expiry_date.

comment[]

optional, string, max chars=250
An internal comment for this action. The comments are not retrievable via API and are only available on request via Chargebee Support.

gift

always returned
Resource object representing gift

subscription

always returned
Resource object representing subscription

GIFT SUBSCRIPTION

INVOICE

Sample gift [ JSON ]

API Index URL GET

Model Class

Gift attributes

Consent Fields for Gift

Custom Fields for Gift

Create a gift subscription for items ¶

Notes

Sample Result [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve a gift ¶

Notes

Sample Result [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List gifts ¶

Notes

Sample Result [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Claim a gift ¶

Notes

Sample Result [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Cancel a gift ¶

Notes

Sample Result [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Update a gift ¶

Notes

Sample Result [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL