Developers
Team orders and webhooks over the Partner API
For gifting platforms and agencies: create a team order for your client with one call (a bundle, many recipients, claim links, printed card, event date), pay through your partner billing mode, follow every gift with signed webhooks, and cancel before production.
The Partner API already lets an approved partner submit single orders that Printonic prints, packs and ships from Chatsworth, California, charged to a prepaid wallet or on net terms. Team orders add the corporate gifting shape on top: one bundle, many recipients, one charge, with the same claim links, printed card, event date, rush and kit assembly options a team gets in the Printonic dashboard.
This guide is the walkthrough. The request and response reference, the webhook signature sample and the error codes are on platform.printonic.com/docs/partner/team-orders.
- 1
Printonic partner team
Get a partner key with the team_orders capability
Partner keys (pk_live_...) are issued by Printonic and bound to your Printonic account, the wallet that team orders are charged against. New keys carry the team_orders capability; ask us to enable it on an older key. Send the key as Authorization: Bearer on every request.
team_orders covers the team order endpoints and webhook management. Charges follow your key's billing mode: prepaid (wallet, then your default saved card) or net terms (up to your credit limit, settled later). - 2
POST /api/external/custom-listings and POST /api/external/gift-sets
Create the products every recipient receives
A team order ships your own merchant SKUs. Create them once from a catalog product (with the client's artwork baked in) or assemble a gift set, and keep the merchant_sku_id or sku_code the response returns. A team order can also point at a merchant_product_id and let each recipient choose an option such as size.
Pricing is always server-side; the request never carries an amount. - 3
POST /api/external/team-orders
Create the team order
Send the bundle (items), the recipients, and an idempotency_key. Recipients either all carry an address (the gifts ship after payment) or all come as name and email (each gets a personal claim link and enters their own address; nothing ships until it arrives). Add destination_countries for links, card { message, sender } for a printed card in every parcel, event { date, rush, kit_assembly } for a deadline, and po_number or reference for your client's paperwork.
The response lists the team order, every recipient with its claim status, the totals and what was charged. Claim links are never returned unless you send return_claim_links: true; they are the recipient's only credential, so store them like passwords. - 4
idempotency_key
Retry safely
Repeat the same idempotency_key with the same body to recover from a lost response; you get the original result, never a second charge. The same key with a different body is a 409. A 402 (insufficient funds, credit limit, daily cap) leaves the team order created but unpaid: fund the account and retry with the same key, or cancel it.
If a response says the outcome is unknown (a code plus a payment_reference), do not reuse that key; verify your billing, then use a new one. - 5
GET /api/external/team-orders/{id} and /manifest.csv
Follow every gift
The detail call returns the team order status (collecting_addresses, in_progress, shipped, delivered, canceled), the recipient rollup, and every recipient with claimed, shipped and delivered timestamps, carrier and tracking, and on time against the event date. The manifest.csv call returns the finance spreadsheet a team downloads from the dashboard.
GET /api/external/team-orders lists the account's team orders with paging and an optional status filter. - 6
POST /api/external/webhooks
Subscribe to webhooks instead of polling
Register an https endpoint and the events you want: team_order.claimed, team_order.shipped, team_order.delivered, team_order.needs_attention (a delayed or rejected shipment, or a claim link that expired unclaimed), plus order.shipped and order.delivered for single partner orders. The response shows the signing secret once. Every delivery carries X-Printonic-Signature: t=<timestamp>,v1=<HMAC-SHA256 of "<timestamp>.<body>">; verify it with the secret and reject timestamps older than five minutes.
Deliveries are sourced and sent hourly and retried on a backoff schedule (5 minutes to 48 hours, eight attempts) before they are marked dead. POST /api/external/webhooks/{id}/test sends a signed ping so you can check your verification. - 7
POST /api/external/team-orders/{id}/cancel
Cancel before production
Cancel every recipient still before production, or only the recipient_ids you list. Each canceled shipment's share of the payment goes back to the wallet first (on net terms that reduces the outstanding balance), then to the card. Shipments already in production or shipped are reported as skipped with the reason.
Once a label is printed the address cannot change and the shipment cannot be canceled; contact Printonic if the parcel has not actually left.
Good to know
- Name the team order after your client's campaign and put their reference in `reference`; both come back on every read and in the manifest.
- For events, send event.date and let the API compute must-ship-by per recipient; add rush when the calculator on printonic.com/teams/events says it is needed.
- Keep one webhook endpoint per environment and rotate by creating a new endpoint, switching, then deleting the old one.
Common questions
Which countries can recipients be in?
United States, Canada, United Kingdom, Australia, Germany, France, Netherlands, Italy and Spain. Each recipient is priced as its own shipment at its country's rate; duties on international gifts are paid by the recipient on delivery.
How many recipients per team order?
Up to 100, counting shared-link seats. Split larger sends into several team orders.
What does a webhook payload contain?
The team order (id, name, your reference, recipient count), the recipient (name, email, company, choice) and the shipment (order id, status, carrier, tracking, timestamps). Never a claim link.
Can I see team orders created in the dashboard?
Yes. The list and detail calls return every team order on the account; created_via says whether it came through the API or the dashboard.
Related guides
Send one gift to many people with a team order
Pick a gift, add your recipients, pay once. Send each person a link so they enter their own shipping address and pick a size, or upload a spreadsheet of addresses in the US, Canada, the UK, Australia, Germany, France, the Netherlands, Italy or Spain. Add a printed card to every parcel, download a quote with your PO number, and export the manifest for finance.
Give an AI assistant access with Agent Access
Create a scoped API key so Claude, Cursor, ChatGPT, or another AI assistant can search the catalog, see your stores and products, draft listings, and propose publishes and orders that wait for your approval, all limited to your own account.
Plan an order for a trade show, conference or launch event
Check the date first, then choose bulk to the venue or one parcel per attendee. Rush production, venue delivery windows with a booth number, mixed sizes in one grid, and kit assembly are all built in.