Paddock Cards MCP
An official MCP server by Paddock that allows AI assistants to search a catalog of greeting cards, prepare personalized orders with specific formats and messages, and facilitate payment via Stripe Link or secure checkout. It supports sending up to 500 cards in a single order and tracking status.
Endpoint and access
No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.
MCP endpoint (Streamable HTTP)
https://api.paddock.so/agent-commerce/mcpWhat you can do with it
- Search for greeting cards by occasion or style
- Prepare an order with personalized messages and recipient details
- Facilitate payment via Stripe Link or secure checkout
- Track printing and mailing status of orders
Source and maintenance
Vendor evidenceRegistry 0.1.4
Protocol and capabilities
- Server
- paddock-cards 1.4.0
- MCP protocol
- 2025-06-18
- Tools
- 13 advertised
- Resources
- 1 advertised
- Resource templates
- 0 advertised
- Prompts
- 2 advertised
Server-advertised capabilities
{
"tools": {
"listChanged": false
},
"prompts": {
"listChanged": false
},
"resources": {
"subscribe": false,
"listChanged": false
}
}Server-provided instructions
Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.
Tools
13 advertised
search_cards — Search cards
Advertised read-only
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.
search_cards input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"kind": {
"enum": [
"any",
"standard",
"artist"
],
"type": "string",
"description": "Catalog collection: standard for Paddock cards, artist for artist cards, or any for both. Omission means any."
},
"tone": {
"type": "string",
"maxLength": 40,
"description": "Mood such as warm, cheerful, elegant or gentle. For funny cards, use humor instead."
},
"humor": {
"enum": [
"any",
"none",
"light",
"playful",
"funny"
],
"type": "string",
"description": "Humor filter: none, light or playful selects that reviewed level; funny accepts light and playful. Omit or use any for no explicit humor filter; the query can still request humor."
},
"limit": {
"type": "integer",
"default": 3,
"maximum": 50,
"minimum": 1,
"description": "Maximum matches in this page, from 1 to 50. Omission returns 3; use next_cursor for more."
},
"query": {
"type": "string",
"maxLength": 300,
"description": "Natural-language artwork request, such as a birthday card with flowers. Can include an occasion, format, color, subject or exclusions. Omit to browse with the other filters."
},
"artist": {
"type": "string",
"maxLength": 120,
"description": "Published artist name or slug, such as one returned in card.artist. Omit to include all artists and standard cards."
},
"cursor": {
"type": "string",
"pattern": "^(?:\\d{1,6})?$",
"description": "Exact next_cursor from the previous search with the same filters. Omit for the first page; stop when next_cursor is null."
},
"format": {
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
],
"type": "string",
"description": "Requested card format. Omit to use a format named in query, or flat_card_in_envelope when no format is requested. Other formats remain listed on each result."
},
"occasion": {
"type": "string",
"maxLength": 100,
"description": "Occasion ID or recognized name, such as birthday or thank_you. Omit to use the query or browse all occasions."
},
"include_specs": {
"type": "boolean",
"description": "Include available paper, finish and envelope details. Basic format specifications are always returned. A missing detail is unspecified."
},
"max_price_cents": {
"type": "integer",
"maximum": 1000000,
"minimum": 0,
"description": "Budget per card for the selected format at the destination’s prices."
},
"destination_country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Recipient country as a two-letter ISO code, such as US or CA. Prices depend on it: US addresses have agent-channel introductory prices and other countries the standard prices. Omit it to see US prices with each format’s other-destination amount listed; the prepared order prices every card by its own recipient address."
},
"require_printed_text": {
"enum": [
"any",
"absent",
"present"
],
"type": "string",
"description": "Filter verified wording already printed in the artwork. Unknown wording does not match absent or present."
},
"printed_text_contains": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Required phrase in verified artwork lettering, matched without case sensitivity. This does not search the customizable message."
}
},
"additionalProperties": false
}search_cards output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"ok",
"data"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"required": [
"schema",
"catalog_revision",
"complete",
"generated_at",
"total",
"next_cursor",
"constraints",
"unmet",
"occasion_resolved",
"artist_resolved",
"pricing_destination",
"currency",
"price_includes",
"policy",
"results",
"format_specs"
],
"properties": {
"total": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"unmet": {
"type": "array",
"items": {
"type": "object",
"required": [
"code",
"detail"
],
"properties": {
"code": {
"type": "string"
},
"detail": {
"type": "string"
}
},
"additionalProperties": false
}
},
"policy": {
"type": "string"
},
"schema": {
"type": "string",
"const": "paddock.search.compact.v1"
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"card",
"selected_format",
"total_cents",
"score",
"match_reasons"
],
"properties": {
"card": {
"type": "object",
"required": [
"card_id",
"kind",
"design",
"title",
"primary_occasion",
"occasions",
"description",
"printed_text",
"tone",
"humor",
"subjects",
"palette",
"contains_people",
"contains_animals",
"image",
"formats",
"from_cents"
],
"properties": {
"kind": {
"enum": [
"standard",
"artist"
],
"type": "string"
},
"tone": {
"type": "array",
"items": {
"enum": [
"warm",
"cheerful",
"playful",
"elegant",
"calm",
"gentle",
"romantic",
"festive",
"nostalgic",
"whimsical",
"sincere",
"celebratory",
"serene",
"bold"
],
"type": "string"
}
},
"humor": {
"enum": [
"none",
"light",
"playful",
"unknown"
],
"type": "string"
},
"image": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"artist": {
"type": "object",
"required": [
"name",
"slug",
"url"
],
"properties": {
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"name": {
"type": [
"string",
"null"
]
},
"slug": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"design": {
"type": "object",
"required": [
"key",
"version"
],
"properties": {
"key": {
"type": "string"
},
"version": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"card_id": {
"type": "string"
},
"formats": {
"type": "array",
"items": {
"type": "object",
"required": [
"format",
"cents",
"orderable",
"cents_by_destination"
],
"properties": {
"cents": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"format": {
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
],
"type": "string"
},
"reason": {
"enum": [
"CARD_SAMPLE_ACCEPTANCE_REQUIRED",
"CARD_ARTWORK_ACCEPTANCE_REQUIRED",
"ARTIST_PRINT_SETUP_REQUIRED",
"CATALOG_ARTWORK_UNAVAILABLE",
"OFFER_EXPIRED",
"AVAILABILITY_UNVERIFIED"
],
"type": "string"
},
"orderable": {
"type": "boolean"
},
"cents_by_destination": {
"type": "object",
"propertyNames": {
"enum": [
"US",
"international"
],
"type": "string"
},
"additionalProperties": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
}
}
},
"additionalProperties": false
}
},
"palette": {
"type": "array",
"items": {
"type": "string"
}
},
"subjects": {
"type": "array",
"items": {
"type": "string"
}
},
"subtitle": {
"type": "string"
},
"occasions": {
"type": "array",
"items": {
"type": "string"
}
},
"from_cents": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
]
},
"description": {
"type": "object",
"required": [
"status",
"text"
],
"properties": {
"text": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"available",
"unknown"
],
"type": "string"
}
},
"additionalProperties": false
},
"printed_text": {
"type": "object",
"required": [
"status",
"text"
],
"properties": {
"note": {
"type": "string"
},
"text": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"verified_absent",
"verified_present",
"unknown"
],
"type": "string"
}
},
"additionalProperties": false
},
"contains_people": {
"type": [
"boolean",
"null"
]
},
"contains_animals": {
"type": [
"boolean",
"null"
]
},
"primary_occasion": {
"type": "string"
},
"occasion_design_keys": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"additionalProperties": false
},
"score": {
"type": "number"
},
"total_cents": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "null"
}
]
},
"match_reasons": {
"type": "array",
"items": {
"type": "string"
}
},
"selected_format": {
"anyOf": [
{
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
],
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"maxItems": 50
},
"complete": {
"type": "boolean"
},
"currency": {
"type": "string",
"const": "usd"
},
"constraints": {
"type": "array",
"items": {
"type": "object",
"required": [
"code",
"detail"
],
"properties": {
"code": {
"type": "string"
},
"detail": {
"type": "string"
}
},
"additionalProperties": false
}
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"format_specs": {
"type": "object",
"required": [
"version",
"unit",
"detail",
"unspecified_means",
"formats"
],
"properties": {
"unit": {
"type": "string",
"const": "in"
},
"detail": {
"enum": [
"basic",
"full"
],
"type": "string"
},
"formats": {
"type": "object",
"required": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
],
"propertyNames": {
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
],
"type": "string"
},
"additionalProperties": {
"anyOf": [
{
"type": "object",
"required": [
"version",
"format",
"title",
"paper",
"size_in",
"artwork_surface",
"message_surface",
"envelope_included",
"paper_detail",
"personalization",
"printed_text"
],
"properties": {
"paper": {
"type": "string",
"description": "Card stock by its confirmed basis-weight designation."
},
"title": {
"type": "string"
},
"format": {
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
],
"type": "string"
},
"size_in": {
"type": "object",
"required": [
"width",
"height"
],
"properties": {
"width": {
"type": "number",
"exclusiveMinimum": 0
},
"height": {
"type": "number",
"exclusiveMinimum": 0
}
},
"description": "Finished size in inches; the closed size for the folded card.",
"additionalProperties": false
},
"version": {
"type": "string",
"maxLength": 60,
"minLength": 1
},
"envelope": {
"type": "object",
"required": [
"size_in",
"addressing"
],
"properties": {
"size_in": {
"type": "object",
"required": [
"width",
"height"
],
"properties": {
"width": {
"type": "number",
"exclusiveMinimum": 0
},
"height": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"addressing": {
"type": "string"
}
},
"description": "Present only for formats mailed in an envelope.",
"additionalProperties": false
},
"open_size_in": {
"type": "object",
"required": [
"width",
"height"
],
"properties": {
"width": {
"type": "number",
"exclusiveMinimum": 0
},
"height": {
"type": "number",
"exclusiveMinimum": 0
}
},
"description": "Folded card only: size when opened.",
"additionalProperties": false
},
"paper_detail": {
"type": "object",
"required": [
"basis_weight"
],
"properties": {
"gsm": {
"type": "number",
"description": "Manufacturer-stated grammage; absent when unknown.",
"exclusiveMinimum": 0
},
"color": {
"type": "string",
"description": "Absent until confirmed for the stock in use."
},
"finish": {
"type": "string",
"description": "Absent until confirmed for the stock in use."
},
"caliper_in": {
"type": "number",
"description": "Measured sheet thickness in inches; absent when unknown.",
"exclusiveMinimum": 0
},
"basis_weight": {
"type": "string"
}
},
"additionalProperties": false
},
"printed_text": {
"type": "string"
},
"artwork_surface": {
"enum": [
"front",
"front cover"
],
"type": "string"
},
"message_surface": {
"type": "string",
"description": "Where Paddock prints the personal message."
},
"personalization": {
"type": "object",
"required": [
"fonts",
"automatic_greeting",
"max_message_chars",
"fit_check"
],
"properties": {
"fonts": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"fit_check": {
"type": "string"
},
"max_message_chars": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"automatic_greeting": {
"type": "string"
}
},
"additionalProperties": false
},
"envelope_included": {
"type": "boolean"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"version",
"format",
"title",
"paper",
"size_in",
"artwork_surface",
"message_surface",
"envelope_included"
],
"properties": {
"paper": {
"type": "string",
"description": "Card stock by its confirmed basis-weight designation."
},
"title": {
"type": "string"
},
"format": {
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
],
"type": "string"
},
"size_in": {
"type": "object",
"required": [
"width",
"height"
],
"properties": {
"width": {
"type": "number",
"exclusiveMinimum": 0
},
"height": {
"type": "number",
"exclusiveMinimum": 0
}
},
"description": "Finished size in inches; the closed size for the folded card.",
"additionalProperties": false
},
"version": {
"type": "string",
"maxLength": 60,
"minLength": 1
},
"open_size_in": {
"type": "object",
"required": [
"width",
"height"
],
"properties": {
"width": {
"type": "number",
"exclusiveMinimum": 0
},
"height": {
"type": "number",
"exclusiveMinimum": 0
}
},
"description": "Folded card only: size when opened.",
"additionalProperties": false
},
"artwork_surface": {
"enum": [
"front",
"front cover"
],
"type": "string"
},
"message_surface": {
"type": "string",
"description": "Where Paddock prints the personal message."
},
"envelope_included": {
"type": "boolean"
}
},
"additionalProperties": false
}
]
}
},
"version": {
"type": "string",
"maxLength": 60,
"minLength": 1
},
"unspecified_means": {
"type": "string"
}
},
"description": "Physical specifications per format, stated once per response. A property that is absent is unspecified.",
"additionalProperties": false
},
"generated_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"price_includes": {
"anyOf": [
{
"type": "object",
"required": [
"postage",
"tax"
],
"properties": {
"tax": {
"type": "boolean"
},
"postage": {
"type": "boolean"
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
},
"artist_resolved": {
"type": [
"string",
"null"
]
},
"catalog_revision": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"occasion_resolved": {
"type": [
"string",
"null"
]
},
"pricing_destination": {
"type": "object",
"required": [
"scope",
"country_code",
"introductory",
"assumed"
],
"properties": {
"scope": {
"enum": [
"US",
"international"
],
"type": "string"
},
"assumed": {
"type": "boolean"
},
"country_code": {
"type": [
"string",
"null"
]
},
"introductory": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}search_cards annotations
{
"title": "Search cards",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}prepare_order — Prepare an order
Open-world
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.
prepare_order input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"request_id",
"cards"
],
"properties": {
"cards": {
"type": "array",
"items": {
"type": "object",
"required": [
"design_key",
"design_version",
"message",
"recipient",
"return_address"
],
"properties": {
"format": {
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
],
"type": "string",
"description": "Postcard, flat card in an envelope, or folded card in an envelope. Omit to select flat_card_in_envelope."
},
"message": {
"type": "string",
"maxLength": 4000,
"description": "Body of the personal message, at most 2000 Unicode characters. Paddock prints the greeting \"Dear {greeting_name or display_name},\" above it automatically, so do not start the message with a salutation. Printed artwork wording is separate."
},
"occasion": {
"type": "object",
"required": [
"kind",
"calendar"
],
"properties": {
"day": {
"type": "integer",
"maximum": 31,
"minimum": 1,
"description": "Day valid for occasion.month, required for personal annual occasions such as anniversary. Birthdays use recipient.birthday_day."
},
"kind": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Exact catalog occasion ID, such as birthday, thank_you or just_because. Use just_because with send_on for a one-time mailing date. Use underscores, not display labels or hyphens."
},
"month": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Required with day for a personal annual occasion such as anniversary. Omit for holidays and one-off occasions; birthdays use recipient.birthday_month."
},
"send_on": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Requested mailing date as YYYY-MM-DD, only for one-off occasions such as just_because. Omit for the next available mailing date. This is not a delivery guarantee."
},
"calendar": {
"type": "string",
"const": "us-western-v1",
"description": "Must be us-western-v1, the supported occasion calendar."
}
},
"description": "Optional occasion and timing context, independent of the selected artwork. Omit for an ordinary just-because card.",
"additionalProperties": false
},
"recipient": {
"type": "object",
"required": [
"display_name",
"mailing_address",
"address_confirmed",
"origin"
],
"properties": {
"origin": {
"type": "string",
"const": "manual",
"description": "Must be manual: recipient details come from the buyer, without a member recipient ID or Contacts import."
},
"birthday_day": {
"type": "integer",
"default": 0,
"maximum": 31,
"minimum": 0,
"description": "Birth day valid for birthday_month; February 29 is allowed. Use 0 with birthday_month 0 when the birthday is unknown and this is not a birthday mailing."
},
"display_name": {
"type": "string",
"maxLength": 240,
"description": "Name on the envelope or address panel."
},
"birthday_year": {
"anyOf": [
{
"type": "integer",
"maximum": 9999,
"minimum": 1
},
{
"type": "null"
}
],
"description": "Known birth year, optional. Requires a valid full birth date that is not in the future. Omit or use null when unknown."
},
"greeting_name": {
"type": "string",
"maxLength": 240,
"description": "Name printed in the automatic greeting, such as Ida for \"Dear Ida,\". Defaults to display_name."
},
"birthday_month": {
"type": "integer",
"default": 0,
"maximum": 12,
"minimum": 0,
"description": "Birth month, 1 through 12, required with birthday_day when occasion.kind is birthday. Otherwise omit both or use 0 for both when unknown."
},
"anniversary_day": {
"type": "integer",
"maximum": 31,
"minimum": 0,
"description": "Optional anniversary day valid for anniversary_month; supply both fields together or omit both. Paired zeros mean unknown."
},
"mailing_address": {
"type": "object",
"required": [
"line1",
"locality",
"region",
"postal_code",
"country_code"
],
"properties": {
"line1": {
"type": "string",
"maxLength": 320,
"description": "Street address or postal delivery line supplied by the buyer."
},
"line2": {
"type": "string",
"default": "",
"maxLength": 320,
"description": "Optional second line, such as an apartment or suite. Omitted means empty."
},
"region": {
"type": "string",
"maxLength": 160,
"description": "State, province or region; use an empty string where the destination does not require one."
},
"locality": {
"type": "string",
"maxLength": 320,
"description": "City, town or postal locality."
},
"postal_code": {
"type": "string",
"maxLength": 48,
"description": "Postal or ZIP code; use an empty string where the destination does not use one."
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter uppercase ISO country code, such as US or CA. The recipient country determines the price and postal rules."
}
},
"description": "Recipient mailing address supplied and confirmed by the buyer.",
"additionalProperties": false
},
"address_confirmed": {
"type": "boolean",
"const": true,
"description": "Must be true: the buyer has confirmed the supplied mailing address."
},
"anniversary_month": {
"type": "integer",
"maximum": 12,
"minimum": 0,
"description": "Optional recipient anniversary month, paired with anniversary_day. Use 1 through 12, or 0 for both when unknown. Mailing timing uses occasion.month and occasion.day."
}
},
"description": "Buyer-supplied recipient details for this card. This does not create or select a saved member recipient.",
"additionalProperties": false
},
"design_key": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"description": "Exact card.design.key from search_cards, or its occasion_design_keys entry for the selected occasion when present. Private cards use design_key from read_private_content or compose_private_card."
},
"message_font": {
"enum": [
"serif",
"sans_serif",
"old_school",
"handwriting"
],
"type": "string",
"description": "Font for the personal message: serif, sans_serif, old_school or handwriting. Omission uses serif. Artwork lettering is unchanged."
},
"design_version": {
"type": "integer",
"maximum": 2147483646,
"description": "Matching card.design.version from the same search result, or design_version returned for the private composition. Never infer a version.",
"exclusiveMinimum": 0
},
"return_address": {
"type": "object",
"required": [
"display_name",
"mailing_address",
"source_kind"
],
"properties": {
"source_kind": {
"type": "string",
"const": "manual",
"description": "Must be manual: the buyer supplies this address; billing and saved Home addresses are not inferred."
},
"display_name": {
"type": "string",
"maxLength": 240,
"description": "Sender name printed with the return address."
},
"mailing_address": {
"type": "object",
"required": [
"line1",
"locality",
"region",
"postal_code",
"country_code"
],
"properties": {
"line1": {
"type": "string",
"maxLength": 320,
"description": "Street address or postal delivery line supplied by the buyer."
},
"line2": {
"type": "string",
"default": "",
"maxLength": 320,
"description": "Optional second line, such as an apartment or suite. Omitted means empty."
},
"region": {
"type": "string",
"maxLength": 160,
"description": "State, province or region; use an empty string where the destination does not require one."
},
"locality": {
"type": "string",
"maxLength": 320,
"description": "City, town or postal locality."
},
"postal_code": {
"type": "string",
"maxLength": 48,
"description": "Postal or ZIP code; use an empty string where the destination does not use one."
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter uppercase ISO country code, such as US or CA. The recipient country determines the price and postal rules."
}
},
"description": "Sender return mailing address supplied by the buyer.",
"additionalProperties": false
}
},
"description": "Required for every card format: the sender’s name and return mailing address supplied by the buyer. Not automatically obtained from billing details.",
"additionalProperties": false
},
"include_paddock_gift": {
"type": "boolean",
"description": "Include a complimentary personalized Paddock bookmark. For eligible new envelope orders, omission includes it; set false to opt out. The bookmark has the chosen artwork, a gift message naming the sender, and a unique QR code for one free card, including artist cards. Read the order’s returned paddock_gift: included, and omission_reason when it is not included. Explain it when useful or asked; no separate question or announcement is needed."
}
},
"description": "One manual guest card. Each card may have its own artwork, format, message, recipient, optional occasion and timing. Existing destination/calendar rules apply. No member, Property, recipient, card or calendar-event IDs.",
"additionalProperties": false
},
"maxItems": 500,
"minItems": 1,
"description": "One purchase containing 1–500 explicit card compositions in their supplied order. Mix any supported designs, formats, messages, recipients, occasions and dates. Do not group purchases by occasion. One card uses this same array."
},
"request_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "Caller-generated UUID for a new purchase. For private artwork, use scope_id from open_private_content. Retry only with this same ID, unchanged cards and the exact order_access_token; a different purchase needs a new ID."
},
"order_access_token": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$",
"description": "For a new catalog purchase, omit so Paddock generates and returns the private token. Private artwork uses the token from open_private_content with request_id = scope_id. Retries require the exact token, same request_id and unchanged cards. Never invent a token. Only clients with a cryptographic random generator may pre-generate 32 random bytes encoded as 43 base64url characters for first-response recovery. Keep it private; existing purchase capabilities cannot be replaced."
}
},
"additionalProperties": false
}prepare_order output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"ok",
"data"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"required": [
"order",
"order_access_token",
"review_url",
"preview_available"
],
"properties": {
"order": {
"type": "object",
"required": [
"id",
"revision",
"state",
"payment_state",
"refund_state",
"amount_cents",
"currency",
"card_count",
"tax_ready_count",
"quote_expires_at",
"checkout_url",
"cards"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"cards": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"revision",
"state",
"payment_state",
"refund_state",
"refund_review_reason",
"tax_review_reason",
"input",
"schedule",
"amount_cents",
"currency",
"offer_version",
"terms_version",
"title",
"artist_name",
"quote_expires_at",
"paddock_gift",
"fulfillment_status",
"mailed_at",
"cancellable"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"input": {
"type": "object",
"required": [
"design_key",
"design_version",
"message",
"recipient"
],
"properties": {
"format": {
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
],
"type": "string",
"description": "Postcard, flat card in an envelope, or folded card in an envelope. Omit to select flat_card_in_envelope."
},
"message": {
"type": "string",
"maxLength": 4000,
"description": "Body of the personal message, at most 2000 Unicode characters. Paddock prints the greeting \"Dear {greeting_name or display_name},\" above it automatically, so do not start the message with a salutation. Printed artwork wording is separate."
},
"occasion": {
"type": "object",
"required": [
"kind",
"calendar"
],
"properties": {
"day": {
"type": "integer",
"maximum": 31,
"minimum": 1,
"description": "Day valid for occasion.month, required for personal annual occasions such as anniversary. Birthdays use recipient.birthday_day."
},
"kind": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Exact catalog occasion ID, such as birthday, thank_you or just_because. Use just_because with send_on for a one-time mailing date. Use underscores, not display labels or hyphens."
},
"month": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Required with day for a personal annual occasion such as anniversary. Omit for holidays and one-off occasions; birthdays use recipient.birthday_month."
},
"send_on": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Requested mailing date as YYYY-MM-DD, only for one-off occasions such as just_because. Omit for the next available mailing date. This is not a delivery guarantee."
},
"calendar": {
"type": "string",
"const": "us-western-v1",
"description": "Must be us-western-v1, the supported occasion calendar."
}
},
"description": "Optional occasion and timing context, independent of the selected artwork. Omit for an ordinary just-because card.",
"additionalProperties": false
},
"recipient": {
"type": "object",
"required": [
"display_name",
"birthday_month",
"birthday_day",
"mailing_address",
"address_confirmed",
"origin"
],
"properties": {
"origin": {
"type": "string",
"const": "manual",
"description": "Must be manual: recipient details come from the buyer, without a member recipient ID or Contacts import."
},
"birthday_day": {
"type": "integer",
"maximum": 31,
"minimum": 0
},
"display_name": {
"type": "string",
"maxLength": 240,
"description": "Name on the envelope or address panel."
},
"birthday_year": {
"anyOf": [
{
"type": "integer",
"maximum": 9999,
"minimum": 1
},
{
"type": "null"
}
],
"description": "Known birth year, optional. Requires a valid full birth date that is not in the future. Omit or use null when unknown."
},
"greeting_name": {
"type": "string",
"maxLength": 240,
"description": "Name printed in the automatic greeting, such as Ida for \"Dear Ida,\". Defaults to display_name."
},
"birthday_month": {
"type": "integer",
"maximum": 12,
"minimum": 0
},
"anniversary_day": {
"type": "integer",
"maximum": 31,
"minimum": 0,
"description": "Optional anniversary day valid for anniversary_month; supply both fields together or omit both. Paired zeros mean unknown."
},
"mailing_address": {
"type": "object",
"required": [
"line1",
"line2",
"locality",
"region",
"postal_code",
"country_code"
],
"properties": {
"line1": {
"type": "string",
"maxLength": 320,
"description": "Street address or postal delivery line supplied by the buyer."
},
"line2": {
"type": "string",
"maxLength": 320
},
"region": {
"type": "string",
"maxLength": 160,
"description": "State, province or region; use an empty string where the destination does not require one."
},
"locality": {
"type": "string",
"maxLength": 320,
"description": "City, town or postal locality."
},
"postal_code": {
"type": "string",
"maxLength": 48,
"description": "Postal or ZIP code; use an empty string where the destination does not use one."
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter uppercase ISO country code, such as US or CA. The recipient country determines the price and postal rules."
}
},
"additionalProperties": false
},
"address_confirmed": {
"type": "boolean",
"const": true,
"description": "Must be true: the buyer has confirmed the supplied mailing address."
},
"anniversary_month": {
"type": "integer",
"maximum": 12,
"minimum": 0,
"description": "Optional recipient anniversary month, paired with anniversary_day. Use 1 through 12, or 0 for both when unknown. Mailing timing uses occasion.month and occasion.day."
}
},
"additionalProperties": false
},
"design_key": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"description": "Exact card.design.key from search_cards, or its occasion_design_keys entry for the selected occasion when present. Private cards use design_key from read_private_content or compose_private_card."
},
"message_font": {
"enum": [
"serif",
"sans_serif",
"old_school",
"handwriting"
],
"type": "string",
"description": "Font for the personal message: serif, sans_serif, old_school or handwriting. Omission uses serif. Artwork lettering is unchanged."
},
"design_version": {
"type": "integer",
"maximum": 2147483646,
"description": "Matching card.design.version from the same search result, or design_version returned for the private composition. Never infer a version.",
"exclusiveMinimum": 0
},
"return_address": {
"type": "object",
"required": [
"display_name",
"mailing_address",
"source_kind"
],
"properties": {
"source_kind": {
"type": "string",
"const": "manual",
"description": "Must be manual: the buyer supplies this address; billing and saved Home addresses are not inferred."
},
"display_name": {
"type": "string",
"maxLength": 240,
"description": "Sender name printed with the return address."
},
"mailing_address": {
"type": "object",
"required": [
"line1",
"line2",
"locality",
"region",
"postal_code",
"country_code"
],
"properties": {
"line1": {
"type": "string",
"maxLength": 320,
"description": "Street address or postal delivery line supplied by the buyer."
},
"line2": {
"type": "string",
"maxLength": 320
},
"region": {
"type": "string",
"maxLength": 160,
"description": "State, province or region; use an empty string where the destination does not require one."
},
"locality": {
"type": "string",
"maxLength": 320,
"description": "City, town or postal locality."
},
"postal_code": {
"type": "string",
"maxLength": 48,
"description": "Postal or ZIP code; use an empty string where the destination does not use one."
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter uppercase ISO country code, such as US or CA. The recipient country determines the price and postal rules."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"include_paddock_gift": {
"type": "boolean",
"description": "Include a complimentary personalized Paddock bookmark. For eligible new envelope orders, omission includes it; set false to opt out. The bookmark has the chosen artwork, a gift message naming the sender, and a unique QR code for one free card, including artist cards. Read the order’s returned paddock_gift: included, and omission_reason when it is not included. Explain it when useful or asked; no separate question or announcement is needed."
}
},
"additionalProperties": false
},
"state": {
"enum": [
"prepared",
"checkout_pending",
"paid",
"cancel_requested",
"cancelled"
],
"type": "string"
},
"title": {
"type": "string"
},
"currency": {
"type": "string",
"const": "usd"
},
"revision": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"schedule": {
"type": "object",
"required": [
"time_zone",
"birthday_date",
"send_date",
"collection_date",
"arrival_start",
"arrival_end",
"edit_deadline",
"post_by",
"estimate_basis",
"late",
"leap_day_observed",
"next_year"
],
"properties": {
"late": {
"type": "boolean"
},
"one_off": {
"type": "boolean",
"const": true
},
"post_by": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"next_year": {
"type": "boolean"
},
"send_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"time_zone": {
"type": "string"
},
"arrival_end": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"arrival_start": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"birthday_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"edit_deadline": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"estimate_basis": {
"type": "string"
},
"collection_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"leap_day_observed": {
"type": "boolean"
}
},
"additionalProperties": false
},
"mailed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
{
"type": "null"
}
]
},
"artist_name": {
"type": [
"string",
"null"
]
},
"cancellable": {
"type": "boolean"
},
"amount_cents": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"paddock_gift": {
"type": "object",
"required": [
"included",
"omission_reason"
],
"properties": {
"included": {
"type": "boolean"
},
"omission_reason": {
"anyOf": [
{
"enum": [
"declined",
"no_envelope",
"international_delivery",
"offer_unavailable",
"not_selected"
],
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"product_spec": {
"type": "object",
"required": [
"version",
"format",
"title",
"paper",
"size_in",
"artwork_surface",
"message_surface",
"envelope_included",
"paper_detail",
"personalization",
"printed_text"
],
"properties": {
"paper": {
"type": "string",
"description": "Card stock by its confirmed basis-weight designation."
},
"title": {
"type": "string"
},
"format": {
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
],
"type": "string"
},
"size_in": {
"type": "object",
"required": [
"width",
"height"
],
"properties": {
"width": {
"type": "number",
"exclusiveMinimum": 0
},
"height": {
"type": "number",
"exclusiveMinimum": 0
}
},
"description": "Finished size in inches; the closed size for the folded card.",
"additionalProperties": false
},
"version": {
"type": "string",
"maxLength": 60,
"minLength": 1
},
"envelope": {
"type": "object",
"required": [
"size_in",
"addressing"
],
"properties": {
"size_in": {
"type": "object",
"required": [
"width",
"height"
],
"properties": {
"width": {
"type": "number",
"exclusiveMinimum": 0
},
"height": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"addressing": {
"type": "string"
}
},
"description": "Present only for formats mailed in an envelope.",
"additionalProperties": false
},
"open_size_in": {
"type": "object",
"required": [
"width",
"height"
],
"properties": {
"width": {
"type": "number",
"exclusiveMinimum": 0
},
"height": {
"type": "number",
"exclusiveMinimum": 0
}
},
"description": "Folded card only: size when opened.",
"additionalProperties": false
},
"paper_detail": {
"type": "object",
"required": [
"basis_weight"
],
"properties": {
"gsm": {
"type": "number",
"description": "Manufacturer-stated grammage; absent when unknown.",
"exclusiveMinimum": 0
},
"color": {
"type": "string",
"description": "Absent until confirmed for the stock in use."
},
"finish": {
"type": "string",
"description": "Absent until confirmed for the stock in use."
},
"caliper_in": {
"type": "number",
"description": "Measured sheet thickness in inches; absent when unknown.",
"exclusiveMinimum": 0
},
"basis_weight": {
"type": "string"
}
},
"additionalProperties": false
},
"printed_text": {
"type": "string"
},
"artwork_surface": {
"enum": [
"front",
"front cover"
],
"type": "string"
},
"message_surface": {
"type": "string",
"description": "Where Paddock prints the personal message."
},
"personalization": {
"type": "object",
"required": [
"fonts",
"automatic_greeting",
"max_message_chars",
"fit_check"
],
"properties": {
"fonts": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"fit_check": {
"type": "string"
},
"max_message_chars": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"automatic_greeting": {
"type": "string"
}
},
"additionalProperties": false
},
"envelope_included": {
"type": "boolean"
}
},
"additionalProperties": false
},
"refund_state": {
"enum": [
"none",
"pending",
"processing",
"succeeded",
"failed",
"unknown"
],
"type": "string"
},
"offer_version": {
"type": "string"
},
"payment_state": {
"enum": [
"unpaid",
"pending",
"paid",
"failed",
"expired",
"refunding",
"refunded"
],
"type": "string"
},
"terms_version": {
"type": "string"
},
"quote_expires_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"tax_review_reason": {
"type": [
"string",
"null"
]
},
"fulfillment_status": {
"anyOf": [
{
"enum": [
"scheduled",
"preparing",
"ready",
"mailed",
"cancel_requested",
"cancelled"
],
"type": "string"
},
{
"type": "null"
}
]
},
"refund_review_reason": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"maxItems": 500,
"minItems": 1
},
"state": {
"enum": [
"prepared",
"checkout_pending",
"paid",
"cancel_requested",
"cancelled"
],
"type": "string"
},
"currency": {
"type": "string",
"const": "usd"
},
"revision": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"card_count": {
"type": "integer",
"maximum": 500,
"minimum": 1
},
"amount_cents": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"checkout_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"refund_state": {
"enum": [
"none",
"pending",
"partial",
"succeeded",
"failed",
"unknown"
],
"type": "string"
},
"payment_state": {
"enum": [
"unpaid",
"pending",
"paid",
"failed",
"expired",
"refunding",
"refunded"
],
"type": "string"
},
"tax_ready_count": {
"type": "integer",
"maximum": 500,
"minimum": 0
},
"customer_content": {
"type": "object",
"required": [
"rights_required",
"rights_accepted",
"terms_version"
],
"properties": {
"terms_version": {
"type": "string",
"const": "customer-print-v1"
},
"rights_accepted": {
"type": "boolean"
},
"rights_required": {
"type": "boolean"
}
},
"additionalProperties": false
},
"quote_expires_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"additionalProperties": false
},
"reused": {
"type": "boolean"
},
"review_url": {
"type": "string",
"format": "uri"
},
"payment_required": {
"type": "boolean"
},
"preview_available": {
"type": "boolean",
"description": "At least one current card is eligible for optional preview_card. Images render only when requested; access and current state are rechecked then."
},
"order_access_token": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}prepare_order annotations
{
"title": "Prepare an order",
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}read_order — Read an order
Advertised read-only
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.
read_order input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"order_id",
"order_access_token"
],
"properties": {
"order_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "Parent order.id returned by prepare_order, revise_order or read_order. Use the matching order_access_token; a card ID cannot identify the purchase."
},
"order_access_token": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$",
"description": "Exact private order_access_token returned by prepare_order or revise_order for this order. Keep it secret; never invent it or put it in a public URL or log."
}
},
"additionalProperties": false
}read_order output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"ok",
"data"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"required": [
"order"
],
"properties": {
"order": {
"type": "object",
"required": [
"id",
"revision",
"state",
"payment_state",
"refund_state",
"amount_cents",
"currency",
"card_count",
"tax_ready_count",
"quote_expires_at",
"checkout_url",
"cards"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"cards": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"revision",
"state",
"payment_state",
"refund_state",
"refund_review_reason",
"tax_review_reason",
"input",
"schedule",
"amount_cents",
"currency",
"offer_version",
"terms_version",
"title",
"artist_name",
"quote_expires_at",
"paddock_gift",
"fulfillment_status",
"mailed_at",
"cancellable"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"input": {
"type": "object",
"required": [
"design_key",
"design_version",
"message",
"recipient"
],
"properties": {
"format": {
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
],
"type": "string",
"description": "Postcard, flat card in an envelope, or folded card in an envelope. Omit to select flat_card_in_envelope."
},
"message": {
"type": "string",
"maxLength": 4000,
"description": "Body of the personal message, at most 2000 Unicode characters. Paddock prints the greeting \"Dear {greeting_name or display_name},\" above it automatically, so do not start the message with a salutation. Printed artwork wording is separate."
},
"occasion": {
"type": "object",
"required": [
"kind",
"calendar"
],
"properties": {
"day": {
"type": "integer",
"maximum": 31,
"minimum": 1,
"description": "Day valid for occasion.month, required for personal annual occasions such as anniversary. Birthdays use recipient.birthday_day."
},
"kind": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Exact catalog occasion ID, such as birthday, thank_you or just_because. Use just_because with send_on for a one-time mailing date. Use underscores, not display labels or hyphens."
},
"month": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Required with day for a personal annual occasion such as anniversary. Omit for holidays and one-off occasions; birthdays use recipient.birthday_month."
},
"send_on": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Requested mailing date as YYYY-MM-DD, only for one-off occasions such as just_because. Omit for the next available mailing date. This is not a delivery guarantee."
},
"calendar": {
"type": "string",
"const": "us-western-v1",
"description": "Must be us-western-v1, the supported occasion calendar."
}
},
"description": "Optional occasion and timing context, independent of the selected artwork. Omit for an ordinary just-because card.",
"additionalProperties": false
},
"recipient": {
"type": "object",
"required": [
"display_name",
"birthday_month",
"birthday_day",
"mailing_address",
"address_confirmed",
"origin"
],
"properties": {
"origin": {
"type": "string",
"const": "manual",
"description": "Must be manual: recipient details come from the buyer, without a member recipient ID or Contacts import."
},
"birthday_day": {
"type": "integer",
"maximum": 31,
"minimum": 0
},
"display_name": {
"type": "string",
"maxLength": 240,
"description": "Name on the envelope or address panel."
},
"birthday_year": {
"anyOf": [
{
"type": "integer",
"maximum": 9999,
"minimum": 1
},
{
"type": "null"
}
],
"description": "Known birth year, optional. Requires a valid full birth date that is not in the future. Omit or use null when unknown."
},
"greeting_name": {
"type": "string",
"maxLength": 240,
"description": "Name printed in the automatic greeting, such as Ida for \"Dear Ida,\". Defaults to display_name."
},
"birthday_month": {
"type": "integer",
"maximum": 12,
"minimum": 0
},
"anniversary_day": {
"type": "integer",
"maximum": 31,
"minimum": 0,
"description": "Optional anniversary day valid for anniversary_month; supply both fields together or omit both. Paired zeros mean unknown."
},
"mailing_address": {
"type": "object",
"required": [
"line1",
"line2",
"locality",
"region",
"postal_code",
"country_code"
],
"properties": {
"line1": {
"type": "string",
"maxLength": 320,
"description": "Street address or postal delivery line supplied by the buyer."
},
"line2": {
"type": "string",
"maxLength": 320
},
"region": {
"type": "string",
"maxLength": 160,
"description": "State, province or region; use an empty string where the destination does not require one."
},
"locality": {
"type": "string",
"maxLength": 320,
"description": "City, town or postal locality."
},
"postal_code": {
"type": "string",
"maxLength": 48,
"description": "Postal or ZIP code; use an empty string where the destination does not use one."
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter uppercase ISO country code, such as US or CA. The recipient country determines the price and postal rules."
}
},
"additionalProperties": false
},
"address_confirmed": {
"type": "boolean",
"const": true,
"description": "Must be true: the buyer has confirmed the supplied mailing address."
},
"anniversary_month": {
"type": "integer",
"maximum": 12,
"minimum": 0,
"description": "Optional recipient anniversary month, paired with anniversary_day. Use 1 through 12, or 0 for both when unknown. Mailing timing uses occasion.month and occasion.day."
}
},
"additionalProperties": false
},
"design_key": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"description": "Exact card.design.key from search_cards, or its occasion_design_keys entry for the selected occasion when present. Private cards use design_key from read_private_content or compose_private_card."
},
"message_font": {
"enum": [
"serif",
"sans_serif",
"old_school",
"handwriting"
],
"type": "string",
"description": "Font for the personal message: serif, sans_serif, old_school or handwriting. Omission uses serif. Artwork lettering is unchanged."
},
"design_version": {
"type": "integer",
"maximum": 2147483646,
"description": "Matching card.design.version from the same search result, or design_version returned for the private composition. Never infer a version.",
"exclusiveMinimum": 0
},
"return_address": {
"type": "object",
"required": [
"display_name",
"mailing_address",
"source_kind"
],
"properties": {
"source_kind": {
"type": "string",
"const": "manual",
"description": "Must be manual: the buyer supplies this address; billing and saved Home addresses are not inferred."
},
"display_name": {
"type": "string",
"maxLength": 240,
"description": "Sender name printed with the return address."
},
"mailing_address": {
"type": "object",
"required": [
"line1",
"line2",
"locality",
"region",
"postal_code",
"country_code"
],
"properties": {
"line1": {
"type": "string",
"maxLength": 320,
"description": "Street address or postal delivery line supplied by the buyer."
},
"line2": {
"type": "string",
"maxLength": 320
},
"region": {
"type": "string",
"maxLength": 160,
"description": "State, province or region; use an empty string where the destination does not require one."
},
"locality": {
"type": "string",
"maxLength": 320,
"description": "City, town or postal locality."
},
"postal_code": {
"type": "string",
"maxLength": 48,
"description": "Postal or ZIP code; use an empty string where the destination does not use one."
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter uppercase ISO country code, such as US or CA. The recipient country determines the price and postal rules."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"include_paddock_gift": {
"type": "boolean",
"description": "Include a complimentary personalized Paddock bookmark. For eligible new envelope orders, omission includes it; set false to opt out. The bookmark has the chosen artwork, a gift message naming the sender, and a unique QR code for one free card, including artist cards. Read the order’s returned paddock_gift: included, and omission_reason when it is not included. Explain it when useful or asked; no separate question or announcement is needed."
}
},
"additionalProperties": false
},
"state": {
"enum": [
"prepared",
"checkout_pending",
"paid",
"cancel_requested",
"cancelled"
],
"type": "string"
},
"title": {
"type": "string"
},
"currency": {
"type": "string",
"const": "usd"
},
"revision": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"schedule": {
"type": "object",
"required": [
"time_zone",
"birthday_date",
"send_date",
"collection_date",
"arrival_start",
"arrival_end",
"edit_deadline",
"post_by",
"estimate_basis",
"late",
"leap_day_observed",
"next_year"
],
"properties": {
"late": {
"type": "boolean"
},
"one_off": {
"type": "boolean",
"const": true
},
"post_by": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"next_year": {
"type": "boolean"
},
"send_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"time_zone": {
"type": "string"
},
"arrival_end": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"arrival_start": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"birthday_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"edit_deadline": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"estimate_basis": {
"type": "string"
},
"collection_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"leap_day_observed": {
"type": "boolean"
}
},
"additionalProperties": false
},
"mailed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
{
"type": "null"
}
]
},
"artist_name": {
"type": [
"string",
"null"
]
},
"cancellable": {
"type": "boolean"
},
"amount_cents": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"paddock_gift": {
"type": "object",
"required": [
"included",
"omission_reason"
],
"properties": {
"included": {
"type": "boolean"
},
"omission_reason": {
"anyOf": [
{
"enum": [
"declined",
"no_envelope",
"international_delivery",
"offer_unavailable",
"not_selected"
],
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"product_spec": {
"type": "object",
"required": [
"version",
"format",
"title",
"paper",
"size_in",
"artwork_surface",
"message_surface",
"envelope_included",
"paper_detail",
"personalization",
"printed_text"
],
"properties": {
"paper": {
"type": "string",
"description": "Card stock by its confirmed basis-weight designation."
},
"title": {
"type": "string"
},
"format": {
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
],
"type": "string"
},
"size_in": {
"type": "object",
"required": [
"width",
"height"
],
"properties": {
"width": {
"type": "number",
"exclusiveMinimum": 0
},
"height": {
"type": "number",
"exclusiveMinimum": 0
}
},
"description": "Finished size in inches; the closed size for the folded card.",
"additionalProperties": false
},
"version": {
"type": "string",
"maxLength": 60,
"minLength": 1
},
"envelope": {
"type": "object",
"required": [
"size_in",
"addressing"
],
"properties": {
"size_in": {
"type": "object",
"required": [
"width",
"height"
],
"properties": {
"width": {
"type": "number",
"exclusiveMinimum": 0
},
"height": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"addressing": {
"type": "string"
}
},
"description": "Present only for formats mailed in an envelope.",
"additionalProperties": false
},
"open_size_in": {
"type": "object",
"required": [
"width",
"height"
],
"properties": {
"width": {
"type": "number",
"exclusiveMinimum": 0
},
"height": {
"type": "number",
"exclusiveMinimum": 0
}
},
"description": "Folded card only: size when opened.",
"additionalProperties": false
},
"paper_detail": {
"type": "object",
"required": [
"basis_weight"
],
"properties": {
"gsm": {
"type": "number",
"description": "Manufacturer-stated grammage; absent when unknown.",
"exclusiveMinimum": 0
},
"color": {
"type": "string",
"description": "Absent until confirmed for the stock in use."
},
"finish": {
"type": "string",
"description": "Absent until confirmed for the stock in use."
},
"caliper_in": {
"type": "number",
"description": "Measured sheet thickness in inches; absent when unknown.",
"exclusiveMinimum": 0
},
"basis_weight": {
"type": "string"
}
},
"additionalProperties": false
},
"printed_text": {
"type": "string"
},
"artwork_surface": {
"enum": [
"front",
"front cover"
],
"type": "string"
},
"message_surface": {
"type": "string",
"description": "Where Paddock prints the personal message."
},
"personalization": {
"type": "object",
"required": [
"fonts",
"automatic_greeting",
"max_message_chars",
"fit_check"
],
"properties": {
"fonts": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"fit_check": {
"type": "string"
},
"max_message_chars": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"automatic_greeting": {
"type": "string"
}
},
"additionalProperties": false
},
"envelope_included": {
"type": "boolean"
}
},
"additionalProperties": false
},
"refund_state": {
"enum": [
"none",
"pending",
"processing",
"succeeded",
"failed",
"unknown"
],
"type": "string"
},
"offer_version": {
"type": "string"
},
"payment_state": {
"enum": [
"unpaid",
"pending",
"paid",
"failed",
"expired",
"refunding",
"refunded"
],
"type": "string"
},
"terms_version": {
"type": "string"
},
"quote_expires_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"tax_review_reason": {
"type": [
"string",
"null"
]
},
"fulfillment_status": {
"anyOf": [
{
"enum": [
"scheduled",
"preparing",
"ready",
"mailed",
"cancel_requested",
"cancelled"
],
"type": "string"
},
{
"type": "null"
}
]
},
"refund_review_reason": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"maxItems": 500,
"minItems": 1
},
"state": {
"enum": [
"prepared",
"checkout_pending",
"paid",
"cancel_requested",
"cancelled"
],
"type": "string"
},
"currency": {
"type": "string",
"const": "usd"
},
"revision": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"card_count": {
"type": "integer",
"maximum": 500,
"minimum": 1
},
"amount_cents": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"checkout_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"refund_state": {
"enum": [
"none",
"pending",
"partial",
"succeeded",
"failed",
"unknown"
],
"type": "string"
},
"payment_state": {
"enum": [
"unpaid",
"pending",
"paid",
"failed",
"expired",
"refunding",
"refunded"
],
"type": "string"
},
"tax_ready_count": {
"type": "integer",
"maximum": 500,
"minimum": 0
},
"customer_content": {
"type": "object",
"required": [
"rights_required",
"rights_accepted",
"terms_version"
],
"properties": {
"terms_version": {
"type": "string",
"const": "customer-print-v1"
},
"rights_accepted": {
"type": "boolean"
},
"rights_required": {
"type": "boolean"
}
},
"additionalProperties": false
},
"quote_expires_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}read_order annotations
{
"title": "Read an order",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}cancel_order — Cancel cards
Advertised destructiveOpen-world
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.
cancel_order input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"order_id",
"order_access_token",
"expected_revision"
],
"properties": {
"card_ids": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"maxItems": 500,
"minItems": 1,
"description": "Omit to cancel the whole eligible purchase. After payment, select IDs from this order.cards[].id to cancel only those eligible items. Before payment, omit this field. IDs must be distinct and belong to this order."
},
"order_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "Parent order.id returned by prepare_order, revise_order or read_order. Use the matching order_access_token; a card ID cannot identify the purchase."
},
"expected_revision": {
"type": "integer",
"maximum": 2147483646,
"description": "Current parent order.revision from prepare_order, revise_order or read_order. A mismatch fails with CONFLICT; read the order before deciding whether to retry cancellation.",
"exclusiveMinimum": 0
},
"order_access_token": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$",
"description": "Exact private order_access_token returned by prepare_order or revise_order for this order. Keep it secret; never invent it or put it in a public URL or log."
}
},
"additionalProperties": false
}cancel_order output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"ok",
"data"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"required": [
"order"
],
"properties": {
"order": {
"type": "object",
"required": [
"id",
"revision",
"state",
"payment_state",
"refund_state",
"amount_cents",
"currency",
"card_count",
"tax_ready_count",
"quote_expires_at",
"checkout_url",
"cards"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"cards": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"revision",
"state",
"payment_state",
"refund_state",
"refund_review_reason",
"tax_review_reason",
"input",
"schedule",
"amount_cents",
"currency",
"offer_version",
"terms_version",
"title",
"artist_name",
"quote_expires_at",
"paddock_gift",
"fulfillment_status",
"mailed_at",
"cancellable"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"input": {
"type": "object",
"required": [
"design_key",
"design_version",
"message",
"recipient"
],
"properties": {
"format": {
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
],
"type": "string",
"description": "Postcard, flat card in an envelope, or folded card in an envelope. Omit to select flat_card_in_envelope."
},
"message": {
"type": "string",
"maxLength": 4000,
"description": "Body of the personal message, at most 2000 Unicode characters. Paddock prints the greeting \"Dear {greeting_name or display_name},\" above it automatically, so do not start the message with a salutation. Printed artwork wording is separate."
},
"occasion": {
"type": "object",
"required": [
"kind",
"calendar"
],
"properties": {
"day": {
"type": "integer",
"maximum": 31,
"minimum": 1,
"description": "Day valid for occasion.month, required for personal annual occasions such as anniversary. Birthdays use recipient.birthday_day."
},
"kind": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Exact catalog occasion ID, such as birthday, thank_you or just_because. Use just_because with send_on for a one-time mailing date. Use underscores, not display labels or hyphens."
},
"month": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Required with day for a personal annual occasion such as anniversary. Omit for holidays and one-off occasions; birthdays use recipient.birthday_month."
},
"send_on": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Requested mailing date as YYYY-MM-DD, only for one-off occasions such as just_because. Omit for the next available mailing date. This is not a delivery guarantee."
},
"calendar": {
"type": "string",
"const": "us-western-v1",
"description": "Must be us-western-v1, the supported occasion calendar."
}
},
"description": "Optional occasion and timing context, independent of the selected artwork. Omit for an ordinary just-because card.",
"additionalProperties": false
},
"recipient": {
"type": "object",
"required": [
"display_name",
"birthday_month",
"birthday_day",
"mailing_address",
"address_confirmed",
"origin"
],
"properties": {
"origin": {
"type": "string",
"const": "manual",
"description": "Must be manual: recipient details come from the buyer, without a member recipient ID or Contacts import."
},
"birthday_day": {
"type": "integer",
"maximum": 31,
"minimum": 0
},
"display_name": {
"type": "string",
"maxLength": 240,
"description": "Name on the envelope or address panel."
},
"birthday_year": {
"anyOf": [
{
"type": "integer",
"maximum": 9999,
"minimum": 1
},
{
"type": "null"
}
],
"description": "Known birth year, optional. Requires a valid full birth date that is not in the future. Omit or use null when unknown."
},
"greeting_name": {
"type": "string",
"maxLength": 240,
"description": "Name printed in the automatic greeting, such as Ida for \"Dear Ida,\". Defaults to display_name."
},
"birthday_month": {
"type": "integer",
"maximum": 12,
"minimum": 0
},
"anniversary_day": {
"type": "integer",
"maximum": 31,
"minimum": 0,
"description": "Optional anniversary day valid for anniversary_month; supply both fields together or omit both. Paired zeros mean unknown."
},
"mailing_address": {
"type": "object",
"required": [
"line1",
"line2",
"locality",
"region",
"postal_code",
"country_code"
],
"properties": {
"line1": {
"type": "string",
"maxLength": 320,
"description": "Street address or postal delivery line supplied by the buyer."
},
"line2": {
"type": "string",
"maxLength": 320
},
"region": {
"type": "string",
"maxLength": 160,
"description": "State, province or region; use an empty string where the destination does not require one."
},
"locality": {
"type": "string",
"maxLength": 320,
"description": "City, town or postal locality."
},
"postal_code": {
"type": "string",
"maxLength": 48,
"description": "Postal or ZIP code; use an empty string where the destination does not use one."
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter uppercase ISO country code, such as US or CA. The recipient country determines the price and postal rules."
}
},
"additionalProperties": false
},
"address_confirmed": {
"type": "boolean",
"const": true,
"description": "Must be true: the buyer has confirmed the supplied mailing address."
},
"anniversary_month": {
"type": "integer",
"maximum": 12,
"minimum": 0,
"description": "Optional recipient anniversary month, paired with anniversary_day. Use 1 through 12, or 0 for both when unknown. Mailing timing uses occasion.month and occasion.day."
}
},
"additionalProperties": false
},
"design_key": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"description": "Exact card.design.key from search_cards, or its occasion_design_keys entry for the selected occasion when present. Private cards use design_key from read_private_content or compose_private_card."
},
"message_font": {
"enum": [
"serif",
"sans_serif",
"old_school",
"handwriting"
],
"type": "string",
"description": "Font for the personal message: serif, sans_serif, old_school or handwriting. Omission uses serif. Artwork lettering is unchanged."
},
"design_version": {
"type": "integer",
"maximum": 2147483646,
"description": "Matching card.design.version from the same search result, or design_version returned for the private composition. Never infer a version.",
"exclusiveMinimum": 0
},
"return_address": {
"type": "object",
"required": [
"display_name",
"mailing_address",
"source_kind"
],
"properties": {
"source_kind": {
"type": "string",
"const": "manual",
"description": "Must be manual: the buyer supplies this address; billing and saved Home addresses are not inferred."
},
"display_name": {
"type": "string",
"maxLength": 240,
"description": "Sender name printed with the return address."
},
"mailing_address": {
"type": "object",
"required": [
"line1",
"line2",
"locality",
"region",
"postal_code",
"country_code"
],
"properties": {
"line1": {
"type": "string",
"maxLength": 320,
"description": "Street address or postal delivery line supplied by the buyer."
},
"line2": {
"type": "string",
"maxLength": 320
},
"region": {
"type": "string",
"maxLength": 160,
"description": "State, province or region; use an empty string where the destination does not require one."
},
"locality": {
"type": "string",
"maxLength": 320,
"description": "City, town or postal locality."
},
"postal_code": {
"type": "string",
"maxLength": 48,
"description": "Postal or ZIP code; use an empty string where the destination does not use one."
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter uppercase ISO country code, such as US or CA. The recipient country determines the price and postal rules."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"include_paddock_gift": {
"type": "boolean",
"description": "Include a complimentary personalized Paddock bookmark. For eligible new envelope orders, omission includes it; set false to opt out. The bookmark has the chosen artwork, a gift message naming the sender, and a unique QR code for one free card, including artist cards. Read the order’s returned paddock_gift: included, and omission_reason when it is not included. Explain it when useful or asked; no separate question or announcement is needed."
}
},
"additionalProperties": false
},
"state": {
"enum": [
"prepared",
"checkout_pending",
"paid",
"cancel_requested",
"cancelled"
],
"type": "string"
},
"title": {
"type": "string"
},
"currency": {
"type": "string",
"const": "usd"
},
"revision": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"schedule": {
"type": "object",
"required": [
"time_zone",
"birthday_date",
"send_date",
"collection_date",
"arrival_start",
"arrival_end",
"edit_deadline",
"post_by",
"estimate_basis",
"late",
"leap_day_observed",
"next_year"
],
"properties": {
"late": {
"type": "boolean"
},
"one_off": {
"type": "boolean",
"const": true
},
"post_by": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"next_year": {
"type": "boolean"
},
"send_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"time_zone": {
"type": "string"
},
"arrival_end": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"arrival_start": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"birthday_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"edit_deadline": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"estimate_basis": {
"type": "string"
},
"collection_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"leap_day_observed": {
"type": "boolean"
}
},
"additionalProperties": false
},
"mailed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
{
"type": "null"
}
]
},
"artist_name": {
"type": [
"string",
"null"
]
},
"cancellable": {
"type": "boolean"
},
"amount_cents": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"paddock_gift": {
"type": "object",
"required": [
"included",
"omission_reason"
],
"properties": {
"included": {
"type": "boolean"
},
"omission_reason": {
"anyOf": [
{
"enum": [
"declined",
"no_envelope",
"international_delivery",
"offer_unavailable",
"not_selected"
],
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"product_spec": {
"type": "object",
"required": [
"version",
"format",
"title",
"paper",
"size_in",
"artwork_surface",
"message_surface",
"envelope_included",
"paper_detail",
"personalization",
"printed_text"
],
"properties": {
"paper": {
"type": "string",
"description": "Card stock by its confirmed basis-weight designation."
},
"title": {
"type": "string"
},
"format": {
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
],
"type": "string"
},
"size_in": {
"type": "object",
"required": [
"width",
"height"
],
"properties": {
"width": {
"type": "number",
"exclusiveMinimum": 0
},
"height": {
"type": "number",
"exclusiveMinimum": 0
}
},
"description": "Finished size in inches; the closed size for the folded card.",
"additionalProperties": false
},
"version": {
"type": "string",
"maxLength": 60,
"minLength": 1
},
"envelope": {
"type": "object",
"required": [
"size_in",
"addressing"
],
"properties": {
"size_in": {
"type": "object",
"required": [
"width",
"height"
],
"properties": {
"width": {
"type": "number",
"exclusiveMinimum": 0
},
"height": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"addressing": {
"type": "string"
}
},
"description": "Present only for formats mailed in an envelope.",
"additionalProperties": false
},
"open_size_in": {
"type": "object",
"required": [
"width",
"height"
],
"properties": {
"width": {
"type": "number",
"exclusiveMinimum": 0
},
"height": {
"type": "number",
"exclusiveMinimum": 0
}
},
"description": "Folded card only: size when opened.",
"additionalProperties": false
},
"paper_detail": {
"type": "object",
"required": [
"basis_weight"
],
"properties": {
"gsm": {
"type": "number",
"description": "Manufacturer-stated grammage; absent when unknown.",
"exclusiveMinimum": 0
},
"color": {
"type": "string",
"description": "Absent until confirmed for the stock in use."
},
"finish": {
"type": "string",
"description": "Absent until confirmed for the stock in use."
},
"caliper_in": {
"type": "number",
"description": "Measured sheet thickness in inches; absent when unknown.",
"exclusiveMinimum": 0
},
"basis_weight": {
"type": "string"
}
},
"additionalProperties": false
},
"printed_text": {
"type": "string"
},
"artwork_surface": {
"enum": [
"front",
"front cover"
],
"type": "string"
},
"message_surface": {
"type": "string",
"description": "Where Paddock prints the personal message."
},
"personalization": {
"type": "object",
"required": [
"fonts",
"automatic_greeting",
"max_message_chars",
"fit_check"
],
"properties": {
"fonts": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"fit_check": {
"type": "string"
},
"max_message_chars": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"automatic_greeting": {
"type": "string"
}
},
"additionalProperties": false
},
"envelope_included": {
"type": "boolean"
}
},
"additionalProperties": false
},
"refund_state": {
"enum": [
"none",
"pending",
"processing",
"succeeded",
"failed",
"unknown"
],
"type": "string"
},
"offer_version": {
"type": "string"
},
"payment_state": {
"enum": [
"unpaid",
"pending",
"paid",
"failed",
"expired",
"refunding",
"refunded"
],
"type": "string"
},
"terms_version": {
"type": "string"
},
"quote_expires_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"tax_review_reason": {
"type": [
"string",
"null"
]
},
"fulfillment_status": {
"anyOf": [
{
"enum": [
"scheduled",
"preparing",
"ready",
"mailed",
"cancel_requested",
"cancelled"
],
"type": "string"
},
{
"type": "null"
}
]
},
"refund_review_reason": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"maxItems": 500,
"minItems": 1
},
"state": {
"enum": [
"prepared",
"checkout_pending",
"paid",
"cancel_requested",
"cancelled"
],
"type": "string"
},
"currency": {
"type": "string",
"const": "usd"
},
"revision": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"card_count": {
"type": "integer",
"maximum": 500,
"minimum": 1
},
"amount_cents": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"checkout_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"refund_state": {
"enum": [
"none",
"pending",
"partial",
"succeeded",
"failed",
"unknown"
],
"type": "string"
},
"payment_state": {
"enum": [
"unpaid",
"pending",
"paid",
"failed",
"expired",
"refunding",
"refunded"
],
"type": "string"
},
"tax_ready_count": {
"type": "integer",
"maximum": 500,
"minimum": 0
},
"customer_content": {
"type": "object",
"required": [
"rights_required",
"rights_accepted",
"terms_version"
],
"properties": {
"terms_version": {
"type": "string",
"const": "customer-print-v1"
},
"rights_accepted": {
"type": "boolean"
},
"rights_required": {
"type": "boolean"
}
},
"additionalProperties": false
},
"quote_expires_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}cancel_order annotations
{
"title": "Cancel cards",
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": true
}report_feedback — Report technical feedback
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.
report_feedback input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"kind",
"operation",
"category",
"severity"
],
"properties": {
"code": {
"enum": [
"none",
"INVALID_REQUEST",
"CARD_VALIDATION_FAILED",
"NOT_FOUND",
"CONFLICT",
"GONE",
"CATALOG_ARTWORK_UNAVAILABLE",
"CARD_SAMPLE_ACCEPTANCE_REQUIRED",
"CARD_ARTWORK_ACCEPTANCE_REQUIRED",
"ARTIST_PRINT_SETUP_REQUIRED",
"DESTINATION_INVALID",
"DESTINATION_SUSPENDED",
"DESTINATION_REVIEW_REQUIRED",
"MESSAGE_DOES_NOT_FIT",
"RETURN_ADDRESS_REQUIRED",
"PRICE_CHANGED",
"QUOTE_EXPIRED",
"PAYMENT_UNAVAILABLE",
"CHECKOUT_UNAVAILABLE",
"CANCELLATION_NOT_ALLOWED",
"REFUND_NOT_ELIGIBLE",
"SERVICE_PAUSED",
"TRY_LATER",
"UNAVAILABLE"
],
"type": "string",
"default": "none",
"description": "Exact public error code returned by the service, or none when absent. Success requires none. Never include provider error text."
},
"kind": {
"enum": [
"problem",
"suggestion",
"success"
],
"type": "string",
"description": "Report an observed problem, a suggestion or a neutral successful outcome. The category must match this kind."
},
"field": {
"enum": [
"none",
"design_key",
"design_version",
"format",
"message",
"recipient.mailing_address",
"return_address",
"occasion",
"price",
"printed_text",
"availability",
"preview"
],
"type": "string",
"default": "none",
"description": "Affected field name only, or none when absent. Success requires none. Never include the field’s value."
},
"category": {
"enum": [
"no_suitable_card",
"irrelevant_results",
"unclear_result",
"preview_unavailable",
"request_rejected",
"slow_response",
"unexpected_error",
"recovery_failed",
"broader_selection",
"clearer_results",
"better_recovery",
"simpler_checkout",
"faster_responses",
"better_documentation",
"completed_as_expected"
],
"type": "string",
"description": "For problem, choose no_suitable_card, irrelevant_results, unclear_result, preview_unavailable, request_rejected, slow_response, unexpected_error or recovery_failed. For suggestion, choose broader_selection, clearer_results, better_recovery, simpler_checkout, faster_responses or better_documentation. Success requires completed_as_expected."
},
"severity": {
"enum": [
"none",
"minor",
"major",
"blocked"
],
"type": "string",
"description": "Observed impact: none, minor inconvenience, major impairment or blocked progress. A problem requires minor, major or blocked; success requires none."
},
"operation": {
"enum": [
"search_cards",
"prepare_order",
"read_order",
"cancel_order",
"checkout",
"connection",
"documentation"
],
"type": "string",
"description": "Supported step the report concerns. Use checkout for payment and connection for connection setup; select documentation for guide or setup instructions."
}
},
"additionalProperties": false
}report_feedback output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"ok",
"data"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"required": [
"status",
"verification"
],
"properties": {
"status": {
"enum": [
"recorded",
"duplicate"
],
"type": "string"
},
"verification": {
"type": "string",
"const": "unverified_report"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}report_feedback annotations
{
"title": "Report technical feedback",
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false,
"destructiveHint": false
}revise_order — Revise an unpaid order
Advertised destructive
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.
revise_order input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"request_id",
"cards",
"order_id",
"order_access_token",
"expected_revision"
],
"properties": {
"cards": {
"type": "array",
"items": {
"type": "object",
"required": [
"design_key",
"design_version",
"message",
"recipient",
"return_address"
],
"properties": {
"format": {
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
],
"type": "string",
"description": "Postcard, flat card in an envelope, or folded card in an envelope. Omit to select flat_card_in_envelope."
},
"message": {
"type": "string",
"maxLength": 4000,
"description": "Body of the personal message, at most 2000 Unicode characters. Paddock prints the greeting \"Dear {greeting_name or display_name},\" above it automatically, so do not start the message with a salutation. Printed artwork wording is separate."
},
"occasion": {
"type": "object",
"required": [
"kind",
"calendar"
],
"properties": {
"day": {
"type": "integer",
"maximum": 31,
"minimum": 1,
"description": "Day valid for occasion.month, required for personal annual occasions such as anniversary. Birthdays use recipient.birthday_day."
},
"kind": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Exact catalog occasion ID, such as birthday, thank_you or just_because. Use just_because with send_on for a one-time mailing date. Use underscores, not display labels or hyphens."
},
"month": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Required with day for a personal annual occasion such as anniversary. Omit for holidays and one-off occasions; birthdays use recipient.birthday_month."
},
"send_on": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Requested mailing date as YYYY-MM-DD, only for one-off occasions such as just_because. Omit for the next available mailing date. This is not a delivery guarantee."
},
"calendar": {
"type": "string",
"const": "us-western-v1",
"description": "Must be us-western-v1, the supported occasion calendar."
}
},
"description": "Optional occasion and timing context, independent of the selected artwork. Omit for an ordinary just-because card.",
"additionalProperties": false
},
"recipient": {
"type": "object",
"required": [
"display_name",
"mailing_address",
"address_confirmed",
"origin"
],
"properties": {
"origin": {
"type": "string",
"const": "manual",
"description": "Must be manual: recipient details come from the buyer, without a member recipient ID or Contacts import."
},
"birthday_day": {
"type": "integer",
"default": 0,
"maximum": 31,
"minimum": 0,
"description": "Birth day valid for birthday_month; February 29 is allowed. Use 0 with birthday_month 0 when the birthday is unknown and this is not a birthday mailing."
},
"display_name": {
"type": "string",
"maxLength": 240,
"description": "Name on the envelope or address panel."
},
"birthday_year": {
"anyOf": [
{
"type": "integer",
"maximum": 9999,
"minimum": 1
},
{
"type": "null"
}
],
"description": "Known birth year, optional. Requires a valid full birth date that is not in the future. Omit or use null when unknown."
},
"greeting_name": {
"type": "string",
"maxLength": 240,
"description": "Name printed in the automatic greeting, such as Ida for \"Dear Ida,\". Defaults to display_name."
},
"birthday_month": {
"type": "integer",
"default": 0,
"maximum": 12,
"minimum": 0,
"description": "Birth month, 1 through 12, required with birthday_day when occasion.kind is birthday. Otherwise omit both or use 0 for both when unknown."
},
"anniversary_day": {
"type": "integer",
"maximum": 31,
"minimum": 0,
"description": "Optional anniversary day valid for anniversary_month; supply both fields together or omit both. Paired zeros mean unknown."
},
"mailing_address": {
"type": "object",
"required": [
"line1",
"locality",
"region",
"postal_code",
"country_code"
],
"properties": {
"line1": {
"type": "string",
"maxLength": 320,
"description": "Street address or postal delivery line supplied by the buyer."
},
"line2": {
"type": "string",
"default": "",
"maxLength": 320,
"description": "Optional second line, such as an apartment or suite. Omitted means empty."
},
"region": {
"type": "string",
"maxLength": 160,
"description": "State, province or region; use an empty string where the destination does not require one."
},
"locality": {
"type": "string",
"maxLength": 320,
"description": "City, town or postal locality."
},
"postal_code": {
"type": "string",
"maxLength": 48,
"description": "Postal or ZIP code; use an empty string where the destination does not use one."
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter uppercase ISO country code, such as US or CA. The recipient country determines the price and postal rules."
}
},
"description": "Recipient mailing address supplied and confirmed by the buyer.",
"additionalProperties": false
},
"address_confirmed": {
"type": "boolean",
"const": true,
"description": "Must be true: the buyer has confirmed the supplied mailing address."
},
"anniversary_month": {
"type": "integer",
"maximum": 12,
"minimum": 0,
"description": "Optional recipient anniversary month, paired with anniversary_day. Use 1 through 12, or 0 for both when unknown. Mailing timing uses occasion.month and occasion.day."
}
},
"description": "Buyer-supplied recipient details for this card. This does not create or select a saved member recipient.",
"additionalProperties": false
},
"design_key": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"description": "Exact card.design.key from search_cards, or its occasion_design_keys entry for the selected occasion when present. Private cards use design_key from read_private_content or compose_private_card."
},
"message_font": {
"enum": [
"serif",
"sans_serif",
"old_school",
"handwriting"
],
"type": "string",
"description": "Font for the personal message: serif, sans_serif, old_school or handwriting. Omission uses serif. Artwork lettering is unchanged."
},
"design_version": {
"type": "integer",
"maximum": 2147483646,
"description": "Matching card.design.version from the same search result, or design_version returned for the private composition. Never infer a version.",
"exclusiveMinimum": 0
},
"return_address": {
"type": "object",
"required": [
"display_name",
"mailing_address",
"source_kind"
],
"properties": {
"source_kind": {
"type": "string",
"const": "manual",
"description": "Must be manual: the buyer supplies this address; billing and saved Home addresses are not inferred."
},
"display_name": {
"type": "string",
"maxLength": 240,
"description": "Sender name printed with the return address."
},
"mailing_address": {
"type": "object",
"required": [
"line1",
"locality",
"region",
"postal_code",
"country_code"
],
"properties": {
"line1": {
"type": "string",
"maxLength": 320,
"description": "Street address or postal delivery line supplied by the buyer."
},
"line2": {
"type": "string",
"default": "",
"maxLength": 320,
"description": "Optional second line, such as an apartment or suite. Omitted means empty."
},
"region": {
"type": "string",
"maxLength": 160,
"description": "State, province or region; use an empty string where the destination does not require one."
},
"locality": {
"type": "string",
"maxLength": 320,
"description": "City, town or postal locality."
},
"postal_code": {
"type": "string",
"maxLength": 48,
"description": "Postal or ZIP code; use an empty string where the destination does not use one."
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter uppercase ISO country code, such as US or CA. The recipient country determines the price and postal rules."
}
},
"description": "Sender return mailing address supplied by the buyer.",
"additionalProperties": false
}
},
"description": "Required for every card format: the sender’s name and return mailing address supplied by the buyer. Not automatically obtained from billing details.",
"additionalProperties": false
},
"include_paddock_gift": {
"type": "boolean",
"description": "Include a complimentary personalized Paddock bookmark. For eligible new envelope orders, omission includes it; set false to opt out. The bookmark has the chosen artwork, a gift message naming the sender, and a unique QR code for one free card, including artist cards. Read the order’s returned paddock_gift: included, and omission_reason when it is not included. Explain it when useful or asked; no separate question or announcement is needed."
}
},
"description": "One manual guest card. Each card may have its own artwork, format, message, recipient, optional occasion and timing. Existing destination/calendar rules apply. No member, Property, recipient, card or calendar-event IDs.",
"additionalProperties": false
},
"maxItems": 500,
"minItems": 1,
"description": "One purchase containing 1–500 explicit card compositions in their supplied order. Mix any supported designs, formats, messages, recipients, occasions and dates. Do not group purchases by occasion. One card uses this same array."
},
"order_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "Parent order.id returned by prepare_order, revise_order or read_order. Use the matching order_access_token; a card ID cannot identify the purchase."
},
"request_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "New caller-generated UUID for this replacement, distinct from the original order ID. To recover a lost response, reuse this ID, the complete identical cards array, original order ID, token and expected_revision. Later edits use the returned replacement order."
},
"expected_revision": {
"type": "integer",
"maximum": 2147483646,
"description": "Current parent order.revision from prepare_order, revise_order or read_order. A mismatch fails with CONFLICT; read the order again before deciding whether to retry. Keep the original revision when recovering an identical replacement request.",
"exclusiveMinimum": 0
},
"order_access_token": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$",
"description": "Exact private order_access_token returned by prepare_order or revise_order for this order. Keep it secret; never invent it or put it in a public URL or log."
}
},
"additionalProperties": false
}revise_order output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"ok",
"data"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"required": [
"order",
"order_access_token",
"review_url",
"reused",
"preview_available",
"replaced_order_id"
],
"properties": {
"order": {
"type": "object",
"required": [
"id",
"revision",
"state",
"payment_state",
"refund_state",
"amount_cents",
"currency",
"card_count",
"tax_ready_count",
"quote_expires_at",
"checkout_url",
"cards"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"cards": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"revision",
"state",
"payment_state",
"refund_state",
"refund_review_reason",
"tax_review_reason",
"input",
"schedule",
"amount_cents",
"currency",
"offer_version",
"terms_version",
"title",
"artist_name",
"quote_expires_at",
"paddock_gift",
"fulfillment_status",
"mailed_at",
"cancellable"
],
"properties": {
"id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"input": {
"type": "object",
"required": [
"design_key",
"design_version",
"message",
"recipient"
],
"properties": {
"format": {
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
],
"type": "string",
"description": "Postcard, flat card in an envelope, or folded card in an envelope. Omit to select flat_card_in_envelope."
},
"message": {
"type": "string",
"maxLength": 4000,
"description": "Body of the personal message, at most 2000 Unicode characters. Paddock prints the greeting \"Dear {greeting_name or display_name},\" above it automatically, so do not start the message with a salutation. Printed artwork wording is separate."
},
"occasion": {
"type": "object",
"required": [
"kind",
"calendar"
],
"properties": {
"day": {
"type": "integer",
"maximum": 31,
"minimum": 1,
"description": "Day valid for occasion.month, required for personal annual occasions such as anniversary. Birthdays use recipient.birthday_day."
},
"kind": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Exact catalog occasion ID, such as birthday, thank_you or just_because. Use just_because with send_on for a one-time mailing date. Use underscores, not display labels or hyphens."
},
"month": {
"type": "integer",
"maximum": 12,
"minimum": 1,
"description": "Required with day for a personal annual occasion such as anniversary. Omit for holidays and one-off occasions; birthdays use recipient.birthday_month."
},
"send_on": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Requested mailing date as YYYY-MM-DD, only for one-off occasions such as just_because. Omit for the next available mailing date. This is not a delivery guarantee."
},
"calendar": {
"type": "string",
"const": "us-western-v1",
"description": "Must be us-western-v1, the supported occasion calendar."
}
},
"description": "Optional occasion and timing context, independent of the selected artwork. Omit for an ordinary just-because card.",
"additionalProperties": false
},
"recipient": {
"type": "object",
"required": [
"display_name",
"birthday_month",
"birthday_day",
"mailing_address",
"address_confirmed",
"origin"
],
"properties": {
"origin": {
"type": "string",
"const": "manual",
"description": "Must be manual: recipient details come from the buyer, without a member recipient ID or Contacts import."
},
"birthday_day": {
"type": "integer",
"maximum": 31,
"minimum": 0
},
"display_name": {
"type": "string",
"maxLength": 240,
"description": "Name on the envelope or address panel."
},
"birthday_year": {
"anyOf": [
{
"type": "integer",
"maximum": 9999,
"minimum": 1
},
{
"type": "null"
}
],
"description": "Known birth year, optional. Requires a valid full birth date that is not in the future. Omit or use null when unknown."
},
"greeting_name": {
"type": "string",
"maxLength": 240,
"description": "Name printed in the automatic greeting, such as Ida for \"Dear Ida,\". Defaults to display_name."
},
"birthday_month": {
"type": "integer",
"maximum": 12,
"minimum": 0
},
"anniversary_day": {
"type": "integer",
"maximum": 31,
"minimum": 0,
"description": "Optional anniversary day valid for anniversary_month; supply both fields together or omit both. Paired zeros mean unknown."
},
"mailing_address": {
"type": "object",
"required": [
"line1",
"line2",
"locality",
"region",
"postal_code",
"country_code"
],
"properties": {
"line1": {
"type": "string",
"maxLength": 320,
"description": "Street address or postal delivery line supplied by the buyer."
},
"line2": {
"type": "string",
"maxLength": 320
},
"region": {
"type": "string",
"maxLength": 160,
"description": "State, province or region; use an empty string where the destination does not require one."
},
"locality": {
"type": "string",
"maxLength": 320,
"description": "City, town or postal locality."
},
"postal_code": {
"type": "string",
"maxLength": 48,
"description": "Postal or ZIP code; use an empty string where the destination does not use one."
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter uppercase ISO country code, such as US or CA. The recipient country determines the price and postal rules."
}
},
"additionalProperties": false
},
"address_confirmed": {
"type": "boolean",
"const": true,
"description": "Must be true: the buyer has confirmed the supplied mailing address."
},
"anniversary_month": {
"type": "integer",
"maximum": 12,
"minimum": 0,
"description": "Optional recipient anniversary month, paired with anniversary_day. Use 1 through 12, or 0 for both when unknown. Mailing timing uses occasion.month and occasion.day."
}
},
"additionalProperties": false
},
"design_key": {
"type": "string",
"maxLength": 160,
"minLength": 1,
"description": "Exact card.design.key from search_cards, or its occasion_design_keys entry for the selected occasion when present. Private cards use design_key from read_private_content or compose_private_card."
},
"message_font": {
"enum": [
"serif",
"sans_serif",
"old_school",
"handwriting"
],
"type": "string",
"description": "Font for the personal message: serif, sans_serif, old_school or handwriting. Omission uses serif. Artwork lettering is unchanged."
},
"design_version": {
"type": "integer",
"maximum": 2147483646,
"description": "Matching card.design.version from the same search result, or design_version returned for the private composition. Never infer a version.",
"exclusiveMinimum": 0
},
"return_address": {
"type": "object",
"required": [
"display_name",
"mailing_address",
"source_kind"
],
"properties": {
"source_kind": {
"type": "string",
"const": "manual",
"description": "Must be manual: the buyer supplies this address; billing and saved Home addresses are not inferred."
},
"display_name": {
"type": "string",
"maxLength": 240,
"description": "Sender name printed with the return address."
},
"mailing_address": {
"type": "object",
"required": [
"line1",
"line2",
"locality",
"region",
"postal_code",
"country_code"
],
"properties": {
"line1": {
"type": "string",
"maxLength": 320,
"description": "Street address or postal delivery line supplied by the buyer."
},
"line2": {
"type": "string",
"maxLength": 320
},
"region": {
"type": "string",
"maxLength": 160,
"description": "State, province or region; use an empty string where the destination does not require one."
},
"locality": {
"type": "string",
"maxLength": 320,
"description": "City, town or postal locality."
},
"postal_code": {
"type": "string",
"maxLength": 48,
"description": "Postal or ZIP code; use an empty string where the destination does not use one."
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "Two-letter uppercase ISO country code, such as US or CA. The recipient country determines the price and postal rules."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"include_paddock_gift": {
"type": "boolean",
"description": "Include a complimentary personalized Paddock bookmark. For eligible new envelope orders, omission includes it; set false to opt out. The bookmark has the chosen artwork, a gift message naming the sender, and a unique QR code for one free card, including artist cards. Read the order’s returned paddock_gift: included, and omission_reason when it is not included. Explain it when useful or asked; no separate question or announcement is needed."
}
},
"additionalProperties": false
},
"state": {
"enum": [
"prepared",
"checkout_pending",
"paid",
"cancel_requested",
"cancelled"
],
"type": "string"
},
"title": {
"type": "string"
},
"currency": {
"type": "string",
"const": "usd"
},
"revision": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"schedule": {
"type": "object",
"required": [
"time_zone",
"birthday_date",
"send_date",
"collection_date",
"arrival_start",
"arrival_end",
"edit_deadline",
"post_by",
"estimate_basis",
"late",
"leap_day_observed",
"next_year"
],
"properties": {
"late": {
"type": "boolean"
},
"one_off": {
"type": "boolean",
"const": true
},
"post_by": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"next_year": {
"type": "boolean"
},
"send_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"time_zone": {
"type": "string"
},
"arrival_end": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"arrival_start": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"birthday_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"edit_deadline": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"estimate_basis": {
"type": "string"
},
"collection_date": {
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
},
"leap_day_observed": {
"type": "boolean"
}
},
"additionalProperties": false
},
"mailed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
{
"type": "null"
}
]
},
"artist_name": {
"type": [
"string",
"null"
]
},
"cancellable": {
"type": "boolean"
},
"amount_cents": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"paddock_gift": {
"type": "object",
"required": [
"included",
"omission_reason"
],
"properties": {
"included": {
"type": "boolean"
},
"omission_reason": {
"anyOf": [
{
"enum": [
"declined",
"no_envelope",
"international_delivery",
"offer_unavailable",
"not_selected"
],
"type": "string"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"product_spec": {
"type": "object",
"required": [
"version",
"format",
"title",
"paper",
"size_in",
"artwork_surface",
"message_surface",
"envelope_included",
"paper_detail",
"personalization",
"printed_text"
],
"properties": {
"paper": {
"type": "string",
"description": "Card stock by its confirmed basis-weight designation."
},
"title": {
"type": "string"
},
"format": {
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
],
"type": "string"
},
"size_in": {
"type": "object",
"required": [
"width",
"height"
],
"properties": {
"width": {
"type": "number",
"exclusiveMinimum": 0
},
"height": {
"type": "number",
"exclusiveMinimum": 0
}
},
"description": "Finished size in inches; the closed size for the folded card.",
"additionalProperties": false
},
"version": {
"type": "string",
"maxLength": 60,
"minLength": 1
},
"envelope": {
"type": "object",
"required": [
"size_in",
"addressing"
],
"properties": {
"size_in": {
"type": "object",
"required": [
"width",
"height"
],
"properties": {
"width": {
"type": "number",
"exclusiveMinimum": 0
},
"height": {
"type": "number",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"addressing": {
"type": "string"
}
},
"description": "Present only for formats mailed in an envelope.",
"additionalProperties": false
},
"open_size_in": {
"type": "object",
"required": [
"width",
"height"
],
"properties": {
"width": {
"type": "number",
"exclusiveMinimum": 0
},
"height": {
"type": "number",
"exclusiveMinimum": 0
}
},
"description": "Folded card only: size when opened.",
"additionalProperties": false
},
"paper_detail": {
"type": "object",
"required": [
"basis_weight"
],
"properties": {
"gsm": {
"type": "number",
"description": "Manufacturer-stated grammage; absent when unknown.",
"exclusiveMinimum": 0
},
"color": {
"type": "string",
"description": "Absent until confirmed for the stock in use."
},
"finish": {
"type": "string",
"description": "Absent until confirmed for the stock in use."
},
"caliper_in": {
"type": "number",
"description": "Measured sheet thickness in inches; absent when unknown.",
"exclusiveMinimum": 0
},
"basis_weight": {
"type": "string"
}
},
"additionalProperties": false
},
"printed_text": {
"type": "string"
},
"artwork_surface": {
"enum": [
"front",
"front cover"
],
"type": "string"
},
"message_surface": {
"type": "string",
"description": "Where Paddock prints the personal message."
},
"personalization": {
"type": "object",
"required": [
"fonts",
"automatic_greeting",
"max_message_chars",
"fit_check"
],
"properties": {
"fonts": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"fit_check": {
"type": "string"
},
"max_message_chars": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"automatic_greeting": {
"type": "string"
}
},
"additionalProperties": false
},
"envelope_included": {
"type": "boolean"
}
},
"additionalProperties": false
},
"refund_state": {
"enum": [
"none",
"pending",
"processing",
"succeeded",
"failed",
"unknown"
],
"type": "string"
},
"offer_version": {
"type": "string"
},
"payment_state": {
"enum": [
"unpaid",
"pending",
"paid",
"failed",
"expired",
"refunding",
"refunded"
],
"type": "string"
},
"terms_version": {
"type": "string"
},
"quote_expires_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"tax_review_reason": {
"type": [
"string",
"null"
]
},
"fulfillment_status": {
"anyOf": [
{
"enum": [
"scheduled",
"preparing",
"ready",
"mailed",
"cancel_requested",
"cancelled"
],
"type": "string"
},
{
"type": "null"
}
]
},
"refund_review_reason": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"maxItems": 500,
"minItems": 1
},
"state": {
"enum": [
"prepared",
"checkout_pending",
"paid",
"cancel_requested",
"cancelled"
],
"type": "string"
},
"currency": {
"type": "string",
"const": "usd"
},
"revision": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"card_count": {
"type": "integer",
"maximum": 500,
"minimum": 1
},
"amount_cents": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"checkout_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"refund_state": {
"enum": [
"none",
"pending",
"partial",
"succeeded",
"failed",
"unknown"
],
"type": "string"
},
"payment_state": {
"enum": [
"unpaid",
"pending",
"paid",
"failed",
"expired",
"refunding",
"refunded"
],
"type": "string"
},
"tax_ready_count": {
"type": "integer",
"maximum": 500,
"minimum": 0
},
"customer_content": {
"type": "object",
"required": [
"rights_required",
"rights_accepted",
"terms_version"
],
"properties": {
"terms_version": {
"type": "string",
"const": "customer-print-v1"
},
"rights_accepted": {
"type": "boolean"
},
"rights_required": {
"type": "boolean"
}
},
"additionalProperties": false
},
"quote_expires_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"additionalProperties": false
},
"reused": {
"type": "boolean"
},
"review_url": {
"type": "string",
"format": "uri"
},
"payment_required": {
"type": "boolean"
},
"preview_available": {
"type": "boolean",
"description": "At least one current card is eligible for optional preview_card. Images render only when requested; access and current state are rechecked then."
},
"replaced_order_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "Parent order.id returned by prepare_order, revise_order or read_order. Use the matching order_access_token; a card ID cannot identify the purchase."
},
"order_access_token": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}revise_order annotations
{
"title": "Revise an unpaid order",
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": true
}preview_card — Preview a card
Advertised read-only
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.
preview_card input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"order_id",
"order_access_token"
],
"properties": {
"faces": {
"enum": [
"outside",
"inside",
"both"
],
"type": "string",
"default": "both",
"description": "Surfaces to render; omission means both. Outside/inside are front/back for postcards and flat cards, or cover/inside for folded cards."
},
"card_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "ID from this order.cards[].id. Required when the order has more than one card; omit to preview its only card."
},
"order_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "Parent order.id returned by prepare_order, revise_order or read_order. Use the matching private token."
},
"expected_revision": {
"type": "integer",
"maximum": 2147483646,
"description": "Parent order.revision returned by prepare_order, revise_order or read_order. If supplied, a mismatch fails with CONFLICT; omission previews the current revision. Preview again after changes.",
"exclusiveMinimum": 0
},
"order_access_token": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$",
"description": "Exact private order_access_token returned by prepare_order or revise_order for this order. Keep it private and never invent one."
}
},
"additionalProperties": false
}preview_card output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"ok",
"data"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"required": [
"order_id",
"order_revision",
"card_id",
"card_revision",
"format",
"title",
"recipient_name",
"preview_url",
"images"
],
"properties": {
"title": {
"type": "string",
"maxLength": 200
},
"format": {
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
],
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "object",
"required": [
"face",
"side",
"label",
"mime_type",
"width",
"height",
"bytes"
],
"properties": {
"face": {
"enum": [
"outside",
"inside"
],
"type": "string"
},
"side": {
"enum": [
"front",
"back"
],
"type": "string"
},
"bytes": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"label": {
"type": "string"
},
"width": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"height": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"mime_type": {
"type": "string",
"const": "image/png"
}
},
"additionalProperties": false
},
"maxItems": 2,
"minItems": 1,
"description": "Image bytes are in the result content blocks, in this order, not here."
},
"card_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"order_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"preview_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
],
"description": "Browser page showing the same images for every card in this order. No payment control."
},
"card_revision": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"order_revision": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"recipient_name": {
"type": "string",
"maxLength": 200
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}preview_card annotations
{
"title": "Preview a card",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}open_private_content — Open private uploads
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.
open_private_content input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"order_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "Existing unpaid order.id from prepare_order, revise_order or read_order. Supply its matching order_access_token to reopen that draft’s upload scope; omit both fields for a new scope."
},
"order_access_token": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$",
"description": "Matching private token for the existing unpaid order, returned by prepare_order, revise_order or its open_private_content scope. Required with order_id; omit both for a new scope. Never invent a token."
}
},
"additionalProperties": false
}open_private_content output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"ok",
"data"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"required": [
"scope_id",
"order_access_token",
"upload_url",
"expires_at",
"policy_version",
"policy",
"next"
],
"properties": {
"next": {
"type": "string"
},
"policy": {
"type": "string"
},
"scope_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
},
"expires_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"upload_url": {
"type": "string",
"format": "uri"
},
"policy_version": {
"type": "string",
"const": "customer-print-v1"
},
"order_access_token": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}open_private_content annotations
{
"title": "Open private uploads",
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false,
"destructiveHint": false
}read_private_content — Read private uploads
Advertised read-only
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.
read_private_content input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"scope_id",
"order_access_token"
],
"properties": {
"scope_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "Exact scope_id returned by open_private_content for the uploads to list."
},
"order_access_token": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$",
"description": "Exact private order_access_token returned by open_private_content for this scope. Keep it private and never invent one."
}
},
"additionalProperties": false
}read_private_content output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"ok",
"data"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"required": [
"scope_id",
"expires_at",
"status",
"assets",
"compositions"
],
"properties": {
"assets": {
"type": "array",
"items": {
"type": "object",
"required": [
"asset_id",
"kind"
],
"properties": {
"kind": {
"enum": [
"artwork",
"logo"
],
"type": "string"
},
"asset_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
}
},
"status": {
"enum": [
"active",
"deleting",
"deleted"
],
"type": "string"
},
"scope_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"expires_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"compositions": {
"type": "array",
"items": {
"type": "object",
"required": [
"composition_id",
"title",
"design_key",
"design_version"
],
"properties": {
"title": {
"type": "string",
"maxLength": 120
},
"design_key": {
"type": "string",
"pattern": "^customer_[0-9a-f-]{36}$"
},
"composition_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"design_version": {
"type": "number",
"const": 1
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}read_private_content annotations
{
"title": "Read private uploads",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}compose_private_card — Compose a private card
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.
compose_private_card input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"scope_id",
"order_access_token",
"composition_id",
"title"
],
"properties": {
"title": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Short private name for this card, shown to the buyer only."
},
"qr_url": {
"type": "string",
"maxLength": 512,
"description": "Full HTTP(S) destination printed as a QR code; Paddock does not fetch it. A QR-only card needs no uploaded asset."
},
"scope_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "Exact scope_id returned by open_private_content. All supplied asset IDs must belong to this scope."
},
"logo_asset_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "asset_id with kind logo from read_private_content in this scope. Optional when artwork_asset_id or qr_url is supplied."
},
"composition_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "Caller-generated UUID for this composition. Retrying with the same ID and identical fields returns the same card (reused: true); the same ID with different fields is CONFLICT, so use a new UUID for a different card."
},
"artwork_asset_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "asset_id with kind artwork from read_private_content in this scope. Supply at least one artwork asset, logo asset or QR URL."
},
"order_access_token": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$",
"description": "Exact private order_access_token returned by open_private_content for this scope. Keep it private and never invent one."
}
},
"additionalProperties": false
}compose_private_card output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"ok",
"data"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"required": [
"composition_id",
"design_key",
"design_version",
"title",
"low_resolution",
"reused"
],
"properties": {
"title": {
"type": "string",
"maxLength": 120
},
"reused": {
"type": "boolean"
},
"design_key": {
"type": "string",
"pattern": "^customer_[0-9a-f-]{36}$"
},
"composition_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"design_version": {
"type": "number",
"const": 1
},
"low_resolution": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}compose_private_card annotations
{
"title": "Compose a private card",
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}delete_private_content — Delete private uploads
Advertised destructive
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.
delete_private_content input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"scope_id",
"order_access_token"
],
"properties": {
"scope_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "Exact scope_id from open_private_content whose unused content the buyer wants deleted."
},
"order_access_token": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$",
"description": "Exact private order_access_token returned by open_private_content for this scope. Keep it private and never invent one."
}
},
"additionalProperties": false
}delete_private_content output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"ok",
"data"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"required": [
"accepted",
"state"
],
"properties": {
"state": {
"enum": [
"active",
"deleting",
"deleted"
],
"type": "string"
},
"accepted": {
"type": "boolean",
"const": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}delete_private_content annotations
{
"title": "Delete private uploads",
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": true
}pay_order — Pay for an order
Advertised destructiveOpen-world
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.
pay_order input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"order_id",
"order_access_token",
"expected_revision"
],
"properties": {
"order_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "Parent order.id returned by prepare_order, revise_order or read_order. Use the matching order_access_token; a card ID cannot identify the purchase."
},
"expected_revision": {
"type": "integer",
"maximum": 2147483646,
"description": "Parent order.revision for the exact purchase shown to the buyer, returned by prepare_order, revise_order or read_order. A mismatch fails with CONFLICT; read the order and obtain approval for any changed purchase.",
"exclusiveMinimum": 0
},
"order_access_token": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$",
"description": "Exact private order_access_token returned by prepare_order or revise_order for this order. Keep it secret; never invent it or put it in a public URL or log."
}
},
"additionalProperties": false
}pay_order output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"ok",
"data"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"data": {
"oneOf": [
{
"type": "object",
"required": [
"order_id",
"revision",
"amount_cents",
"currency",
"status",
"action",
"action_url"
],
"properties": {
"action": {
"enum": [
"connect_and_approve",
"approve_purchase",
"authenticate_payment"
],
"type": "string"
},
"status": {
"type": "string",
"const": "requires_action"
},
"currency": {
"type": "string",
"const": "usd"
},
"order_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "Parent order.id returned by prepare_order, revise_order or read_order. Use the matching order_access_token; a card ID cannot identify the purchase."
},
"revision": {
"type": "integer",
"maximum": 2147483646,
"exclusiveMinimum": 0
},
"action_url": {
"type": "string",
"format": "uri"
},
"amount_cents": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"retry_after_seconds": {
"type": "integer",
"maximum": 300,
"minimum": 1
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"order_id",
"revision",
"amount_cents",
"currency",
"status",
"retry_after_seconds"
],
"properties": {
"status": {
"type": "string",
"const": "processing"
},
"currency": {
"type": "string",
"const": "usd"
},
"order_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "Parent order.id returned by prepare_order, revise_order or read_order. Use the matching order_access_token; a card ID cannot identify the purchase."
},
"revision": {
"type": "integer",
"maximum": 2147483646,
"exclusiveMinimum": 0
},
"amount_cents": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"retry_after_seconds": {
"type": "integer",
"maximum": 300,
"minimum": 1
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"order_id",
"revision",
"amount_cents",
"currency",
"status"
],
"properties": {
"status": {
"type": "string",
"const": "paid"
},
"currency": {
"type": "string",
"const": "usd"
},
"order_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "Parent order.id returned by prepare_order, revise_order or read_order. Use the matching order_access_token; a card ID cannot identify the purchase."
},
"revision": {
"type": "integer",
"maximum": 2147483646,
"exclusiveMinimum": 0
},
"amount_cents": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"order_id",
"revision",
"amount_cents",
"currency",
"status"
],
"properties": {
"status": {
"type": "string",
"const": "failed"
},
"currency": {
"type": "string",
"const": "usd"
},
"order_id": {
"type": "string",
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
"description": "Parent order.id returned by prepare_order, revise_order or read_order. Use the matching order_access_token; a card ID cannot identify the purchase."
},
"revision": {
"type": "integer",
"maximum": 2147483646,
"exclusiveMinimum": 0
},
"amount_cents": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
}
},
"additionalProperties": false
}
]
}
},
"additionalProperties": false
}pay_order annotations
{
"title": "Pay for an order",
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": true
}list_orders — List your orders
Advertised read-only
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.
list_orders input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"limit": {
"type": "integer",
"default": 10,
"maximum": 50,
"minimum": 1,
"description": "Maximum orders in this page, from 1 to 50. Omission returns 10, newest first."
},
"cursor": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,256}$",
"description": "Exact next_cursor from the previous list_orders result. Omit for the newest page. A cursor grants no access."
}
},
"additionalProperties": false
}list_orders output schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"ok",
"data"
],
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"required": [
"orders",
"next_cursor"
],
"properties": {
"orders": {
"type": "array",
"items": {
"type": "object",
"required": [
"order_id",
"created_at",
"revision",
"card_count",
"amount_cents",
"currency",
"state",
"payment_state",
"refund_state"
],
"properties": {
"state": {
"type": "string"
},
"currency": {
"type": "string",
"const": "usd"
},
"order_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"revision": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"card_count": {
"type": "integer",
"maximum": 500,
"minimum": 1
},
"created_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"amount_cents": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"refund_state": {
"type": "string"
},
"payment_state": {
"type": "string"
}
},
"additionalProperties": false
},
"maxItems": 50
},
"next_cursor": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}list_orders annotations
{
"title": "List your orders",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}Prompts
2 advertised
find_card — Find a Paddock card
Find cards in the current catalog by occasion, artwork, format and recipient-country prices.
- request
- What card you want to find or prepare, including the occasion, artwork or style. (required)
- destination_country
- Recipient country, as a two-letter code such as US or CA. Omit when unknown.
prepare_card_order — Prepare a Paddock card order
Help the buyer choose cards and confirm the required details before preparing one unpaid purchase. Payment needs separate buyer approval.
- request
- What card you want to find or prepare, including the occasion, artwork or style. (required)
- destination_country
- Recipient country, as a two-letter code such as US or CA. Omit when unknown.
Resources
1 advertised
paddock_guide — Paddock card guide
How to find cards, prepare an unpaid order, and follow buyer-approved payment and mailing status.
paddock_guide URI
paddock://guide30-day availability
Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.
- Successful checks
- 1 of 1 (100%)
- Average latency
- 1388 ms
- 95th percentile latency
- 1388 ms
Maintenance history
Public check and source-refresh events. Editorial and ownership records remain private.
- · probe · passed · 1388 ms · metadata changed · 13 tool(s), 1 resource(s), 0 resource template(s), 2 prompt(s)
Connect from your client
Each snippet registers the same endpoint; pick the client you use.
Claude Code
Claude Code configuration
claude mcp add --transport http paddock-cards-mcp https://api.paddock.so/agent-commerce/mcpCodex
Codex configuration
codex mcp add paddock-cards-mcp --url https://api.paddock.so/agent-commerce/mcpCursor
Cursor configuration
{
"mcpServers": {
"paddock-cards-mcp": {
"url": "https://api.paddock.so/agent-commerce/mcp"
}
}
}Cline
Cline configuration
{
"mcpServers": {
"paddock-cards-mcp": {
"type": "streamableHttp",
"url": "https://api.paddock.so/agent-commerce/mcp",
"disabled": false
}
}
}VS Code
VS Code configuration
{
"servers": {
"paddock-cards-mcp": {
"type": "http",
"url": "https://api.paddock.so/agent-commerce/mcp"
}
}
}Gemini CLI
Gemini CLI configuration
gemini mcp add --transport http paddock-cards-mcp https://api.paddock.so/agent-commerce/mcpClaude Desktop
Claude Desktop configuration
{
"mcpServers": {
"paddock-cards-mcp": {
"url": "https://api.paddock.so/agent-commerce/mcp"
}
}
}Windsurf
Windsurf configuration
{
"mcpServers": {
"paddock-cards-mcp": {
"serverUrl": "https://api.paddock.so/agent-commerce/mcp"
}
}
}Let your agent find its tools
Find servers like Paddock Cards MCP from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.
Other commerce servers
Do you run Paddock Cards MCP?
Prove ownership with a DNS record, a well-known file, or your Official MCP Registry entry, and your edits publish immediately. Proofs are re-checked weekly; admins can still hide or remove a listing.