Paddock Cards

Find ordinary and artist cards by artwork, occasion, format or budget. Returns matches with exact design keys and versions, images, orderability, destination prices and next_cursor. Pass destination_country when known; read pricing_destination and cents_by_destination. Basic physical specifications appear once in format_specs; include_specs adds published details. Public browsing needs no account or key. If results is empty, inspect unmet, constraints and pagination before adjusting filters. Pass the selected design key and version to prepare_order.

Prepare one unpaid purchase of 1 to 500 cards, with mixed artwork, formats, messages, recipients, occasions and dates in one cards array. Each card is priced for its recipient country. Returns order.cards, the exact total, a private order_access_token and review_url for buyer review and payment. When preview_available is true, optional preview_card can show the finished card; images render only when requested. This authorizes neither a charge nor mailing. Preserve the returned token privately for retries and follow-up tools. If the first response is lost before saving a server-generated token, use a new request_id for another unpaid purchase. The 500-card/4-MiB bounds are technical request limits. Validation issues identify zero-based card indices without copying private content.

Read one known private purchase using its order ID and matching capability. Returns the current revision, payment state and order.cards with each card’s production and mailing states. Use it to check progress or refresh a stale revision; it does not change the order.

Cancel an eligible purchase or eligible paid cards at the current order revision. Before payment, omit card_ids for whole-purchase cancellation. After payment, omit them for the whole eligible purchase or select returned card IDs. The service checks ownership and each fulfillment cutoff, then returns the actual cancellation and refund states.

Optionally record a technical problem, suggestion or neutral successful outcome using fixed choices. Use after communicating the outcome to the buyer; never required to buy a card. Reports are stored for 30 days and deduplicated daily. Returns recorded or duplicate; TRY_LATER means the daily limit of 100 new reports per server-assigned scope or 500 overall was reached. Do not include personal content, credentials, links, conversations or hidden reasoning. Reports are unverified feedback, not proof of payment or mailing.

Replace an unpaid draft before payment starts. Send the complete desired cards array, including unchanged cards. Validation and replacement are atomic: failure leaves the original draft intact; success cancels it and returns a new order, price, private token and review_url. Use that replacement for later edits, previews and payment; prior payment approval does not carry over. To add private artwork, first reopen the original draft with open_private_content; existing private artwork can be retained. If payment has started or is uncertain, use read_order and resolve it before changing anything. Retry an uncertain revision only with the identical request. The replacement inherits its source’s history access; revision does not link a previously unlinked order.

Show a prepared card’s finished surfaces before payment when preview_available is true. Optional, never required to buy. Returns images and their order revision, plus preview_url for clients that need a browser. Preview again after changes. This does not change, charge or mail the order.

Open a private upload scope for the buyer’s photo, artwork, logo or QR card. Omit both inputs for a new scope, or pass an unpaid order and its token to reopen that draft’s scope. Returns scope_id, a private token, upload_url and expiry. Assistants cannot upload conversation attachments; send the buyer the link, then use read_private_content when they finish. Catalog cards need no upload scope.

List assets and existing card compositions in one private scope after the buyer uploads. Returns asset IDs with their kinds and each composition’s design_key/version. Reuse an existing composition directly; use compose_private_card only for a new face. For a new purchase, prepare_order uses request_id = scope_id and the same token; existing drafts use revise_order. An empty scope returns empty assets and compositions arrays. An expired scope without checkout or payment returns NOT_FOUND; open a new scope to upload again.

Create a new immutable card face from this scope’s artwork, logo or QR URL. Requires at least one of those inputs; a QR-only face needs no upload. Returns design_key and design_version for prepare_order or revise_order. Personal message, recipient and mailing details are supplied in the order’s cards array. Reuse an existing composition when no new face is needed.

Request deletion of unused uploads and compositions in one private scope at the buyer’s request. Returns acceptance and deletion state; it does not cancel an order. Purchased content remains until 90 days after mailing or final cancellation/refund, longer while an order, dispute or legal hold is unresolved.

Start or resume payment for this exact prepared order and revision. Show the exact amount and returned action_url for the buyer to connect Link, approve this purchase or complete bank authentication. Only the buyer can approve; never ask for payment credentials in chat. Call again after that step, respecting retry_after_seconds. Confirm payment only when status is paid; processing and requires_action are incomplete. Changing the order requires a new quote and approval. Use read_order for separate printing and mailing progress.

Find orders first prepared through this assistant connection with history permission, newest first. Replacements inherit their original order’s history access; revising an unlinked order does not add it. Requires a connected buyer who granted orders:read; the public endpoint returns connection instructions. Returns compact order IDs, dates, totals, card counts and payment/refund states, plus next_cursor. Use read_order with a returned order_id for card details and mailing status; no per-order token is needed with history permission. Excludes expired, erased and revoked orders. Reconnecting starts a separate history. Never use names or addresses to find another buyer’s orders.