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:
|
_givy_gifter_name
REQUIRED | Name of the customer sending the gift. Required for all gifts.
|
_givy_recipient_name
REQUIRED | Name of the person receiving the gift. Required for all gifts.
|
_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
JS example: _givy_shipping_cost_per_item: ['10.00','FLAT_RATE'].toString()
Location-Based Rate
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.
|
_givy_message
OPTIONAL | Custom message included on redemption page. Max of 900 characters.
|
_givy_gif_url
OPTIONAL | URL of a custom GIPHY GIF displayed on the recipient's redemption page.
|
_givy_video_message_url
OPTIONAL | URL of a video which will be displayed on the recipient's redemption page.
|
_givy_selling_plan_data
OPTIONAL. REQUIRED FOR SUBSCRIPTION GIFTING | A comma separated list of three values
|
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_dataand_givy_shipping_cost_per_itemall expect the financial values passed in the presentment currency of the customer's sessionPresentment 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.activevalue
Subscription Property
Calculation for the subscription price:
(<item price for chosen selling plan> * <number of recurrences gifted>) + (<shipping cost> * <number of deliveries that occur during the period of gifted recurrences>)
E.g. a $10/month subscription with 6 gifted orders and a $5/month shipping cost:
(10 * 6) + (5 * 6) = 90
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 giftedProperties - 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>