# Checkout gift subscription for items

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


[Idempotency Supported](/docs/api/idempotency)

Creates a hosted page for a customer (called the gifter) to gift a subscription to another customer (called the receiver).

#### Gifter customer resource lookup and creation[](#gifter-customer-resource-lookup-and-creation)

When `[gifter[customer_id]](/docs/api/hosted_pages/checkout-gift-subscription-for-items#gifter_customer_id)` is provided, it is looked up in Chargebee when the gifter completes the hosted page checkout. If not found, a new customer resource is created with this ID.

##### Multiple business entities[](#multiple-business-entities)

If multiple [business entities](/docs/api/advanced-features) are created for the site, the lookup and creation of the gifter customer resource happen within the [context](/docs/api/advanced-features) of the business entity specified in this API call. If no business entity is [specified](/docs/api/advanced-features#mbe-header-main), the customer resource lookup is performed within the [site context](/docs/api/advanced-features), and if not found, the resource is created for the [default business entity](/docs/api/advanced-features) of the site.

#### Gift receiver customer resource lookup and creation[](#gift-receiver-customer-resource-lookup-and-creation)

Once the gifter checks out using the hosted page returned by this endpoint, Chargebee checks if a customer resource with the receiver's email address exists. The first such customer record is considered the receiver's customer resource. A new customer resource is created for the receiver if none are found.

##### Multiple business entities[](#multiple-business-entities)

If multiple [business entities](/docs/api/advanced-features) are created for the site, the lookup and creation of the gift receiver's customer resource happen within the [context](/docs/api/advanced-features) of the business entity of the gifter

## Sample Request

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/hosted_pages/checkout_gift_for_items \
     -u {site_api_key}:\
     -d "gifter[customer_id]"="gifter" \
     -d "subscription_items[item_price_id][0]"="gift-plan-USD" \
     -d "subscription_items[quantity][0]"=2
```

#### .NET

```dotnet
using ChargeBee.Api;
using ChargeBee.Models;

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = HostedPage.CheckoutGiftForItems()
		.GifterCustomerId("gifter")
		.SubscriptionItemItemPriceId(0, "gift-plan-USD")
		.SubscriptionItemQuantity(0, 2)
		.Request();

HostedPage hostedPage = result.HostedPage;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    hostedpageAction "github.com/chargebee/chargebee-go/v3/actions/hostedpage"
    "github.com/chargebee/chargebee-go/v3/models/hostedpage"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := hostedpageAction.CheckoutGiftForItems(&hostedpage.CheckoutGiftForItemsRequestParams{
        SubscriptionItems : []*hostedpage.CheckoutGiftForItemsSubscriptionItemParams{
            {
                ItemPriceId : "gift-plan-USD",
                Quantity : chargebee.Int32(2),
            },
        },
        Gifter : &hostedpage.CheckoutGiftForItemsGifterParams{
            CustomerId : "gifter",
        },
    }).Request()
    if err != nil {
        fmt.Println(err)
    } else {
        HostedPage := res.HostedPage
    }
}
```

#### Go

```go
package main

import (
  "fmt"
  "github.com/chargebee/chargebee-go/v4"
)

func main() {
  config := &chargebee.ClientConfig{
    SiteName: "{site}",
    ApiKey: "{site_api_key}",
  }    
  client := chargebee.NewClient(config)
  req := &chargebee.HostedPageCheckoutGiftForItemsRequest{
    SubscriptionItems : []*chargebee.HostedPageCheckoutGiftForItemsSubscriptionItem{
        {
            ItemPriceId : "gift-plan-USD",
            Quantity : chargebee.Int32(2),
        },
    },
    Gifter : &chargebee.HostedPageCheckoutGiftForItemsGifter{
        CustomerId : "gifter",
    },
}
  res, err := client.HostedPage.CheckoutGiftForItems(req)
      if err != nil {
        fmt.Println(err)
    } else {
        HostedPage := res.HostedPage
    }
}
```

#### Java

```java
import com.chargebee.*;
import com.chargebee.ListResult;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
import java.io.IOException;

public class Sample {

    public static void main(String args[]) throws IOException, Exception {
        Environment.configure("{site}", "{site_api_key}");
        Result result = HostedPage.checkoutGiftForItems()
            .gifterCustomerId("gifter")
            .subscriptionItemItemPriceId(0, "gift-plan-USD")
            .subscriptionItemQuantity(0, 2)
            .request();

        HostedPage hostedPage = result.hostedPage();
    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.hostedPage.HostedPage;
import com.chargebee.v4.models.hostedPage.params.HostedPageCheckoutGiftForItemsParams;
import com.chargebee.v4.models.hostedPage.responses.HostedPageCheckoutGiftForItemsResponse;
import java.util.List;

public class HostedPageCheckoutGiftForItems {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        HostedPageCheckoutGiftForItemsParams.GifterParams gifterParams =
            HostedPageCheckoutGiftForItemsParams.GifterParams.builder()
                .customerId("gifter")
                .build();

        HostedPageCheckoutGiftForItemsParams.SubscriptionItemsParams subscriptionItem0 =
            HostedPageCheckoutGiftForItemsParams.SubscriptionItemsParams.builder()
                .itemPriceId("gift-plan-USD")
                .quantity(2)
                .build();

        List<HostedPageCheckoutGiftForItemsParams.SubscriptionItemsParams> subscriptionItemsList =
            List.of(subscriptionItem0);

        HostedPageCheckoutGiftForItemsParams params = HostedPageCheckoutGiftForItemsParams.builder()
            .gifter(gifterParams)
            .subscriptionItems(subscriptionItemsList)
            .build();

        HostedPageCheckoutGiftForItemsResponse response = client.hostedPages().checkoutGiftForItems(params);

        HostedPage hostedPage = response.getHostedPage();
    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

const chargebee = new Chargebee({
    site: "{site}",
    apiKey: "{site_api_key}",
});

try {
    const result = await chargebee.hostedPage.checkoutGiftForItems({
        subscription_items: [
            {
                item_price_id: "gift-plan-USD",
                quantity: 2
            }
        ],
        gifter: {
            customer_id: "gifter"
        }
    });

    console.log(result);
    const hostedPage = result.hosted_page;
} catch (err) {
    console.log(err);
}
```

#### PHP

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->hostedPage()->checkoutGiftForItems([
    "subscription_items" => [
        [
            "item_price_id" => "gift-plan-USD",
            "quantity" => 2
        ]
    ],
    "gifter" => [
        "customer_id" => "gifter"
    ]
]);
$hostedPage = $result->hosted_page;
```

#### Python

```python
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.HostedPage.checkout_gift_for_items(
    cb_client.HostedPage.CheckoutGiftForItemsParams(
        subscription_items=[
            cb_client.HostedPage.CheckoutGiftForItemsSubscriptionItemParams(
              item_price_id="gift-plan-USD",
              quantity=2
            )
        ],
        gifter=cb_client.HostedPage.CheckoutGiftForItemsGifterParams(
            customer_id="gifter"
        )
    )
)
hosted_page = response.hosted_page
```

#### Ruby

```ruby
require 'chargebee'

ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")

result = ChargeBee::HostedPage.checkout_gift_for_items({
  :gifter => {
    :customer_id => "gifter"
  },
  :subscription_items => [
    {
      :item_price_id => "gift-plan-USD",
      :quantity => 2
    }
  ]
})

hosted_page = result.hosted_page
```

## Sample Response

```json
{
  "hosted_page": {
    "created_at": 1517484798,
    "embed": false,
    "expires_at": 1517488398,
    "id": "__gift___test__gPY4LqKkoEdrcdWdxpl6nABSZu2oDcCpR",
    "layout": "in_app",
    "object": "hosted_page",
    "resource_version": 1517484798645,
    "state": "created",
    "type": "checkout_gift",
    "updated_at": 1517484798,
    "url": "https://yourapp.chargebee.com/pages/v4/__gift___test__gPY4LqKkoEdrcdWdxpl6nABSZu2oDcCpR/"
  }
}
```

## URL Format

**POST** https://[site].chargebee.com/api/v2/hosted_pages/checkout_gift_for_items

## Input Parameters

- `layout` (optional, enumerated string)
  Specifies the UI layout for the hosted page. This overrides [the layout](https://www.chargebee.com/docs/billing/2.0/hosted-capabilities/hosted-checkout#ui-layout-options) configured in Chargebee Billing.
  Possible enum values:
    - `in_app`
      Renders the hosted page in an in-app layout.
    - `full_page`
      Renders the hosted page in a full-page layout.

- `business_entity_id` (optional, string, max chars=50)
  Sets the context for this operation to the [business entity](/docs/api/advanced-features) specified. Applicable only when multiple business entities have been created for the site. When this parameter is provided, the operation is able to read/write data associated only to the business entity specified. When not provided, the operation can read/write data for the entire site.
  
  **Note**
  
  An alternative way of passing this parameter is by means of a [custom HTTP header](/docs/api/advanced-features).
  
  **See also**
  
  Gifter customer resource lookup and creation.

- `brand_id` (optional, string, max chars=50)
  The unique ID of the [brand](/docs/api/brands) this hosted page should be linked to. Applicable only when multiple brands have been created for the site. Resources created through the hosted page, such as the customer and the subscription, are linked to the same brand. An alternative way of passing this parameter is by means of the `chargebee-brand-id` custom HTTP header; when both are provided, they must specify the same brand.
  
  **Default behavior**
  
  -   When not provided, the brand of the customer or subscription referenced in the request is used, or the default brand defined for the site when the request references neither.

- `redirect_url` (optional, string, max chars=250)
  The customers will be redirected to this URL upon successful checkout. The hosted page id and state will be passed as parameters to this URL.
  
  **Note** :
  
  -   Although the customer will be redirected to the `redirect_url` after successful checkout, we do not recommend relying on it for completing critical post-checkout actions. This is because redirection may not happen due to unforeseen reasons such as user closing the tab, or exiting the browser, and so on. If there is any synchronization that you are doing after the redirection, you will have to have a backup. Chargebee recommends listening to appropriate webhooks such as [`subscription_created`](/docs/api/events) or [`invoice_generated`](/docs/api/events) to verify a successful checkout.
  -   Redirect URL configured in Settings > Hosted Pages Settings would be overriden by this redirect URL.
  -   _Eg :_ _http://yoursite.com?id=\*\*&state=succeeded_
  -   This parameter is not applicable for iframe messaging.

- `coupon_ids` (optional, string, max chars=100)
  List of coupons to be applied to this subscription. You can provide coupon ids or [coupon codes](/docs/api/coupon_codes) .

- `gifter` (optional, string)
  Parameters for gifter
  - `customer_id` (optional, string, max chars=50)
    The customer ID of the gifter. If not provided, the gifter customer resource is created with an autogenerated ID on checkout.
    
    **See also**
    
    [Gifter customer resource lookup and creation](/docs/api/hosted_pages)
  - `locale` (optional, string, max chars=50)
    Determines which region-specific language Chargebee uses to communicate with the customer. In the absence of the locale attribute, Chargebee will use your site's default language for customer communication.

- `subscription_items` (optional, array)
  Parameters for subscription\_items
  - `item_price_id` (optional, string, max chars=100)
    The unique identifier of the item price.
  - `quantity` (optional, integer)
    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](/docs/api/getting-started) is enabled.
  - `unit_price` (optional, in cents)
    The price/per unit price of the item. The value is interpreted as per the type of [currency](/docs/api/currencies).
    
    **Prerequisites**
    
    -   The `pricing_model` of the item price is `flat_fee` or `per_unit`.
    -   [Price overriding](https://www.chargebee.com/docs/price-override.html) is enabled for the site.
    
    **Default value**
    
    -   [`item_price.price`](/docs/api/item_prices/item_price-object#price).
  - `unit_price_in_decimal` (optional, string, max chars=39)
    The price/per unit price of the item in major units of the [currency](/docs/api/currencies). When not provided, the [value set for the item price](/docs/api/item_prices/item_price-object#price) is used.
    
    **Prerequisites**
    
    -   The `pricing_model` of the item price is `flat_fee` or `per_unit`.
    -   [Multi-decimal](https://www.chargebee.com/docs/billing/2.0/site-configuration/multi-decimal-support#configuring-multi-decimal-support) pricing is enabled.
    -   [Price overriding](https://www.chargebee.com/docs/2.0/price-override.html) is enabled for the site.
    
    **Default value**
    
    -   [`item_price.price_in_decimal`](/docs/api/item_prices/item_price-object#price_in_decimal).

- `item_tiers` (optional, array)
  Parameters for item\_tiers
  - `item_price_id` (optional, string, max chars=100)
    The id of the item price for which the tier price is being overridden.
  - `starting_unit` (optional, integer)
    The lowest value in the quantity tier.
    
    **Constraints**
    
    -   Must be zero for the lowest tier.
    -   For all other tiers, it must be equal to the `ending_unit` of the next lower tier.
  - `ending_unit` (optional, integer)
    The highest value in the quantity tier.
    
    **Constraints**
    
    -   Not applicable for the highest tier.
    -   Must be equal to the `starting_unit` of the next higher tier.
  - `price` (optional, in cents)
    The overridden price of the tier. The value depends on the [type of currency](/docs/api/currencies).
  - `starting_unit_in_decimal` (optional, string, max chars=33)
    The decimal representation of the lowest value of quantity in this tier.
    
    **Constraints**
    
    -   Must be zero for the lowest tier.
    -   For all other tiers, it must be equal to the `ending_unit_in_decimal` of the next lower tier.
    
    **Prerequisite**
    
    -   [Multi-decimal](https://www.chargebee.com/docs/billing/2.0/site-configuration/multi-decimal-support#configuring-multi-decimal-support) pricing is enabled.
  - `ending_unit_in_decimal` (optional, string, max chars=33)
    The decimal representation of the highest value of quantity in this tier.
    
    **Constraints**
    
    -   Not applicable for the highest tier.
    -   Must be equal to the `starting_unit_in_decimal` of the next higher tier.
    
    **Prerequisite**
    
    -   [Multi-decimal](https://www.chargebee.com/docs/billing/2.0/site-configuration/multi-decimal-support#configuring-multi-decimal-support) pricing is enabled.
  - `price_in_decimal` (optional, string, max chars=39)
    -   The decimal representation of the per-unit price for the tier when the [item\_price.pricing\_model](/docs/api/item_prices/item_price-object#pricing_model) is `tiered` or `volume`.
    -   The decimal representation of the total price for the item when the [item\_price.pricing\_model](/docs/api/item_prices/item_price-object#pricing_model) is `stairstep`.
    
    **Constraints**
    
    -   The value must be in major units of the [currency](/docs/api/currencies).
    
    **Prerequisite**
    
    -   [Multi-decimal](https://www.chargebee.com/docs/billing/2.0/site-configuration/multi-decimal-support#configuring-multi-decimal-support) pricing is enabled.

## Returns

- `hosted_page` (Hosted page object)
  Resource object representing hosted\_page