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 ]

{ "id": "5SK0b1B9R5b8Vg1AsK35cub8Vhohp2bn9gOES5Sa0AxWFA9Cw", "status": "scheduled", "scheduled_at": 1545244200, "auto_claim": false, "claim_expiry_date": 1546108200, "updated_at": 1538735777, "resource_version": 1538735777761, "object": "gift", "gifter": { "customer_id": "cbdemo_dave", "invoice_id": "__demo_inv__28", "signature": "Dave", "note": "Happy Christmas", "object": "gifter" }, "gift_receiver": { "customer_id": "cbdemo_ricky", "subscription_id": "5SK0b1B9R5b8VPl3", "first_name": "Ricky", "last_name": "Roma", "email": "ricky@example.com", "object": "gift_receiver" }, "gift_timelines": [ { "status": "scheduled", "occurred_at": 1538735777, "object": "gift_timeline" }, {..} ] }

API Index URL GET

https://{site}.chargebee.com/api/v2/gifts
id
Uniquely identifies a gift.
string, max chars=150
status
Status of the gift.
enumerated string
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
Indicates the date on which the gift notification is sent to the receiver. If not passed, the receiver is notified immediately.
timestamp(UTC) in seconds
auto_claim
If true, claim will happen automatically.
boolean, default=false
claim_expiry_date
Not applicable when auto-claim is true.The date until which the gift can be claimed. If the gift is not claimed within claim_expiry_date, it will expire and the subscription will move to cancelled state. If this parameter is not passed, the default value set in Site Settings will be used. If auto_claim is set as the default setting in Site Settings, the claim_expiry_date will be set to 90 days from the date of notification.
optional, timestamp(UTC) in seconds
resource_version
Version number of this resource. Each update of this resource results in incremental change of this number. This attribute will be present only if the resource has been updated after 2016-09-28.
optional, long
updated_at
Timestamp indicating when this gift resource was last updated.
optional, timestamp(UTC) in seconds
Gifter details.
gifter
Gifter attributes
customer_id
Gifter customer id.
string, max chars=50
invoice_id
Invoice raised on the gifter.
optional, string, max chars=50
signature
Gifter sign-off name.
optional, string, max chars=50
note
Personalized message for the gift.
optional, string, max chars=500
gift_receiver
Show attributes[+]
Receiver details.
gift_receiver
Gift receiver attributes
customer_id
Receiver customer id.
string, max chars=50
subscription_id
Subscription created for the gift.
string, max chars=50
first_name
First name of the receiver as given by the gifter.
optional, string, max chars=150
last_name
Last name of the receiver as given by the gifter,.
optional, string, max chars=150
email
Email of the receiver. All gift related emails are sent to this email.
optional, string, max chars=70
gift_timelines
Show attributes[+]
Gift timeline details.
list of gift_timeline
Gift timeline attributes
status
Status of the gift.
enumerated string
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.
occurred_at
Timestamp indicating when this event occurred.
optional, timestamp(UTC) in seconds

Creates a gift subscription with the gifter and receiver. Only plans marked as gift plans can be used to create gift subscription. It may also have addons and coupons. A gift is initially created in 'scheduled' state and the gift subscription will be created in 'future' state and invoiced immediately.

Term start and term end dates are determined based on whether the gift is claimed. Before claim, term start date is the subscription start date. Term end date occurs at the end of the plan’s frequency. Once the gift is claimed, the gift claim date becomes the term start date and the term end date will be set as the end of the plan’s frequency.

Sample Request
curl  https://{site}.chargebee.com/api/v2/gifts \
     -u {site_api_key}: \
     -d gifter[signature]="Sam" \
     -d gift_receiver[first_name]="John" \
     -d gift_receiver[last_name]="Doe" \
     -d gift_receiver[email]="john@user.com" \
     -d subscription[plan_id]="basic"
copy
curl  https://{site}.chargebee.com/api/v2/gifts \
     -u {site_api_key}: \
     -d gifter[signature]="Sam" \
     -d gift_receiver[first_name]="John" \
     -d gift_receiver[last_name]="Doe" \
     -d gift_receiver[email]="john@user.com" \
     -d subscription[plan_id]="basic"

Sample Response [ JSON ]

{ "gift": { "id": "5SK0b1B9R5b9trvOHDrikDaCcBotcuAQtFRIahJ6MomiVa5tr", "status": "scheduled", "scheduled_at": 1545244200, "auto_claim": false, "claim_expiry_date": 1553020200, "updated_at": 1538736109, "resource_version": 1538736109080, "object": "gift", "gifter": { "customer_id": "cbdemo_dave", "invoice_id": "__demo_inv__29", "signature": "Dave", "note": "Happy Christmas", "object": "gifter" }, "gift_receiver": { "customer_id": "cbdemo_ricky", "subscription_id": "5SK0b1B9R5b9tpFH", "first_name": "Ricky", "last_name": "Roma", "email": "ricky@example.com", "object": "gift_receiver" }, "gift_timelines": [ { "status": "scheduled", "occurred_at": 1538736109, "object": "gift_timeline" }, {..} ] }, "subscription": { "id": "5SK0b1B9R5b9tpFH", "customer_id": "cbdemo_ricky", "plan_id": "cbdemo_gift", "plan_quantity": 1, "plan_unit_price": 10000, "plan_amount": 10000, "billing_period": 3, "billing_period_unit": "month", "plan_free_quantity": 0, "status": "future", "start_date": 1639938600, "next_billing_at": 1647714600, "remaining_billing_cycles": 1, "created_at": 1538736108, "updated_at": 1538736109, "has_scheduled_changes": false, "resource_version": 1538736109071, "deleted": false, "object": "subscription", "coupon": "cbdemo_holidays", "currency_code": "USD", "coupons": [ { "coupon_id": "cbdemo_holidays", "applied_count": 1, "object": "coupon" }, {..} ], "due_invoices_count": 0, "gift_id": "5SK0b1B9R5b9trvOHDrikDaCcBotcuAQtFRIahJ6MomiVa5tr" }, "invoice": { "id": "__demo_inv__29", "customer_id": "cbdemo_dave", "recurring": true, "status": "paid", "price_type": "tax_exclusive", "date": 1538736108, "due_date": 1538736108, "net_term_days": 0, "exchange_rate": 1.0, "total": 8500, "amount_paid": 8500, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 0, "amount_due": 0, "paid_at": 1538736109, "updated_at": 1538736109, "resource_version": 1538736109062, "deleted": false, "object": "invoice", "first_invoice": true, "amount_to_collect": 0, "round_off_amount": 0, "new_sales_amount": 8500, "has_advance_charges": true, "currency_code": "USD", "base_currency_code": "USD", "is_gifted": true, "term_finalized": false, "tax": 0, "line_items": [ { "id": "li_5SK0b1B9R5b9tqCJ", "date_from": 1639938600, "date_to": 1647714600, "unit_amount": 10000, "quantity": 1, "amount": 10000, "pricing_model": "flat_fee", "is_taxed": false, "tax_amount": 0, "object": "line_item", "subscription_id": "5SK0b1B9R5b9tpFH", "description": "cbdemo_gift", "entity_type": "plan", "entity_id": "cbdemo_gift", "tax_exempt_reason": "tax_not_configured", "discount_amount": 1500, "item_level_discount_amount": 1500 }, {..} ], "discounts": [ { "object": "discount", "entity_type": "item_level_coupon", "description": "Holidays", "amount": 1500, "entity_id": "cbdemo_holidays" }, {..} ], "line_item_discounts": [ { "object": "line_item_discount", "line_item_id": "li_5SK0b1B9R5b9tqCJ", "discount_type": "item_level_coupon", "discount_amount": 1500, "coupon_id": "cbdemo_holidays" }, {..} ], "sub_total": 8500, "linked_payments": [ { "txn_id": "txn_5SK0b1B9R5b9tr1L", "applied_amount": 8500, "applied_at": 1538736109, "txn_status": "success", "txn_date": 1538736109, "txn_amount": 8500 }, {..} ], "applied_credits": [], "adjustment_credit_notes": [], "issued_credit_notes": [], "linked_orders": [], "billing_address": { "first_name": "Dave", "last_name": "Moss", "company": "Moss Enterprises", "validation_status": "not_validated", "object": "billing_address" } } }

URL Format POST

https://{site}.chargebee.com/api/v2/gifts
scheduled_at
Indicates the date on which the gift notification is sent to the receiver. If not passed, the receiver is notified immediately.
optional, timestamp(UTC) in seconds
auto_claim
If true, claim will happen automatically.
optional, boolean
claim_expiry_date
Not applicable when auto-claim is true.The date until which the gift can be claimed. If the gift is not claimed within claim_expiry_date, it will expire and the subscription will move to cancelled state. If this parameter is not passed, the default value set in Site Settings will be used. If auto_claim is set as the default setting in Site Settings, the claim_expiry_date will be set to 90 days from the date of notification.
optional, timestamp(UTC) in seconds
coupon_ids[0..n]
Identifier of the coupon as a List. Coupon Codes can also be passed.
optional, list of string
gifter
Parameters for gifter
pass parameters as gifter[<param name>]
gifter[customer_id]
Gifter customer id.
required, string, max chars=50
gifter[signature]
Gifter sign-off name.
required, string, max chars=50
gifter[note]
Personalized message for the gift.
optional, string, max chars=500
gifter[payment_src_id]
Identifier of the payment source.
optional, string, max chars=40
gift_receiver
Parameters for gift_receiver
pass parameters as gift_receiver[<param name>]
gift_receiver[customer_id]
Receiver customer id.
required, string, max chars=50
gift_receiver[first_name]
First name of the receiver as given by the gifter.
required, string, max chars=150
gift_receiver[last_name]
Last name of the receiver as given by the gifter,.
required, string, max chars=150
gift_receiver[email]
Email of the receiver. All gift related emails are sent to this email.
required, string, max chars=70
subscription
Parameters for subscription
pass parameters as subscription[<param name>]
subscription[plan_id]
Identifier of the plan for this subscription.
required, string, max chars=100
subscription[plan_quantity]
Plan quantity for this subscription.
optional, integer, default=1, min=1
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[first_name]
First name.
optional, string, max chars=150
shipping_address[last_name]
Last name.
optional, string, max chars=150
shipping_address[email]
Email.
optional, string, max chars=70
shipping_address[company]
Company name.
optional, string, max chars=250
shipping_address[phone]
Phone number.
optional, string, max chars=50
shipping_address[line1]
Address line 1.
optional, string, max chars=180
shipping_address[line2]
Address line 2.
optional, string, max chars=150
shipping_address[line3]
Address line 3.
optional, string, max chars=150
shipping_address[city]
City.
optional, string, max chars=50
shipping_address[state_code]
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50
shipping_address[state]
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
shipping_address[zip]
Zip or Postal code.
optional, string, max chars=20
shipping_address[country]
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
shipping_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
addons
Parameters for addons. Multiple addons can be passed by specifying unique indices.
pass parameters as addons[<param name>][<idx:0..n>]
addons[id][0..n]
Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100
addons[quantity][0..n]
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, default=1, min=1
Resource object representing gift.
always returned
Resource object representing subscription.
always returned
Resource object representing invoice.
optional
Retrieves a gift subscription. This API accepts the gift ‘id’ and returns the gift along with the subscription.
Sample Request
curl  https://{site}.chargebee.com/api/v2/gifts/5SK0b1B9R5b8Vg1AsK35cub8Vhohp2bn9gOES5Sa0AxWFA9Cw \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/gifts/5SK0b1B9R5b8Vg1AsK35cub8Vhohp2bn9gOES5Sa0AxWFA9Cw \
     -u {site_api_key}:

Sample Response [ JSON ]

{"gift": { "id": "5SK0b1B9R5b9trvOHDrikDaCcBotcuAQtFRIahJ6MomiVa5tr", "status": "claimed", "scheduled_at": 1545244200, "auto_claim": false, "updated_at": 1538736541, "resource_version": 1538736541450, "object": "gift", "gifter": { "customer_id": "cbdemo_dave", "invoice_id": "__demo_inv__29", "signature": "Dave", "note": "Happy Christmas", "object": "gifter" }, "gift_receiver": { "customer_id": "cbdemo_ricky", "subscription_id": "5SK0b1B9R5b9tpFH", "first_name": "Ricky", "last_name": "Roma", "email": "ricky@example.com", "object": "gift_receiver" }, "gift_timelines": [ { "status": "claimed", "occurred_at": 1545294200, "object": "gift_timeline" }, {..} ] }}

URL Format GET

https://{site}.chargebee.com/api/v2/gifts/{gift_id}
Resource object representing gift.
always returned
Resource object representing subscription.
always returned
Retrieves the list of gifts.
Sample Request
curl  https://{site}.chargebee.com/api/v2/gifts \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5"
copy
curl  https://{site}.chargebee.com/api/v2/gifts \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5"

Sample Response [ JSON ]

{ "list": [ {"gift": { "id": "5SK0b1B9R5b9trvOHDrikDaCcBotcuAQtFRIahJ6MomiVa5tr", "status": "claimed", "scheduled_at": 1545244200, "auto_claim": false, "updated_at": 1538736541, "resource_version": 1538736541450, "object": "gift", "gifter": { "customer_id": "cbdemo_dave", "invoice_id": "__demo_inv__29", "signature": "Dave", "note": "Happy Christmas", "object": "gifter" }, "gift_receiver": { "customer_id": "cbdemo_ricky", "subscription_id": "5SK0b1B9R5b9tpFH", "first_name": "Ricky", "last_name": "Roma", "email": "ricky@example.com", "object": "gift_receiver" }, "gift_timelines": [ { "status": "claimed", "occurred_at": 1545294200, "object": "gift_timeline" }, {..} ] }}, {..} ], "next_offset": "[\"373000000002\"]" }

URL Format GET

https://{site}.chargebee.com/api/v2/gifts
limit
Limits the number of resources to be returned.
optional, integer, default=10, min=1, max=100
offset
Allows you to fetch the next set of resources. The value used for this parameter must be the value returned for next_offset parameter in the previous API call.
optional, string, max chars=1000
Filter Params
For operator usages, see the Pagination and Filtering section.
status[<operator>]
To filter based on Gift Status. Possible values are : scheduled, unclaimed, claimed, cancelled, expired.
Supported operators : is, is_not, in, not_in

Example status[is] = "claimed"
optional, enumerated string filter
gift_receiver
Parameters for gift_receiver
pass parameters as gift_receiver[<param name>][<operator>]
gift_receiver[email][operator]
To filter based on GiftReceiver Email.
Supported operators : is, is_not, starts_with

Example gift_receiver[email][is] = "john@test.com"
optional, string filter
gift_receiver[customer_id][operator]
To filter based on GiftReceiver Customer Id.
Supported operators : is, is_not, starts_with

Example gift_receiver[customer_id][is] = "1xRt6ifdr"
optional, string filter
gifter
Parameters for gifter
pass parameters as gifter[<param name>][<operator>]
gifter[customer_id][operator]
To filter based on Gifter Customer Id.
Supported operators : is, is_not, starts_with

Example gifter[customer_id][is] = "1xRt6ifdr"
optional, string filter
Resource object representing gift.
always returned
Resource object representing subscription.
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
Claiming a gift will move the status to ‘claimed’. Only gifts in ‘unclaimed’ state can be claimed. .
Sample Request
curl  https://{site}.chargebee.com/api/v2/gifts/5SK0b1B9R5b8Vg1AsK35cub8Vhohp2bn9gOES5Sa0AxWFA9Cw/claim \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/gifts/5SK0b1B9R5b8Vg1AsK35cub8Vhohp2bn9gOES5Sa0AxWFA9Cw/claim \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{ "gift": { "id": "5SK0b1B9R5b9trvOHDrikDaCcBotcuAQtFRIahJ6MomiVa5tr", "status": "claimed", "scheduled_at": 1545244200, "auto_claim": false, "updated_at": 1538736541, "resource_version": 1538736541450, "object": "gift", "gifter": { "customer_id": "cbdemo_dave", "invoice_id": "__demo_inv__29", "signature": "Dave", "note": "Happy Christmas", "object": "gifter" }, "gift_receiver": { "customer_id": "cbdemo_ricky", "subscription_id": "5SK0b1B9R5b9tpFH", "first_name": "Ricky", "last_name": "Roma", "email": "ricky@example.com", "object": "gift_receiver" }, "gift_timelines": [ { "status": "claimed", "occurred_at": 1545294200, "object": "gift_timeline" }, {..} ] }, "subscription": { "id": "5SK0b1B9R5b9tpFH", "customer_id": "cbdemo_ricky", "plan_id": "cbdemo_gift", "plan_quantity": 1, "plan_unit_price": 10000, "plan_amount": 10000, "billing_period": 3, "billing_period_unit": "month", "plan_free_quantity": 0, "status": "non_renewing", "current_term_start": 1545294200, "current_term_end": 1553070200, "remaining_billing_cycles": 0, "created_at": 1538736108, "started_at": 1545294200, "activated_at": 1545294200, "cancelled_at": 1553070200, "updated_at": 1545294201, "has_scheduled_changes": false, "resource_version": 1538736541355, "deleted": false, "object": "subscription", "coupon": "cbdemo_holidays", "currency_code": "USD", "coupons": [ { "coupon_id": "cbdemo_holidays", "applied_count": 1, "object": "coupon" }, {..} ], "due_invoices_count": 0, "mrr": 0, "exchange_rate": 1.0, "base_currency_code": "USD", "gift_id": "5SK0b1B9R5b9trvOHDrikDaCcBotcuAQtFRIahJ6MomiVa5tr" } }

URL Format POST

https://{site}.chargebee.com/api/v2/gifts/{gift_id}/claim
Resource object representing gift.
always returned
Resource object representing subscription.
always returned
This API allows to cancel gifts. Only gift in ‘scheduled’ and ‘unclaimed’ states can be cancelled.
Sample Request
curl  https://{site}.chargebee.com/api/v2/gifts/8avVGOkx8U1MX/cancel \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/gifts/8avVGOkx8U1MX/cancel \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{ "gift": { "id": "5SK0b1B9R5b8Vg1AsK35cub8Vhohp2bn9gOES5Sa0AxWFA9Cw", "status": "canceled", "scheduled_at": 1545244200, "auto_claim": false, "claim_expiry_date": 1546108200, "updated_at": 1538737481, "resource_version": 1538737481603, "object": "gift", "gifter": { "customer_id": "cbdemo_dave", "invoice_id": "__demo_inv__28", "signature": "Dave", "note": "Happy Christmas", "object": "gifter" }, "gift_receiver": { "customer_id": "cbdemo_ricky", "subscription_id": "5SK0b1B9R5b8VPl3", "first_name": "Ricky", "last_name": "Roma", "email": "ricky@example.com", "object": "gift_receiver" }, "gift_timelines": [ { "status": "canceled", "occurred_at": 1538737481, "object": "gift_timeline" }, {..} ] }, "subscription": { "id": "5SK0b1B9R5b8VPl3", "customer_id": "cbdemo_ricky", "plan_id": "cbdemo_gift", "plan_quantity": 1, "plan_unit_price": 10000, "plan_amount": 10000, "billing_period": 3, "billing_period_unit": "month", "plan_free_quantity": 0, "status": "cancelled", "created_at": 1538735776, "cancelled_at": 1538737481, "updated_at": 1538737481, "has_scheduled_changes": false, "resource_version": 1538737481654, "deleted": false, "object": "subscription", "coupon": "cbdemo_holidays", "currency_code": "USD", "coupons": [ { "coupon_id": "cbdemo_holidays", "applied_count": 1, "object": "coupon" }, {..} ], "due_invoices_count": 0, "mrr": 0, "gift_id": "5SK0b1B9R5b8Vg1AsK35cub8Vhohp2bn9gOES5Sa0AxWFA9Cw" } }

URL Format POST

https://{site}.chargebee.com/api/v2/gifts/{gift_id}/cancel
Resource object representing gift.
always returned
Resource object representing subscription.
always returned