Products are not issued cards#
A Gift Card product is a catalog listing; an issued card holds a redeemable balance. Use Store API GET /api/2025-01/gift-cards/products with read_products and read_gift_cards, or filter GET /api/2025-01/products with is_gift_card=true. The normal product list includes both classifications. Product create uses POST /api/2025-01/gift-cards/products with write_products and write_gift_cards. Updates and deletion use /products/{id} and require both write scopes for Gift Card products. Publishing requires active status and an explicit sales-channel assignment; creating a product does not insert menu links or issue a card.
One public classification for every integration#
Hosted product and product-card CTX expose is_gift_card. The browser bridge exposes product_is_gift_card in its product-page context. An app surface can declare product.is_gift_card to receive product_is_gift_card in its scoped context. This is the same public catalog fact for every app: it grants no extra permissions and does not replace an app’s compatibility decisions. Gift Card products keep their simple or variable product type. Do not confuse is_gift_card with gift_only, which identifies free-gift promotional inventory.
Recipient input#
Omit gift_card_recipient (or supply null) to deliver to the purchaser’s checkout contact. To send to someone else, provide an object with name, email, phone, message and optional deliver_at (RFC 3339). Supply a valid email or an international phone number beginning with +. If both are present, purchase delivery uses email. The delivery route must be configured before an order can be placed. A schedule must be in the future. The server rejects amount, currency, expiry-policy and other undeclared fields; purchase value always comes from authoritative catalog pricing.
The browser methods tringify.cart.add and tringify.checkout.buyNow accept gift_card_recipient alongside product_id, variant_id and quantity. For example: tringify.cart.add({product_id: 7, quantity: 1, gift_card_recipient: {name: "Avery", email: "avery@example.com", message: "Enjoy your gift"}}). Use the normal hosted action response and display its localized message; do not translate backend error codes in the client.
Hosted cart_add forms accept gift_card_recipient as a JSON field. Native HTML controls can instead submit gift_card_send_as_gift=true with gift_card_recipient_name, gift_card_recipient_email, gift_card_recipient_phone, gift_card_recipient_message and gift_card_deliver_at. A datetime-local value on this hosted field is interpreted as UTC and must be labelled accordingly. The same form fields are preserved when the submitter uses purchase_intent=buy_now. Themes control presentation and must expose recipient controls themselves; existing custom themes are not silently rewritten.
Hosted cart.items exposes gift_card_recipient with snake_case fields: name, email, phone, message and deliver_at. App surface cart.add_lines and checkout.buy_now accept the same recipient object on each line, under their existing declared actions. No additional app authority is granted.
Identity, payment and editing safety#
Recipient details are part of line identity, not ordinary line properties or analytics. Different recipients or messages create different lines; increasing quantity buys multiple cards for that same recipient. Always pass the returned line_id/lineId when updating or removing a recipient-specific line. To change its recipient, remove that line and add the replacement. Login cart merging and Buy Now retries retain the selection. Reuse the same mutation ID only for an identical request.
Order creation snapshots the purchase amount, currency, recipient and current expiry policy. Cards are issued idempotently only for a paid, non-test purchase; imported historical orders do not issue new stored value. Delivery may be immediate or scheduled. A provider-submitted status is not a delivery receipt. Catalog changes do not rewrite an order or an already-issued card.
Product detail exposes gift_card_policy.can_edit_value, can_delete and a localized reason. Once any order references a Gift Card product, including an unpaid order, financial fields cannot be edited and the product cannot be deleted (GIFT_CARD_PRODUCT_LOCKED). Archive or unpublish it and create a replacement for another value. Title, description, media, SEO, organization and publication remain editable. Physical inventory, shipping, tax classes, sale prices, quantity discounts and free-gift controls are rejected (GIFT_CARD_PRODUCT_CONTROLS_INVALID). These rules apply equally to Store Admin, mobile, imports and apps.
Catalog changes use the existing products/create, products/update, products/delete and publication webhook topics, carrying is_gift_card where a product object is present. Issued-card lifecycle events remain separate Gift Card topics. Public catalog data, CTX and analytics never expose redeemable codes, code hashes or delivery secrets.