# Gifts

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


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-subscription)

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

#### INVOICE[](#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
}
```

## Gifts attributes

## Input Parameters

- `id` (required, string, max chars=150)
  Uniquely identifies a gift

- `status` (required, enumerated string)
  Status of the gift.
  Possible enum values:
    - `scheduled`
      Gift has been scheduled.
    - `unclaimed`
      Gift is not yet claimed and is ready to be claimed.
    - `claimed`
      Gift is claimed.
    - `cancelled`
      Gift is cancelled.
    - `expired`
      Gift 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` (required, boolean, default=false)
  When `true` , the claim happens automatically. When not passed, the default value in the site settings is used.

- `no_expiry` (required, 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` (required, gifter)
  Gifter details
  - `customer_id` (required, string, max chars=50)
    Gifter customer id.
  - `invoice_id` (optional, string, max chars=50)
    Invoice raised on the gifter.
  - `signature` (optional, string, max chars=50)
    Gifter sign-off name
  - `note` (optional, string, max chars=500)
    Personalized message for the gift.

- `gift_receiver` (required, gift_receiver)
  Receiver details
  - `customer_id` (required, string, max chars=50)
    Receiver customer id.
  - `subscription_id` (required, string, max chars=50)
    Subscription created for the gift.
  - `first_name` (optional, string, max chars=150)
    First name of the receiver as given by the gifter.
  - `last_name` (optional, string, max chars=150)
    Last name of the receiver as given by the gifter,
  - `email` (optional, string, max chars=70)
    Email of the receiver. All gift related emails are sent to this email.

- `gift_timelines` (optional, list of gift_timeline)
  Gift timeline details
  - `status` (required, enumerated string)
    Status of the gift.
    Possible enum values:
      - `scheduled`
        Gift has been scheduled.
      - `unclaimed`
        Gift is not yet claimed and is ready to be claimed.
      - `claimed`
        Gift is claimed.
      - `cancelled`
        Gift is cancelled.
      - `expired`
        Gift is expired.
  - `occurred_at` (optional, timestamp(UTC) in seconds)
    Timestamp indicating when this event occurred.