Giftnote Order Attribute Schema Reference

Developer reference for every Giftnote order attribute field, accepted values, validation rules, JS events, and silent failure modes.

Written By Giftnote Team

Last updated About 3 hours 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.

Field	Type	Required	Accepted values	Default
`giftnote_to`	String	Yes	Recipient's name	—
`giftnote_from`	String	Yes	Sender's name	—
`giftnote_message`	String	Yes	Free text, max 210 characters	—
`giftnote_medium`	String	Yes	`"phone"` · `"email"` · `"both"`	—
`giftnote_email`	String	Conditional	Valid email address — required when `giftnote_medium` is `"email"` or `"both"`	—
`giftnote_phone`	String	Conditional	E.164 format — required when `giftnote_medium` is `"phone"` or `"both"`	—
`giftnote_method`	String	Yes	`"instant"` · `"scheduled"` · `"tracked"`	—
`giftnote_time`	String	Conditional	ISO 8601 datetime — required when `giftnote_method` is `"scheduled"`	—

Line item properties — gift cards

Gift card recipient data is stored as Shopify line_item_properties on the gift card line item. This is because the gift card widget captures data on the product page (not at checkout), and a cart may contain both physical and gift card items with different recipients.

Field	Type	Required	Accepted values
`giftnote_to`	String	Yes	Recipient's name
`giftnote_from`	String	Yes	Sender's name
`giftnote_message`	String	Yes	Free text, max 210 characters
`giftnote_medium`	String	Yes	`"phone"` · `"email"` · `"both"`
`giftnote_email`	String	Conditional	Valid email address — required when `giftnote_medium` is `"email"` or `"both"`
`giftnote_phone`	String	Conditional	E.164 format — required when `giftnote_medium` is `"phone"` or `"both"`
`giftnote_method`	String	Yes	`"instant"` · `"scheduled"` (no `"tracked"` — gift cards are digital)
`giftnote_time`	String	Conditional	ISO 8601 datetime — required when `giftnote_method` is `"scheduled"`

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:

Setting	Required value	What happens if wrong
Vendor	`Giftnote` (capital G)	Gift card code is never generated. Order appears normal in Shopify with no Giftnote processing. Silent failure — no error surfaced.
Track inventory	Unchecked (disabled)	Gift card codes become invalid on issuance.
This is a physical product	Unchecked	Shopify charges shipping on a digital product.
Requires shipping (per variant)	Unchecked on every variant	Shopify prompts for a shipping address at checkout for a digital product.
Product template	Assigned to `gift-card` template type	Giftnote's delivery mechanism does not activate.
Product origin	Created from scratch	Copied or converted products carry hidden attributes that break the Giftnote flow.

Full details

`giftnote_to`

The recipient's name. Displayed in the gift message notification (email and SMS) and in the Giftnote dashboard.

{ "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's standard widget offers an anonymous option that omits the sender name — if you replicate this, omit the field entirely rather than passing an empty string.

`giftnote_message`

The gift message text. Delivered to the recipient via the chosen medium (email, SMS, or both).

{ "name": "giftnote_message", "value": "Happy birthday! Hope you love this 🎉" }

Maximum length: 210 characters. This limit applies across all delivery modes because SMS segments are constrained to 210 characters. Messages exceeding this limit are truncated at delivery.

Supports emoji and Unicode. No HTML — messages are rendered as plain text in SMS and as pre-formatted text in email templates.

`giftnote_medium`

Controls how the gift message is delivered to the recipient.

{ "name": "giftnote_medium", "value": "both" }

Value	Delivery channel	Required companion fields
`"phone"`	SMS only	`giftnote_phone`
`"email"`	Email only	`giftnote_email`
`"both"`	Email + SMS simultaneously	`giftnote_email` and `giftnote_phone`

Approximately 80% of customers provide a phone number in the standard widget; approximately 60% provide an email. If you are building a custom form, present both options — "both" maximizes delivery success.

`giftnote_email`

The recipient's email address. Required when giftnote_medium is "email" or "both".

{ "name": "giftnote_email", "value": "sarah@example.com" }

Trim whitespace before submission. A leading whitespace character in this field passes Shopify's validation but fails Giftnote's recipient matching silently — the gift message is never delivered and no error appears in the dashboard. This is the most common cause of "sent but not received" issues with custom form implementations.

Standard email validation applies. Giftnote does not verify deliverability at submission time.

`giftnote_phone`

The recipient's phone number. Required when giftnote_medium is "phone" or "both".

Must be E.164 format: country code prefix, no spaces, no dashes, no parentheses.

{ "name": "giftnote_phone", "value": "+17082616039" }

Format	Valid?
`+17082616039`	✅
`+447911123456`	✅
`+61412345678`	✅
`7082616039`	❌ Missing country code
`(708) 261-6039`	❌ Contains formatting characters
`+1 708 261 6039`	❌ Contains spaces

If a phone number is submitted without the country code prefix (e.g., a US number without +1), Giftnote silently drops the attribute. The gift message will not appear in the dashboard, 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" }

Value	Behavior	Use case
`"instant"`	Fires immediately after the order is placed	Sender wants recipient to know right away
`"scheduled"`	Fires at the date/time specified in `giftnote_time`	Birthday, holiday, or specific occasion
`"tracked"`	Fires when the carrier marks the parcel as delivered	Surprise gift — message arrives with the package

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" }

Format	Valid?
`2026-03-15T09:00:00-05:00`	✅ Full ISO 8601 with timezone offset
`2026-03-15T14:00:00Z`	✅ UTC
`2026-03-15T09:00:00`	✅ Interpreted as UTC if no offset
`March 15, 2026`	❌ Not ISO 8601
`03/15/2026`	❌ Not ISO 8601
`1710500400`	❌ Unix timestamp not accepted

[Gray callout] Known issue: Scheduled gift message confirmation emails display the time in UTC, not the customer's local timezone. If you are building a custom date picker, consider displaying 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:

Event	Direction	Purpose
`giftnote_saved`	Emitted by Giftnote	Fires when a customer completes the gift message form. Listen for this to add a surcharge/upsell product to the cart.
`giftnote_removed`	Emitted by Giftnote	Fires when a customer removes their gift message. Listen for this to remove the surcharge product from the cart.
`giftnote_open`	Dispatch to Giftnote	Opens the gift message modal programmatically. Use this for exit-intent popups or custom CTA buttons.
`giftnoteHydrate`	Dispatch to Giftnote	Forces the web component to re-render. Dispatch this on every [cart drawer](how-to-add-the-gift-message-widget-to-your-cart-drawer) refresh — AJAX cart updates cause the button to lose state.
`giftnote_inject_styles`	Dispatch to Giftnote	Injects custom styles into the shadow DOM. Standard CSS selectors cannot reach the button's internal styles because it renders inside a shadow DOM.

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 dashboard, 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 dashboard. No error is logged. No notification is sent to the merchant or customer.

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.

Leading whitespace in email

" sarah@example.com" (note the leading space) passes Shopify's order attribute storage but fails Giftnote's recipient matching. The gift message appears as "sent" in some views but is never delivered. Trim all whitespace from giftnote_email before submission.

Message exceeds 210 characters

Messages longer than 210 characters are truncated, not rejected. 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.

Gift card vendor field incorrect

The Shopify product vendor must be exactly Giftnote (capital G, no space). If the vendor field is giftnote, Gift Note, GiftNote, or anything else, Giftnote does not recognize the product. The order processes as a normal Shopify order with no gift card code generated. This is the single most common onboarding failure across all merchants.

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.
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.