--- name: onecheckout-gallery-submission description: Turn a browsed or purchased product, service, ticket, event, travel itinerary, subscription, or SaaS plan into a high-quality OneCheckout Gallery API submission with accurate category, price, image, options, dates, and a replayable MCP request. Use after finding or purchasing something that should be submitted to the OneCheckout gallery. --- # OneCheckout Gallery Submission Purpose: convert real browsing or exploration into a polished, public-safe Gallery API submission. Use this when a user wants to submit a product, service, subscription, event ticket, travel booking, SaaS plan, or other purchasable item to the OneCheckout gallery. The user may either: - complete the purchase and submit it afterward, or - stop before the final irreversible purchase/booking/payment step and submit the discovered item metadata. Either way, preserve enough browser context to go back and capture missing assets, price, options, dates, and images before submitting. ## API endpoint `POST https://onecheckout.ai/api/gallery/submissions` No API key is required. The API is write-only: responses confirm receipt but never disclose moderation status. Field names are accepted in both camelCase and snake_case. Rate limits: - 50 submissions/day per submitter email and per submitter phone (resets 00:00 UTC) - 1 request/second per submitter email and phone - Respect `429` and the `Retry-After` header (seconds) Use a real JSON serializer (`JSON.stringify`, `json.dumps`). Do not hand-build JSON in shell strings. ## Required fields Every submission must include: - `productUrl`: URL for the product, service, event, booking, plan, or offering (http/https) - `sellerName`: merchant, brand, provider, or marketplace name - `productName`: purchased item, offering, event, or plan name - `price`: real numeric price; never null, placeholder, or guessed. Alias `priceAmount` - `submitterEmail`: caller contact email; must contain "@"; kept private - `submitterPhone`: US/Canada phone; must be "+1" followed by 10 digits; kept private ## Strongly preferred fields Higher-quality entries include: - `rootUrl`: site root; auto-derived from `productUrl` when omitted - `selectedOptions`: discrete strings (size, color, tier, route/date, section/row, cabin, room type, quantity). Each option max 120 chars, up to 24 options - `quantity`: whole units, minimum 1 - `description`: public-safe longer description, max 2000 chars - `currency`: 3-letter ISO 4217, defaults to `USD` - `priceInterval`: one of `once`, `day`, `week`, `month`, `quarter`, `year` - `imageUrl`: direct-openable product/poster image - `textPoster`: `true` for poster/card artwork that should not be cropped - `category`: one exact value from the taxonomy below when it applies - `eventDate`: required for ticketed, timed, or scheduled events and activities - `sourcePlatform`: where the buy button lived (ad network, chat, article) - `mcpRequest`: a replayable purchase request (see below) - `buyerDisplayFirstName`: first name for public attribution - `buyerDisplayLastInitial`: last initial only, never a full last name - `purchasedAt`: ISO 8601 timestamp - `submitterRef`: your own reference / partner id Do not send deprecated fields: `variant`, `buyerDisplayName`. ## Core workflow 1. Browse to the real product/service/event/booking page. 2. Capture metadata before leaving the page: URLs, seller name, item name, selected options as discrete strings, quantity, price (with taxes/fees/shipping and what is included), date(s), a high-quality image URL, and a public-safe buyer attribution. 3. If the user intends to purchase, continue through checkout. Keep enough context to return for missing assets. 4. If stopping before final purchase, stop at the last reversible step before actions such as Place order, Pay, Confirm purchase, Subscribe, Book, Reserve, Buy tickets, or Complete order. 5. Build a public-safe JSON payload. 6. Validate price, category, image, dates, and `mcpRequest`. 7. POST the submission with a real JSON serializer. 8. Treat HTTP `201` with an `id` as accepted for review. Do not infer public approval. ## Price rules Price is a hard gate. - Ecommerce/tickets/travel: prefer the final visible checkout total, including taxes/fees/shipping when available. - If final taxes/fees only appear after an irreversible submit, use the highest confirmed pre-submit total or visible fare/seat price, and explain what is included/excluded in `description`. - SaaS/subscriptions: use the plan price and set `priceInterval` correctly. Mention trial terms, setup fees, or usage billing in `description`. - Tickets/events/travel: choose a real date/seat/fare/room/cabin option and get a real price. If one option hides price or is sold out, choose another. - Do not submit without a real numeric `price`. ## Image rules (critical) Image quality often decides whether an entry is useful. Hard gates: - `imageUrl` must direct-open and fetch successfully (2xx, an image `Content-Type`, usable bytes). - Avoid broken, expiring, hotlink-blocked, internal, transformed, HTML/error-page, tiny, or placeholder URLs. - Avoid images over 380 KB or wider/taller than 6,000 px. Choose an official smaller CDN variant when needed. - If `Content-Length` is missing, download to a temp file and check byte size. Use local image tools (`sips`, PIL, ImageMagick) to check dimensions when needed. Best source by category: - Product/event/property/booking detail pages: start with the detail-page OG/Twitter image; it is usually the most stable thumbnail. - Event marketplaces (Eventbrite-like): prefer the event detail page OG image; still validate direct-open and size. - Hotels/properties: prefer the property overview OG image or hero photo, not random stock. - SaaS/API: pull price from the pricing page, but for artwork use the root/home OG image; avoid pricing-page thumbnails. - Ecommerce: use the PDP hero/gallery image; prefer lifestyle imagery when relevant. - Tickets/events: use official poster/key art, team/show artwork, or the ticketing PDP OG image. - Flights/travel: use plane/cabin/route/destination/hotel/cruise imagery. Avoid credit-card ads and unrelated banners. - Streaming/media: a flagship title image beats a generic logo. ## Dates and event/travel handling Use `eventDate` for any ticketed, timed, or scheduled event/activity/show/movie/sport/conference/experience. - Format: `YYYY-MM-DD` (event start date only; no time or timezone). - Prefer events at least 7 days in the future. - Same-day or past events are poor candidates: ticketed submissions without an `eventDate` are rejected in review, and any event dated today or earlier (evaluated in US Pacific time) is automatically removed. For travel, category is usually `travel`: - flights, trains, cruises, hotels/stays, theme parks, attractions, tours, museums - include route/dates/stay/sailing/visit details in `selectedOptions` and `description` - include `eventDate` when the travel product is ticketed/timed (attraction, tour, cruise departure, flight departure) Travel and event options are abundant. Do not block because one listing is inconvenient; change date, route, room, cabin, seat, provider, venue, or activity. ## Category taxonomy Use one exact value whenever it applies. Send the exact slug shown. Always prefer the most specific category that fits the actual item. Use `shopping` only as a last resort for a physical ecommerce purchase that genuinely fits no more specific category. Custom categories are only for genuinely new products; anything unrecognized is shown generically in the gallery. - `accessories`: Bags, belts, watches, and small goods. - `api`: Developer APIs, SDKs, and usage-based developer platforms. - `apparel`: Clothing and wearables. - `automotive`: Vehicles, parts, and accessories. - `beauty`: Cosmetics, skincare, and grooming. - `books media`: Physical books, print, and physical media. - `cloud services`: Cloud hosting, storage, and infrastructure. - `consumer services`: Non-physical consumer services and memberships. - `digital services`: Digital-only services and online tools. - `electronics`: Devices, gadgets, and hardware. - `events`: Conferences, shows, and experiences. - `financial services`: Fintech, banking, and financial service subscriptions. - `fitness`: Fitness gear, equipment, and training products. - `food beverage`: Food, drink, and consumables. - `footwear`: Shoes, sneakers, and boots. - `furniture`: Furniture and large home items. - `gaming`: Digital games, in-game goods, and game subscriptions. - `health wellness`: Supplements and physical wellness products. - `home`: Homeware, kitchen, and household goods. - `insurance`: Insurance policies and coverage plans. - `jewelry`: Jewelry and fine accessories. - `memberships`: Membership and community access plans. - `online courses`: Courses, cohorts, and digital learning. - `pet`: Products for pets and animals. - `saas`: Software-as-a-service products and platforms. - `shopping`: General ecommerce purchases that don't fit a more specific category. - `software`: Downloadable or licensed software and apps. - `sporting goods`: Sports, fitness, and outdoor gear. - `streaming`: Streaming video, music, and media subscriptions. - `subscriptions`: Recurring subscription plans not covered by another bucket. - `telecom`: Mobile, internet, and connectivity plans. - `tickets`: Event tickets (usually poster/card artwork). - `toys games`: Physical toys and tabletop games. - `travel`: Flights, stays, and travel bookings. ## Public-gallery taste Most callers submit what they are actually buying. Preserve that real buyer intent; do not swap the item just to manufacture variety for a one-off submission. If submitting multiple items for a collection, avoid repetition: - Mix product/service/event/travel types. - Avoid many entries from the same marketplace, team, venue, artist, or product family. - For events, mix concerts, sports, comedy, theater, family, festivals, conferences, and experiences. - Do not submit the same event across multiple marketplaces unless the purpose is explicit comparison. ## Description rules Write `description` for a public gallery reader. Good descriptions include: what the item/plan/ticket/booking is, selected options and date/time context, what the price includes/excludes, and trial/subscription terms when relevant. Do not mention internal agent mechanics, private notes, secrets, browser steps, or whether a purchase was stopped before final submission. ## MCP request Include a replayable `mcpRequest` when available. It should represent buyer intent that another MCP client could execute. Preferred shape: ```json { "method": "tools/call", "params": { "name": "card_task_start", "arguments": { "parameters": { "task": "Buy one adult ticket for the San Francisco Symphony on August 15, 2026, choosing a reasonably priced orchestra or balcony seat.", "url": "https://www.example.com/event" } } } } ``` Rules: - Use `method: "tools/call"` and `params.name: "card_task_start"` for the OneCheckout/OneText purchase-start flow. - Include `parameters.task`; include `parameters.url` when useful. - Do not include card numbers, OTPs, raw credentials, screenshots, or secrets. - Do not put internal safety instructions in the request. Describe what the user wants to buy, not agent-side control flow. ## Example payload ```python import json, urllib.request payload = { "productUrl": "https://www.ticketmaster.com/example-event", "rootUrl": "https://www.ticketmaster.com", "sellerName": "Ticketmaster", "productName": "Artist Name: World Tour", "submitterEmail": "dev@example.com", "submitterPhone": "+14155550123", "selectedOptions": ["1 ticket", "Section 104", "Row 12", "Event date: 2026-08-15"], "quantity": 1, "description": "One ticket for Artist Name at Example Arena on Aug 15, 2026. Price includes visible marketplace fees before final checkout.", "price": 189.50, "currency": "USD", "priceInterval": "once", "imageUrl": "https://cdn.example.com/event-poster-1200.jpg", "textPoster": True, "category": "tickets", "eventDate": "2026-08-15", "sourcePlatform": "Ticketmaster", "mcpRequest": { "method": "tools/call", "params": { "name": "card_task_start", "arguments": { "parameters": { "task": "Buy one ticket for Artist Name at Example Arena on August 15, 2026, choosing a reasonably priced seat.", "url": "https://www.ticketmaster.com/example-event" } } } }, "buyerDisplayFirstName": "Alex", "buyerDisplayLastInitial": "R", "purchasedAt": "2026-08-01T18:30:00Z", "submitterRef": "partner-run-artist-example-20260815", } req = urllib.request.Request( "https://onecheckout.ai/api/gallery/submissions", data=json.dumps(payload).encode("utf-8"), headers={"Content-Type": "application/json"}, method="POST", ) with urllib.request.urlopen(req, timeout=30) as res: print(res.status, res.read().decode()) ``` ## Responses - `201`: accepted for review; body has an `id` and a generic message. Never implies public approval. - `422`: validation failed; body has a `details` array. Does not count against your quota. - `429`: rate limit exceeded; includes a `Retry-After` header in seconds. - `400`: invalid JSON body. ## Pre-submit checklist - [ ] Required fields present: `productUrl`, `sellerName`, `productName`, `price`, `submitterEmail`, `submitterPhone`. - [ ] `price` is real, numeric, non-null, and described accurately. - [ ] `category` is one of the normalized slugs whenever possible. - [ ] `selectedOptions` are discrete and enough to identify the exact choice. - [ ] `eventDate` is present for ticketed/timed/scheduled events. - [ ] Travel entries include route/date/stay/sailing/visit details. - [ ] `imageUrl` direct-opens as an image, is not broken/hotlink-blocked, is under 380 KB, and under 6,000 px. - [ ] `description` is public-safe with no internal/private agent-process language. - [ ] `mcpRequest` is replayable, public-safe, and contains buyer intent only. - [ ] No deprecated fields (`variant`, `buyerDisplayName`). - [ ] No secrets, full last names, card data, order numbers, or private notes in public-facing fields. ## Human docs A human-readable version of this reference lives at https://onecheckout.ai/docs/gallery-api.