If you have decided to build a completely custom gifting flow, your development team will need to add specific line item properties when adding the product to the cart. This guide will walk through the key information required to successfully initiate a gifting flow.

Line Item Properties

Line item property	Values / Example
_givy_send_method REQUIRED	How the gift will be sent. Required for all gifts. Must be one of: `EMAIL_SEND_METHOD` `UNIQUE_LINK_SEND_METHOD` `PRINT_SEND_METHOD`
_givy_gifter_name REQUIRED	Name of the customer sending the gift. Required for all gifts. e.g. `Jane`
_givy_recipient_name REQUIRED	Name of the person receiving the gift. Required for all gifts. e.g. `Jimmy`
_givy_recipient_email SOMETIMES REQUIRED	Email of the person receiving the gift. Required if _givy_send_method = EMAIL_SEND_METHOD
_givy_shipping_cost_per_item OPTIONAL	The shipping amount to charge for this gift. Can either be a flat rate per item, or a location-based rate with a country and province/state code. Flat Rate Amount, in presentment currency Must match the amount specified in the Givy settings If one gifted product or subscription to a recipient uses flat rate shipping, all gifted products that require shipping in the order to that recipient must use flat rate shipping e.g. `'10.00','FLAT_RATE'` JS example: _givy_shipping_cost_per_item: ['10.00','FLAT_RATE'].toString() Location-Based Rate Amount, in presentment currency Ship to country code (e.g. `CA`) Ship to province/state code or name (e.g. `MB`, `California`) - must be data that Shopify recognizes If one gifted subscription to a recipient uses location based shipping, all gifted subscriptions that require shipping in the order to that recipient must use fixed rate shipping. e.g. `'10.00','LOCATION_BASED','CA','MB'` JS example: _givy_shipping_cost_per_item: ['10.00','LOCATION_BASED','CA','MB'].toString() Notes You are allowed to use location based shipping for one gifted product and not other gifted products to the same recipient in the order
_givy_send_date OPTIONAL	Date the gift email will be sent. Format: `YYYY-MM-DD` e.g. `2024-12-31`
_givy_message OPTIONAL	Custom message included on redemption page. Max of 900 characters. e.g. `Happy birthday!`
_givy_gif_url OPTIONAL	URL of a custom GIPHY GIF displayed on the recipient's redemption page. Can be any valid URL
_givy_video_message_url OPTIONAL	URL of a video which will be displayed on the recipient's redemption page. Can be any valid video URL Must link to a video file (ie. MP4), not a YouTube/Vimeo link
_givy_selling_plan_data OPTIONAL. REQUIRED FOR SUBSCRIPTION GIFTING	A comma separated list of three values Selling plan ID from Shopify (int not guid) Number of recurrences gifted Total amount in presentment currency Cost for all recurrences Includes shipping costs e.g. `1277165708,3,250.00`

Data Validation

The Givy properties allow storefronts to modify the price of products which are then charged at checkout. This section provides an overview of how Givy prevents fraudulent activity using these properties.

Financial Validation

The financial amounts included in the _givy_selling_plan_data and _givy_shipping_cost_per_item properties directly result in the price of the gifted product in the cart. To counteract any manipulation of these properties, Givy validates all the financial amounts when the order is created. If a value is determined to be incorrect, the gift will be flagged as potentially fraudulent in the Givy app. Details of this order will also be available in the Givy debug log.

Property Validation

If you complete an order and the gift does not appear in the Givy admin, it means the order failed validation. You can view the validation error messages in the debug log, located at this URL:

https://admin.shopify.com/store/<your shop>/apps/givy/debug

Currency Values

The _givy_selling_plan_data and _givy_shipping_cost_per_item all expect the financial values passed in the presentment currency of the customer's session
Presentment currency is a feature of Shopify Markets. You can refer to this page for more information https://www.shopify.com/ca/partners/blog/multi-currency-app-developers
You can determine the current session's storefront currency by looking at the window.Shopify.currency.active value

Subscription Properties

More detail coming soon

Multiple Gifts / Recipients

An order can contain gifts to multiple recipients as well as multiple gifts to the same recipient. Gifts will be grouped and sent in the same email to a recipient if the following properties have identical values:

_givy_send_method
_givy_recipient_name
_givy_recipient_email
_givy_gifter_name
_givy_message
_givy_gif_url
_givy_video_message_url
_givy_send_date

Note: Even if all properties are identical, gifted products along with gifted subscriptions will result in separate emails. This is due to differences in the redemption flows of the two types of gifts.

Other Line Item Properties

Quantity (qty) - behaves as usual. If set to 2:
- Gifted product - Two of the gifted product would be purchased
- Gifted subscription - Two gifted subscriptions would be purchased. If the _givy_selling_plan_data property specifies 3 recurrences are gifted then the first three recurrences would be gifted on two separate subscriptions.
Variant ID (id) - The variant ID will be the product that is being gifted
Properties - All properties besides the ones identified above that start with _givy will be removed and not appear in the completed order.
Selling Plan ID (selling_plan_id) - The selling plan must not be set when adding a gifted subscription to the cart. The selling plan being gifted is indicated in the _givy_selling_plan_data line item property

Code Examples

Example - Add Gifted Product using Unique Link Method

The following is a sample JavaScript call adding a gifted product to the cart. Replace the id property with the variant ID being gifted.

<script>
   function giftProduct() { 
      const payload = { 
         items: [{ 
            id: 42030736408716, 
            properties: { 
               _givy_recipient_name: 'Kelly', 
               _givy_gifter_name: 'Joe', 
               _givy_send_method: 'UNIQUE_LINK_SEND_METHOD', 
               _givy_message: 'Happy Birthday!', 
            } 
          }] 
      }; 

      fetch(window.Shopify.routes.root + 'cart/add.js', { 
         method: 'POST', 
         headers: { 
            'Content-Type': 'application/json' 
         }, 
         body: JSON.stringify(payload) 
       }) 
       .then(response => response.json()) 
       .then(data => console.log(data)) 
       .catch(error => console.error('Error:', error)); 
   } 
</script>

<button onClick="giftProduct()">Gift Product</button>

Example - Add Gifted Subscription / Membership

The following is a sample JavaScript call adding a gifted subscription to the cart. Replace the id property with the variant ID being gifted, and _givy_selling_plan_data with a valid selling plan ID, duration, and price.

<script>
   function giftSubscription() { 
      const payload = { 
         items: [{ 
            id: 42030736408716, 
            properties: { 
               _givy_recipient_name: 'Kelly', 
               _givy_gifter_name: 'Joe', 
               _givy_send_method: 'UNIQUE_LINK_SEND_METHOD', 
               _givy_message: 'Happy Birthday!', 
               _givy_selling_plan_data: '42141231234,3,120.00', 
            } 
         }] 
      }; 

      fetch(window.Shopify.routes.root + 'cart/add.js', { 
         method: 'POST', 
         headers: { 
            'Content-Type': 'application/json' 
         }, 
         body: JSON.stringify(payload) 
      }) 
      .then(response => response.json()) 
      .then(data => console.log(data)) 
      .catch(error => console.error('Error:', error)); 
   } 
</script> 

<button onClick="giftSubscription()">Gift Subscription</button>

How does product gifting work?

Create a custom gifting modal button

Customizing the subscription name display

How does subscription / membership gifting work?

Add Custom Line Item Properties on Gifted Products