Guides

August 29, 2026

How to Automate Secret Santa: Match, Buy & Ship (2026)

Elfster handles matching. Learn how to automate Secret Santa buying and shipping with a purchasing API from draw to delivery.

Matching names is a solved app. Buying the gift and shipping it to the right person, without parking every recipient address in a buyer's Amazon account, is not. If you want to automate Secret Santa from the draw through delivery, keep Elfster (or any matcher) for pairings and wishlists, then hand a product URL, a budget, and a ship-to address to a purchasing API.

The matcher never needs the buyer's retail login. The buyer never needs a spreadsheet of home addresses. Zinc places the order as a gift, caps the spend, and returns tracking.

What automated Secret Santa actually covers
Matching tools vs buying and shipping
Architecture: draw, wishlist, order, tracking
How to place the gift order
Limits and mistakes
FAQ

Agent Skilluniversal-checkout

Buy and ship a Secret Santa gift

Add the Universal Checkout skill so your agent can take a match, a budget, and an address, then place a gift order and return tracking.

Install and use the universal-checkout Agent Skill from https://github.com/zincio/skills. Find a premium coffee gift on Amazon under $150 for Jordan Lee at 120 Market Street, Austin, TX 78701. Show me the product and total for approval, then place it as a gift with an idempotency key and track it through delivery.

Setup guide GitHub

What automated Secret Santa actually covers

Secret Santa has three jobs that people mash into one:

Matching. A derangement: everyone gives once, everyone receives once, nobody draws themselves, exclusions hold (couples, managers).
Choosing. A wishlist URL, a budget, or a prompt ("coffee gear under $40").
Buying and shipping. Checkout at a retailer, pack as a gift, send to the recipient's address, get a tracking number back.

Almost every "automate Secret Santa" result on the web stops after step 1. n8n templates pair names and email the assignment. Python scripts shuffle a CSV and hit SMTP. dazfuller/SecretSanta is a .NET global tool that reads participants, assigns recipients, emails each Santa, and writes no local record of the pairs so the organizer stays blind. That is matching. It does not buy a thing.

Office and family exchanges still die in step 3. Someone opens Amazon, pastes an address they should not have stored, forgets is_gift, and screenshots a tracking number into Slack. Remote teams ship late. The organizer becomes a warehouse.

A purchasing API is the execution layer for step 3. Matching stays in Elfster, DrawNames, or your own derangement. Buying happens as a gift order against Amazon, Walmart, Target, or another supported retailer. The same loop works for white elephant, birthday draws, and any "one person buys for another" event.

Matching tools vs buying and shipping

Elfster and DrawNames handle matching. Checkout is still manual unless you wire a purchasing API.

Tool	Matching	Wishlists / ideas	Buys and ships?
Elfster	Name draw, exclusions, anonymous Q&A	Wishlists plus gift recommendations. How Elfster works covers exchanges, wishlists, and ideas	No. You still check out at a retailer. PulseRevOps ranks Elfster as an exchange organizer, not a checkout engine.
DrawNames	App draw, exclusions, no registration	Gift finder and wish lists, budget and date	No. Step 9 on their app page is "See what your target wishes for, and buy them the perfect gift."
SecretSantaOrganizer	Shuffle, email assignment, 17 languages, exclusions	Wishlists and a gift finder. Free, no account	No. Their FAQ is about the draw. The site affiliates Amazon gift cards instead of placing orders.
secretsanta.social	Auto-assign, exclusion rules, shareable group link	Digital wishlists with links and priorities, budget cap	No. Reveal, then "start the gift hunt."
dazfuller/SecretSanta	CSV in, random assign, SMTP out, no local pair file	Email template with `{{name}}`	No. Console matching only. The repo is archived.
Zinc	None. You pass the already-matched recipient	You pass a product URL or let an agent search	Yes. Create Order with `is_gift`, `max_price`, shipping address, tracking webhooks

DrawNames is explicit: after the wish list, the human buys. SecretSantaOrganizer is explicit: they email the secret person. Elfster is the category default for office draws. None of them hold a card and check out at Amazon on your behalf, which is the point. Official Amazon and Walmart APIs are seller tools. They do not let a third-party app complete shopper checkout. See the Amazon API and Walmart API guides if that distinction is fuzzy.

Architecture: draw, wishlist, order, tracking

Keep matching and buying in different systems. The matcher should not store the buyer's Amazon password. The buyer should not store a directory of recipient homes inside a personal retail account.

matcher (Elfster / DrawNames / your script)
  -> pair (santa_id, recipient_id)
  -> wishlist URL or budget + prompt
  -> recipient shipping address (collected by the matcher or a private form)
purchasing API (Zinc)
  -> Create Order (product, max_price, is_gift, address)
  -> webhooks (order.placed, order.tracking_received, order.delivered)
  -> tracking to the Santa only (or to the organizer's ops channel)

1. Run the draw where it already works

Use Elfster, DrawNames, SecretSantaOrganizer, or secretsanta.social if you want a hosted UI. Use a derangement script if you want no SaaS. Exclusions belong here: partners should not draw each other. The organizer can stay blind. dazfuller's README is a clean statement of that goal: no local record of who got whom.

Export or webhook the pair: Santa email, recipient name, budget, wishlist links.

2. Turn the wishlist into a product URL

Three inputs are enough:

A product URL the recipient saved (Amazon, Walmart, Target).
A budget plus a short description, which an agent can search.
A fallback SKU the organizer approved when the wishlist is empty.

Confirm the item is in stock and ships to the recipient's country before you order. Do not trust last week's price. Set max_price to the group cap plus a small tax-and-shipping buffer you agreed in the rules, or fail closed if tax would break the cap.

If you want an AI to pick from the wishlist, that is suggestion plus purchase. See Can AI suggest gifts and buy them? for that split.

3. Collect the ship-to address once, privately

The matcher can collect addresses as part of RSVP. A private form works too. Store them for the event, then delete them. Do not paste twenty home addresses into one person's Amazon address book. That is how Secret Santa becomes an HR incident.

Zinc receives the address on the order. It does not keep a consumer Amazon account in the Santa's name. The gift ships from the retailer to the recipient.

4. Place the order as a gift, then tell only the Santa

Call Create Order. Set is_gift so the packing slip hides prices. If the retailer has no gift checkout, the order fails with gift_option_unavailable. Use one idempotency_key per Santa-recipient pair (a UUID fits). Put exchange_id and santa_id in metadata so finance can reconcile the card without opening the pairs.

Subscribe to webhooks. Email the Santa when order.tracking_received fires. Do not post tracking in the public Slack channel if that would unmask the pair. Ops can watch order.failed in a private channel.

How to place the gift order

Use test mode on a fake pair first. Then run the real list.

curl https://api.zinc.com/orders \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "b3c4d5e6-7f80-41a2-9c3d-eeff00112233",
    "products": [
      {
        "url": "https://www.amazon.com/dp/B0B5F3P45N",
        "quantity": 1
      }
    ],
    "shipping_address": {
      "first_name": "Alex",
      "last_name": "Ng",
      "address_line1": "410 Pine Street",
      "city": "Seattle",
      "state": "WA",
      "postal_code": "98101",
      "country": "US",
      "phone_number": "2065550199"
    },
    "max_price": 4000,
    "is_gift": true,
    "metadata": {
      "campaign": "secret-santa-2026",
      "exchange_id": "exch_88",
      "santa_id": "santa_14",
      "recipient_id": "recv_22"
    }
  }'

Three fields carry the event rules:

max_price (cents) is the group cap. If tax and shipping would exceed it, the order fails instead of "just this once."
is_gift hides prices on the slip. No gift option at checkout means gift_option_unavailable, not a priced box.
idempotency_key makes a timeout safe to retry. Read the idempotency guide.

Orders are asynchronous. Wait for order.placed. If the SKU goes out of stock, swap to the fallback URL with a new key. For returns after the party, use the returns API on the Zinc order, not a merchant portal you do not own.

An agent can sit in the middle. Install the Universal Checkout skill, pass the wishlist and cap, require approval above the cap or for category mismatches, then place the order. For the developer build, see how to build an AI shopping agent. For the consumer "can AI buy this" question, see Can AI buy things online for me?.

Same API as corporate gifting, different trigger. Corporate gifting fires from CRM. Secret Santa fires from a draw.

Limits and mistakes

Zinc buys in-stock retail SKUs. It does not print a custom mug on a 10-day lead, match names, or host the party page. Leave matching in Elfster. Leave handmade Etsy-style items to the human if the lead time is longer than the exchange date.

Common breaks:

Putting recipient addresses in the Santa's Amazon account. Use the API. The Santa should see a product and a tracking number, not a saved-address list of coworkers.
No cap. max_price is the rule you announced in the invite. Enforce it at order time.
Retrying a timeout without an idempotency key. You now have two gifts and a ruined surprise.
Posting tracking in a public channel. You just revealed the pair.
Wishlist links that 404. Resolve the URL at order time. Keep a fallback SKU.
Assuming matching software ships. DrawNames, Elfster, and SecretSantaOrganizer will not check out for you. Plan the purchasing step or you still have a hat draw with extra email.

International addresses, apartment numbers, and PO boxes fail at retailer checkout. Validate the address when you collect it, not on December 22.

FAQ

How can I automate Secret Santa including matching, buying, and shipping?

Split the stack. Use Elfster, DrawNames, SecretSantaOrganizer, secretsanta.social, or a script such as dazfuller/SecretSanta for the draw and wishlists. Then pass the product URL, budget, and recipient address to a purchasing API. Matching is solved. Buying and shipping is the part you add.

Does Elfster buy and ship the gift?

No. Elfster runs the exchange, wishlists, and recommendations. After the reveal, someone still checks out at a retailer. Connect a purchasing API if you want that checkout to be programmatic and keep addresses out of personal Amazon accounts.

Can I keep the draw secret while still automating shipping?

Yes. Collect addresses in the matcher or a private form. Place orders with metadata the organizer can audit without publishing pairs. Send tracking only to the Santa. dazfuller's tool even avoids writing pairs to disk. Your order metadata can stay similarly tight: IDs, not names, in logs.

What if the wishlist item is out of stock or over budget?

Fail on max_price rather than substituting up. Use a backup URL the recipient listed, or ask the Santa to approve a substitute. Do not silently buy a more expensive item. Test mode is the place to rehearse stock misses.

Can an AI agent run the whole exchange?

An agent can search, respect the cap, and call Create Order with is_gift. It should not be the matching algorithm unless you have tests for derangement and exclusions. Keep the draw deterministic and reviewable. Let the agent handle catalog search and checkout, with human approval on the first run.

Next steps

Stand up matching in the tool your group already likes. Collect one address and one wishlist URL per person. Place a single gift order in test mode. When tracking lands in the Santa's inbox, turn the script on for the rest of the list.