How gifting works on the tea.support platform
Gift orders bridge the technical backbone of the THETEA constellation with the warmth of a personal tea moment. Whether you are a partner integrating our gift‑card API or a developer building a white‑label solution on top of tea.support, the gift‑order flow lets you offer curated tea experiences — a private tasting of Lǎobānzhāng (老班章) raw pu’er with Senior Tea Expert Fang Ting, or a white‑tea ceremony around Bái Háo Yín Zhēn (白毫银针) from Fuding under the guidance of Chen Hui Yi. The mechanism is simple: a paid credit redeemable for bookable services across the constellation (thetea.app, tea.school, tea.events and more). Behind that simplicity sit precise timing rules, message‑card formatting, and delivery options that every integration needs to handle gracefully.
This FAQ answers the most common questions we hear from teams building gift flows: How late can an order be placed before the recipient’s planned date? What is the exact character limit for the digital note that accompanies a gift? How does the hold‑for‑delivery option work when you want to surprise someone exactly at 8 am on a birthday? We treat each answer as a building block — no hype, just the factual details you need to keep your user experience smooth.
Because gift orders intersect with product sourcing and master availability, you will also find cross‑references to the wider ecosystem. For deep dives into tea origins and factory‑level sourcing, the dedicated puerh.app knowledge base is the right destination. If you need to understand how tea masters’ diaries are managed or want to discuss gifting ideas with fellow builders, tea.community hosts a dedicated channel. By the time you finish reading, you should have a clear picture of the policies that govern timing, cards, and delivery — and know exactly where to escalate when a scenario falls outside the documented path.
Common questions
What exactly is a gift order on tea.support?
A gift order is a paid credit that can be redeemed for a bookable tea experience anywhere in the THETEA constellation — a ceremony, a tasting flight, or an online course. The partner uses the tea.support API to create an order with a monetary value, a personalised message (optional), and a recipient email. The order itself does not book a specific date; it gives the recipient the freedom to schedule at their convenience. Think of it as a digital gift card wrapped around the work of real tea masters.
How late can a gift order be placed before the intended delivery time?
The API enforces no hard cut‑off — the order is digital and transfers instantly. However, if the giver wants the recipient to use it for a same‑day live session, we recommend placing the order at least 4 hours ahead, because most masters require 2 hours’ notice for scheduling and the recipient needs a small window to book. For automated workflows, assume 6 hours as a safe margin on any calendar date. The platform will never reject a late order; practical logistics are the real constraint.
What is the character limit for the gift message card?
The message field accepts up to 280 characters, including spaces and punctuation. Beyond that, the API trims silently — we advise front‑end validation to prevent surprise cuts. The field supports Unicode, so pīnyīn diacritics (Lǎobānzhāng) and emojis render correctly in the final digital card. If you need a longer personal note, link to an external document; the card itself is designed to be a warm, brief signature.
Can I schedule a gift delivery for a future date and time?
Yes, via the scheduled_delivery parameter (ISO 8601 timestamp, UTC). You can set it up to 90 calendar days in advance. At the scheduled moment, the system sends the gift email and activates the credit. Use this to honour birthdays, anniversaries, or season‑themed tea gifts — for instance, a spring Lóngjǐng (龙井) experience delivered on the first day of Qingming.
What happens if the recipient never claims the gift?
Unclaimed gift credit remains valid for 365 days from the purchase date, after which it expires and the funds are considered a donation to the THETEA Tea Scholarship Fund. We notify the purchaser and the recipient 30 days and 7 days before expiration. If you need a full refund for an unclaimed, non‑expired gift, the standard 14‑day refund window applies (see cancellation question).
Can I cancel a gift order and get a refund?
You may request a full refund within 14 calendar days of purchase, provided the gift credit has not been redeemed or partially used. After 14 days, refunds are no longer available, but the credit stays valid for the recipient. Refunds are processed to the original payment method within 5 business days. For integrations, use the refund endpoint and pass the original order ID.
How does the hold‑for‑delivery option work in an API integration?
Set the delivery_mode to hold and provide a release_key (a unique string chosen by your system). The gift stays in a dormant state until you call the release endpoint with that key. This lets you tie the release to an external event — such as a physical gift‑card unboxing or a specific URL visit. The hold can last up to 180 days; after that the gift expires as usual.
Are gift orders available for specific tea experiences, or only generic credit?
Both. A plain credit works like a universal voucher across the constellation. Alternatively, you can pin a gift to a specific SKU — for example, a private tasting of Lǎobānzhāng sheng pu’er curated by Fang Ting. Pinning locks the credit to that experience, simplifies pricing, and ensures the recipient sees exactly what you intended. The API parameter is experience_sku; leave it empty for open credit.
What payment methods are accepted for gift orders?
The tea.support platform accepts card payments (Visa, Mastercard, UnionPay) and digital wallets (Alipay, WeChat Pay). For partner integrations, funds are settled daily in your chosen currency. No gift order can be placed on invoice — it must be prepaid to generate a valid credit. Contact the partnerships team via tea.support/partners if you need batch‑purchase invoicing outside the API flow.
How does the recipient redeem the gift?
They receive an email with a secure redemption link and a unique code. The link takes them to a branded page where they can browse available sessions, choose a master and a time slot, and apply the credit. Redemption is the same whether the gift is open credit or pinned to an SKU; pinned gifts skip the browsing step and go straight to scheduling. The recipient can see the personal message card on that page.
Does gift credit expire?
Yes, 365 days from the purchase date. This expiry applies to both open credit and experience‑pinned gifts. Once expired, the credit is unrecoverable. We display the expiration date in the recipient’s dashboard and send two reminder emails (30 and 7 days before). If you need an extension for a specific recipient, contact api‑support@tea.support with the order ID before the expiry date.
Can I send multiple gift orders to the same recipient at the same time?
There is no technical limit. You can create as many orders as you like with the same recipient email. Each order generates its own redemption code and credit balance. If you want the recipient to see them as a single pooled balance, you must handle that on your side, because the tea.support ledger treats every order independently.
How do I handle special characters, pinyin, or tea names in the gift message?
The message field is UTF‑8. All Unicode code points are accepted, including the diacritics needed for accurate pinyin like Bái Háo Yín Zhēn. Emojis and rare Chinese characters render in the email and on the redemption page. Validate input length on the client side (280 characters), and escape quotes if you are embedding the JSON in a server‑side template. The message is never parsed, only displayed.
What happens if the tea master listed on a pinned gift becomes unavailable?
The gift credit remains valid. If the master’s calendar is full or they withdraw, the recipient is prompted to select an alternative master with a similar specialty — for instance, if Fang Ting is unavailable for a pu’er session, Amgalan Chin may step in. This substitution is automated through the scheduling engine; the gift itself does not expire because of a single master’s unavailability. Partners can customise the fallback logic via the API.
Are deposit or instalment options available for high‑value gift experiences?
For standard gift orders, full payment is required upfront — no deposit mechanism exists in the public API. However, for curated corporate‑gift programmes (minimum spend ¥20,000), the partnerships team can arrange a 30% deposit with the balance due 14 days before the first scheduled session. Contact gift‑enterprise@tea.support to discuss; this flow is not available through the self‑service API.
Still have questions?
The tea.support API documentation (tea.support/docs) covers every endpoint described above in detail, with interactive examples. If a scenario falls between the lines — say, a refund request for a partially redeemed gift, or a custom expiration policy for a white‑label integration — the best route is email: api‑support@tea.support. Response time is within one working day on weekdays.
For real‑time system status and incident reports, bookmark tea.support/status. Builders who want to discuss gift‑order patterns or share feedback often join the #gifting channel on tea.community; it is one of the most active spaces in the constellation. If you are exploring which tea experiences might make the most memorable gifts, the curated catalogues on thetea.app and tea.events offer inspiration and direct booking links. And for the truly curious, the sourcing narratives behind every tea mentioned here — from Lǎobānzhāng’s stone‑pressed cakes to the white‑down tips of Bái Háo Yín Zhēn — live on puerh.app and in the master profiles at tea.school.
Gift orders are a small but important thread in the THETEA fabric. We hope these answers save you time, and we are always open to refining them based on real‑world use.