Settings
Configure SDK
Gifts
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
}API Index URL
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.
Gifter details
Receiver details
Gift timeline details
Create a gift subscription for items ¶
Create a gift subscription with items like plans, addons, or charges and gift it to an existing customer.
Sample Response [ JSON ]
URL Format POST
Input Parameters
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.
pass parameters as payment_intent[<param name>]
pass parameters as shipping_address[<param name>]
pass parameters as subscription_items[<param name>][<idx:0..n>]
pass parameters as item_tiers[<param name>][<idx:0..n>]
Returns
Resource object representing gift
Resource object representing subscription
Resource object representing invoice
Retrieve a gift ¶
Retrieves a gift subscription. This API accepts the gift 'id' and returns the gift along with the subscription.
Sample Response [ JSON ]
URL Format GET
Returns
Resource object representing gift
Resource object representing subscription
List gifts ¶
Retrieves the list of gifts.
Sample Response [ JSON ]
URL Format GET
Input Parameters
Filter Params
For operator usages, see the Pagination and Filtering section.
Parameters for gift_receiver
pass parameters as gift_receiver[<param name>][<operator>]
Returns
Resource object representing gift
Resource object representing subscription
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`.
Claim a gift ¶
Claiming a gift will move the status to 'claimed'. Only gifts in 'unclaimed' state can be claimed.
Sample Response [ JSON ]
URL Format POST
Returns
Resource object representing gift
Resource object representing subscription
Cancel a gift ¶
This API allows to cancel gifts. Only gift in 'scheduled' and 'unclaimed' states can be cancelled.
Sample Response [ JSON ]
URL Format POST
Returns
Resource object representing gift
Resource object representing subscription
Update a gift ¶
Change the date/time at which the gift notification email is to be sent. This only applies to gifts in the scheduled status .
Sample Response [ JSON ]
URL Format POST
Input Parameters
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 .
An internal comment for this action. The comments are not retrievable via API and are only available on request via Chargebee Support .
Returns
Resource object representing gift
Resource object representing subscription