1. Giftnote Order Attribute Schema Reference
The field-by-field reference for the order attributes and line item properties Giftnote reads from custom or headless checkout integrations.
Written By Giftnote Team
Last updated About 1 hour ago
This article documents every field Giftnote reads from Shopify note_attributes (gift messages) and line_item_properties (gift cards), including types, accepted values, format requirements, and what happens when validation fails. After reading this, you can build a custom form or headless integration that correctly passes gift data to Giftnote.
Quick reference
Order attributes — gift messages
Gift message data is stored in Shopify note_attributes at the order level. One gift message per order — Shopify's architecture does not support per-line-item gift messages on a single order. Both the bare giftnote_* form and the underscore-prefixed _giftnote_* form are accepted and normalized identically.
There is no giftnote_medium input field. Since the September update, Giftnote doesn't read a delivery-medium attribute at all. Delivery channel is derived automatically: if giftnote_email is present, email delivery is enabled; if giftnote_phone is present, SMS delivery is enabled; if both are present, both fire. Sending a giftnote_medium attribute has no effect and is silently ignored — control delivery channel by which of giftnote_email/giftnote_phone you send, not by a separate medium field.
Line item properties — gift cards
Gift card recipient data is stored as Shopify line_item_properties on the gift card line item, using the underscore-prefixed _giftnote_* form only. Accepted keys: _giftnote_to, _giftnote_from, _giftnote_message, _giftnote_email, _giftnote_phone, _giftnote_method ("instant" · "scheduled" — no "tracked", gift cards are digital), _giftnote_time, _giftnote_source. There is no _giftnote_medium key here either — same derived-from-presence behavior as order attributes.
The checkout extension widget does not work for gift cards. Only the product page widget triggers the Giftnote flow for gift card purchases.
Gift card product requirements
For Giftnote to recognize a product as a gift card proxy, the Shopify product must be configured exactly as follows:
Full details
giftnote_to
The recipient's name. Displayed in the gift message notification (email and SMS) and in the Giftnote admin. Optional: a message without it still builds.
{ "name": "giftnote_to", "value": "Sarah" }No format restrictions beyond being a non-empty string.
giftnote_from
The sender's name. Displayed in the gift message notification alongside the message body.
{ "name": "giftnote_from", "value": "James" }If you support anonymous gifting, pass the value the sender has consented to display.
giftnote_message
The gift message text. Delivered to the recipient by email, SMS, or both, depending on which contact fields you send.
{ "name": "giftnote_message", "value": "Happy birthday! Hope you love this 🎉" }Keep messages to 210 characters. That is the message limit in the Giftnote admin's Edit Message.
Supports emoji and Unicode. No HTML — messages are rendered as plain text in SMS and as pre-formatted text in email templates.
Delivery channel (email and phone)
There is no giftnote_medium field. The channel follows the contact fields you send:
If you are building a custom form, present both fields. Sending both maximizes delivery success.
giftnote_email
The recipient's email address. Send it to enable email delivery.
{ "name": "giftnote_email", "value": "sarah@example.com" }Trim whitespace before submission. Giftnote validates the email when it reads the order and drops an invalid one, so send a clean address.
Standard email validation applies. Giftnote does not verify deliverability at submission time.
giftnote_phone
The recipient's phone number. Send it to enable SMS delivery.
Must be E.164 format: country code prefix, no spaces, no dashes, no parentheses.
{ "name": "giftnote_phone", "value": "+17082616039" }If a phone number is submitted without the country code prefix (for example, a US number without +1), Giftnote silently drops the attribute. The gift message will not appear in the admin, and no error is surfaced to the merchant or customer.
SMS is sent via Giftnote's own Twilio infrastructure. It is transactional — no opt-in is required from the recipient.
giftnote_method
Controls when the gift message fires.
{ "name": "giftnote_method", "value": "tracked" }For gift card line item properties: only "instant" and "scheduled" are valid. "tracked" is not supported because gift cards are delivered digitally and have no carrier tracking.
"tracked" is the primary product differentiator — the gift message fires at the moment of delivery, not at purchase. This is what most merchants select when using Giftnote for physical gift orders.
giftnote_time
The scheduled delivery date and time for the gift message. Required when giftnote_method is "scheduled".
Must be ISO 8601 format.
{ "name": "giftnote_time", "value": "2026-03-15T09:00:00-05:00" }If you are building a custom date picker, show the selected time in the customer's local timezone within your own UI to set expectations.
If giftnote_method is "scheduled" and giftnote_time is missing or malformed, the gift message is silently dropped.
JavaScript events for custom integrations
If you are building a custom widget, trigger, or cart interaction, Giftnote exposes these JavaScript events:
Example — rehydrate after cart drawer update:
document.dispatchEvent(new Event("giftnoteHydrate"));Example — open widget from a custom button:
document.querySelector('.my-gift-button').addEventListener('click', function() {
document.dispatchEvent(new Event("giftnote_open"));
});Common errors
These are the most frequent integration failures with custom forms and headless implementations. All of them fail silently — Giftnote does not surface validation errors to the storefront, merchant admin, or Shopify admin.
Invalid data is silently dropped
If any required field contains invalid data (wrong format, empty string, missing field), the entire gift message is dropped. It does not appear in the Giftnote admin. No error is logged. No notification is sent to the merchant or customer. An invalid giftnote_email on its own is the exception: the email is dropped and the message still builds for SMS if a valid phone is present. Always validate on your end before submitting to Shopify.
Phone number missing country code
The most common single error. A US phone number submitted as 7082616039 instead of +17082616039 is silently rejected. Your form must prepend the country code in E.164 format before the data reaches Shopify's note_attributes.
Whitespace in email
Trim all whitespace from giftnote_email before submission. Giftnote drops an email it can't validate, and the message then only goes by SMS if a valid phone is present.
Message longer than 210 characters
210 characters is the message limit in the Giftnote admin. If you are building a custom form, enforce the 210-character limit client-side with a visible counter.
Scheduled method without a time
Setting giftnote_method to "scheduled" without a valid giftnote_time value causes the gift message to be silently dropped. Always conditionally require the time field when the scheduled method is selected.
"tracked" method on a gift card line item
Gift cards are delivered digitally — there is no carrier tracking. If _giftnote_method is set to "tracked" on a gift card line item property, the delivery trigger never fires. Use "instant" or "scheduled" only.
Sending giftnote_medium
A giftnote_medium attribute is ignored. If a recipient gets email but no SMS (or the reverse), check which of giftnote_email and giftnote_phone your form actually sends.
Gift card product not the configured one
Giftnote recognizes gift card purchases from the product configured under Settings → Gift Cards → Products, not from a vendor string. If an order processes as a normal Shopify order with no gift card issued, check that the product bought is the one shown there.
Test orders placed via Shopify admin
Orders created through the Shopify admin backend bypass the storefront widget entirely. No note_attributes or line_item_properties are attached. Always place test orders from the live storefront. For testing, use a low-value gift card product and refund after — 100% discount codes can bypass payment and cause downstream failures.
Notes
Order-level, not line-item-level: Gift messages are stored in note_attributes, which apply to the entire order. You cannot attach different gift messages to different line items within the same order. This is a Shopify platform constraint, not a Giftnote limitation.
Gift card data at line-item level: Gift card recipient data is the exception — it uses line_item_properties because the gift card widget captures data on the product page before the item is added to cart, and a single cart may contain physical products alongside gift cards with different recipients.
Reading attributes back from an order: Giftnote stores gift data in its own order metafield. The giftnote_* note attributes (to / from / message / email / phone / source / method) stay visible on the Shopify order only when Keep Order Attributes is on in Settings → Gift Orders → Advanced settings. It is off by default. Giftnote's own processing doesn't need them. The setting is there for tools that read note attributes: themes, packing slips, Shopify Flow, Order Printer and 3PLs. If yours does, turn it on. Shops that had it on before the September update keep it on.
Headless Shopify: The product page and cart drawer widgets are not compatible with headless storefronts. Only the checkout extension widget renders on the myshopify.com checkout URL. For headless implementations, build a custom input form that writes to Shopify note_attributes using the schema above, and the Giftnote backend processes the data identically.
Shadow DOM: The <giftnote-button> web component renders inside a shadow DOM. Standard CSS selectors cannot style it. Use the giftnote_inject_styles event or the CSS field in App Embeds → Giftnote Control Panel in the Shopify theme editor.
Theme publishing resets widget state: Publishing a new Shopify theme drops the Giftnote app embed settings. The merchant must re-enable the Giftnote app embed in the new theme. If your agency manages theme deployments, add this to your go-live checklist.
Shopify Flow bridge: To expose gift message data in the Shopify Notes field (for packing slips, warehouse systems, or ERP integrations), use a Shopify Flow automation that copies note_attributes values into the order Notes field. This is not automatic.
Klaviyo event variable case sensitivity: If you are building Klaviyo email templates that reference Giftnote event data, note that event variables are case-sensitive. {{ event.From }} (capital F) is correct. {{ event.from }} fails silently.