Paddock Cards
Send personalized greeting cards through your AI assistant. Paddock prints and mails them.
¿Debería usar esto?
Calidad y seguridad
A
Hallazgos (1)
- LOWTool 'report_feedback' description lacks action verben report_feedback
Basado en el análisis automatizado de las definiciones de herramientas y el cumplimiento del protocolo.
Costo de contexto
~14,035Tokens (definiciones de herramientas)
~25.6 KBTamaño de respuesta típico
Impacto significativo en la atención (10.96% del contexto de 128k)
Este es el número aproximado de tokens que se consumen cada vez que las herramientas del servidor se cargan en el contexto de un modelo. Los recuentos más altos reducen la atención disponible para otras tareas.
Instalar
Instalación con un clic
Agrega esto a tu archivo `claude_desktop_config.json`:
{
"mcpServers": {
"cards": {
"url": "https://api.paddock.so/agent-commerce/mcp"
}
}
}Puntos de conexión remotos
https://api.paddock.so/agent-commerce/mcpstreamable-httpQué puede hacer
Inventario de herramientas
Herramientas (5)
🟢 Solo lectura🟡 Escritura🔴 Eliminación⚪ Desconocido
🟢search_cards(query, occasion, tone, humor, kind, ...)
Find currently available ordinary and artist cards by occasion, tone, format, artist or budget. Returns three concise matches by default; use next_cursor for more. Public browsing needs no account or key.
Esquema de entrada
{
"type": "object",
"properties": {
"query": {
"type": "string",
"maxLength": 300
},
"occasion": {
"type": "string",
"maxLength": 100
},
"tone": {
"description": "Mood such as warm, cheerful, elegant or gentle. For funny cards, use humor instead.",
"type": "string",
"maxLength": 40
},
"humor": {
"type": "string",
"enum": [
"any",
"none",
"light",
"playful",
"funny"
]
},
"kind": {
"type": "string",
"enum": [
"any",
"standard",
"artist"
]
},
"require_printed_text": {
"description": "Filter verified wording already printed in the artwork. Unknown wording does not match absent or present.",
"type": "string",
"enum": [
"any",
"absent",
"present"
]
},
"printed_text_contains": {
"description": "Required phrase in verified artwork lettering, matched without case sensitivity. This does not search the customizable message.",
"type": "string",
"minLength": 1,
"maxLength": 200
},
"format": {
"description": "Postcard, flat card in an envelope, or folded card in an envelope. Omit to select flat_card_in_envelope.",
"type": "string",
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
]
},
"max_price_cents": {
"type": "integer",
"minimum": 0,
"maximum": 1000000
},
"artist": {
"type": "string",
"maxLength": 120
},
"limit": {
"default": 3,
"type": "integer",
"minimum": 1,
"maximum": 50
},
"cursor": {
"type": "string",
"pattern": "^(?:\\d{1,6})?$"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}Esquema de salida
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"properties": {
"schema": {
"type": "string",
"const": "paddock.search.compact.v1"
},
"catalog_revision": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"complete": {
"type": "boolean"
},
"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)))$"
},
"total": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"constraints": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"detail": {
"type": "string"
}
},
"required": [
"code",
"detail"
],
"additionalProperties": false
}
},
"unmet": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"detail": {
"type": "string"
}
},
"required": [
"code",
"detail"
],
"additionalProperties": false
}
},
"occasion_resolved": {
"type": [
"string",
"null"
]
},
"artist_resolved": {
"type": [
"string",
"null"
]
},
"currency": {
"type": "string",
"const": "usd"
},
"price_includes": {
"anyOf": [
{
"type": "object",
"properties": {
"postage": {
"type": "boolean"
},
"tax": {
"type": "boolean"
}
},
"required": [
"postage",
"tax"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"policy": {
"type": "string"
},
"results": {
"maxItems": 50,
"type": "array",
"items": {
"type": "object",
"properties": {
"card": {
"type": "object",
"properties": {
"card_id": {
"type": "string"
},
"kind": {
"type": "string",
"enum": [
"standard",
"artist"
]
},
"design": {
"type": "object",
"properties": {
"key": {
"type": "string"
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"key",
"version"
],
"additionalProperties": false
},
"occasion_design_keys": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"title": {
"type": "string"
},
"subtitle": {
"type": "string"
},
"primary_occasion": {
"type": "string"
},
"occasions": {
"type": "array",
"items": {
"type": "string"
}
},
"description": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"available",
"unknown"
]
},
"text": {
"type": [
"string",
"null"
]
}
},
"required": [
"status",
"text"
],
"additionalProperties": false
},
"printed_text": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"verified_absent",
"verified_present",
"unknown"
]
},
"text": {
"type": [
"string",
"null"
]
},
"note": {
"type": "string"
}
},
"required": [
"status",
"text"
],
"additionalProperties": false
},
"tone": {
"type": "array",
"items": {
"type": "string",
"enum": [
"warm",
"cheerful",
"playful",
"elegant",
"calm",
"gentle",
"romantic",
"festive",
"nostalgic",
"whimsical",
"sincere",
"celebratory",
"serene",
"bold"
]
}
},
"humor": {
"type": "string",
"enum": [
"none",
"light",
"playful",
"unknown"
]
},
"subjects": {
"type": "array",
"items": {
"type": "string"
}
},
"palette": {
"type": "array",
"items": {
"type": "string"
}
},
"contains_people": {
"type": [
"boolean",
"null"
]
},
"contains_animals": {
"type": [
"boolean",
"null"
]
},
"artist": {
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
]
},
"slug": {
"type": [
"string",
"null"
]
},
"url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
}
},
"required": [
"name",
"slug",
"url"
],
"additionalProperties": false
},
"image": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"formats": {
"type": "array",
"items": {
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
]
},
"cents": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"orderable": {
"type": "boolean"
},
"reason": {
"type": "string",
"enum": [
"CARD_SAMPLE_ACCEPTANCE_REQUIRED",
"CARD_ARTWORK_ACCEPTANCE_REQUIRED",
"ARTIST_PRINT_SETUP_REQUIRED",
"CATALOG_ARTWORK_UNAVAILABLE",
"OFFER_EXPIRED",
"AVAILABILITY_UNVERIFIED"
]
}
},
"required": [
"format",
"cents",
"orderable"
],
"additionalProperties": false
}
},
"from_cents": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
}
},
"required": [
"card_id",
"kind",
"design",
"title",
"primary_occasion",
"occasions",
"description",
"printed_text",
"tone",
"humor",
"subjects",
"palette",
"contains_people",
"contains_animals",
"image",
"formats",
"from_cents"
],
"additionalProperties": false
},
"selected_format": {
"anyOf": [
{
"type": "string",
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
]
},
{
"type": "null"
}
]
},
"total_cents": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"score": {
"type": "number"
},
"match_reasons": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"card",
"selected_format",
"total_cents",
"score",
"match_reasons"
],
"additionalProperties": false
}
}
},
"required": [
"schema",
"catalog_revision",
"complete",
"generated_at",
"total",
"next_cursor",
"constraints",
"unmet",
"occasion_resolved",
"artist_resolved",
"currency",
"price_includes",
"policy",
"results"
],
"additionalProperties": false
}
},
"required": [
"ok",
"data"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}⚪prepare_order(request_id, cards, order_access_token)
Prepare one unpaid purchase of 1–500 cards, mixed across any occasions, designs, formats, messages, recipients and dates. One card uses the same cards array. Return per-card previews, the exact sum of current per-card prices, one human review/payment URL and a private order_access_token. No charge or mailing is authorized here. The 500-card/4-MiB bounds are technical request limits. Use a caller-generated UUID request_id; for recoverable first requests, generate and privately store a fresh cryptographically random 43-character base64url order_access_token before calling. Retry that ID only with the same token and unchanged cards. If omitted, the server generates the token; losing that response requires a new ID for another unpaid purchase. Validation issues identify zero-based card indices without copying private content.
Esquema de entrada
{
"type": "object",
"properties": {
"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}$"
},
"cards": {
"minItems": 1,
"maxItems": 500,
"type": "array",
"items": {
"type": "object",
"properties": {
"design_key": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"design_version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 2147483646
},
"message": {
"type": "string",
"maxLength": 4000,
"description": "Personal message, at most 2000 Unicode characters. Printed artwork wording is separate."
},
"format": {
"description": "Postcard, flat card in an envelope, or folded card in an envelope. Omit to select flat_card_in_envelope.",
"type": "string",
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
]
},
"message_font": {
"type": "string",
"enum": [
"serif",
"sans_serif",
"old_school",
"handwriting"
]
},
"include_paddock_gift": {
"type": "boolean"
},
"recipient": {
"type": "object",
"properties": {
"display_name": {
"type": "string",
"maxLength": 240
},
"greeting_name": {
"type": "string",
"maxLength": 240
},
"birthday_month": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 12
},
"birthday_day": {
"default": 0,
"type": "integer",
"minimum": 0,
"maximum": 31
},
"birthday_year": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 9999
},
{
"type": "null"
}
]
},
"anniversary_month": {
"type": "integer",
"minimum": 0,
"maximum": 12
},
"anniversary_day": {
"type": "integer",
"minimum": 0,
"maximum": 31
},
"mailing_address": {
"type": "object",
"properties": {
"line1": {
"type": "string",
"maxLength": 320
},
"line2": {
"type": "string",
"maxLength": 320
},
"locality": {
"type": "string",
"maxLength": 320
},
"region": {
"type": "string",
"maxLength": 160
},
"postal_code": {
"type": "string",
"maxLength": 48
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$"
}
},
"required": [
"line1",
"line2",
"locality",
"region",
"postal_code",
"country_code"
],
"additionalProperties": false
},
"address_confirmed": {
"type": "boolean",
"const": true
},
"origin": {
"type": "string",
"const": "manual"
}
},
"required": [
"display_name",
"mailing_address",
"address_confirmed",
"origin"
],
"additionalProperties": false
},
"return_address": {
"type": "object",
"properties": {
"display_name": {
"type": "string",
"maxLength": 240
},
"mailing_address": {
"type": "object",
"properties": {
"line1": {
"type": "string",
"maxLength": 320
},
"line2": {
"type": "string",
"maxLength": 320
},
"locality": {
"type": "string",
"maxLength": 320
},
"region": {
"type": "string",
"maxLength": 160
},
"postal_code": {
"type": "string",
"maxLength": 48
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$"
}
},
"required": [
"line1",
"line2",
"locality",
"region",
"postal_code",
"country_code"
],
"additionalProperties": false
},
"source_kind": {
"type": "string",
"const": "manual"
}
},
"required": [
"display_name",
"mailing_address",
"source_kind"
],
"additionalProperties": false
},
"occasion": {
"description": "Optional occasion and timing context, independent of the selected artwork. Omit for an ordinary just-because card.",
"type": "object",
"properties": {
"kind": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"calendar": {
"type": "string",
"const": "us-western-v1"
},
"month": {
"type": "integer",
"minimum": 1,
"maximum": 12
},
"day": {
"type": "integer",
"minimum": 1,
"maximum": 31
},
"send_on": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
}
},
"required": [
"kind",
"calendar"
],
"additionalProperties": false
}
},
"required": [
"design_key",
"design_version",
"message",
"recipient"
],
"additionalProperties": false,
"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."
},
"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_access_token": {
"description": "Optionally generate and privately store 32 cryptographically random bytes encoded as 43 base64url characters before the first request. Reuse that token with the same request_id and unchanged cards to recover a lost response. If omitted, the server generates and returns the capability. Existing purchase capabilities cannot be replaced.",
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$"
}
},
"required": [
"request_id",
"cards"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}Esquema de salida
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"properties": {
"order": {
"type": "object",
"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}$"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"state": {
"type": "string",
"enum": [
"prepared",
"checkout_pending",
"paid",
"cancel_requested",
"cancelled"
]
},
"payment_state": {
"type": "string",
"enum": [
"unpaid",
"pending",
"paid",
"failed",
"expired",
"refunding",
"refunded"
]
},
"refund_state": {
"type": "string",
"enum": [
"none",
"pending",
"partial",
"succeeded",
"failed",
"unknown"
]
},
"amount_cents": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"currency": {
"type": "string",
"const": "usd"
},
"card_count": {
"type": "integer",
"minimum": 1,
"maximum": 500
},
"tax_ready_count": {
"type": "integer",
"minimum": 0,
"maximum": 500
},
"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)))$"
},
"checkout_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"cards": {
"minItems": 1,
"maxItems": 500,
"type": "array",
"items": {
"type": "object",
"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}$"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"state": {
"type": "string",
"enum": [
"prepared",
"checkout_pending",
"paid",
"cancel_requested",
"cancelled"
]
},
"payment_state": {
"type": "string",
"enum": [
"unpaid",
"pending",
"paid",
"failed",
"expired",
"refunding",
"refunded"
]
},
"refund_state": {
"type": "string",
"enum": [
"none",
"pending",
"processing",
"succeeded",
"failed",
"unknown"
]
},
"refund_review_reason": {
"type": [
"string",
"null"
]
},
"tax_review_reason": {
"type": [
"string",
"null"
]
},
"input": {
"type": "object",
"properties": {
"design_key": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"design_version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 2147483646
},
"message": {
"type": "string",
"maxLength": 4000,
"description": "Personal message, at most 2000 Unicode characters. Printed artwork wording is separate."
},
"format": {
"description": "Postcard, flat card in an envelope, or folded card in an envelope. Omit to select flat_card_in_envelope.",
"type": "string",
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
]
},
"message_font": {
"type": "string",
"enum": [
"serif",
"sans_serif",
"old_school",
"handwriting"
]
},
"include_paddock_gift": {
"type": "boolean"
},
"recipient": {
"type": "object",
"properties": {
"display_name": {
"type": "string",
"maxLength": 240
},
"greeting_name": {
"type": "string",
"maxLength": 240
},
"birthday_month": {
"type": "integer",
"minimum": 0,
"maximum": 12
},
"birthday_day": {
"type": "integer",
"minimum": 0,
"maximum": 31
},
"birthday_year": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 9999
},
{
"type": "null"
}
]
},
"anniversary_month": {
"type": "integer",
"minimum": 0,
"maximum": 12
},
"anniversary_day": {
"type": "integer",
"minimum": 0,
"maximum": 31
},
"mailing_address": {
"type": "object",
"properties": {
"line1": {
"type": "string",
"maxLength": 320
},
"line2": {
"type": "string",
"maxLength": 320
},
"locality": {
"type": "string",
"maxLength": 320
},
"region": {
"type": "string",
"maxLength": 160
},
"postal_code": {
"type": "string",
"maxLength": 48
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$"
}
},
"required": [
"line1",
"line2",
"locality",
"region",
"postal_code",
"country_code"
],
"additionalProperties": false
},
"address_confirmed": {
"type": "boolean",
"const": true
},
"origin": {
"type": "string",
"const": "manual"
}
},
"required": [
"display_name",
"birthday_month",
"birthday_day",
"mailing_address",
"address_confirmed",
"origin"
],
"additionalProperties": false
},
"return_address": {
"type": "object",
"properties": {
"display_name": {
"type": "string",
"maxLength": 240
},
"mailing_address": {
"type": "object",
"properties": {
"line1": {
"type": "string",
"maxLength": 320
},
"line2": {
"type": "string",
"maxLength": 320
},
"locality": {
"type": "string",
"maxLength": 320
},
"region": {
"type": "string",
"maxLength": 160
},
"postal_code": {
"type": "string",
"maxLength": 48
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$"
}
},
"required": [
"line1",
"line2",
"locality",
"region",
"postal_code",
"country_code"
],
"additionalProperties": false
},
"source_kind": {
"type": "string",
"const": "manual"
}
},
"required": [
"display_name",
"mailing_address",
"source_kind"
],
"additionalProperties": false
},
"occasion": {
"description": "Optional occasion and timing context, independent of the selected artwork. Omit for an ordinary just-because card.",
"type": "object",
"properties": {
"kind": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"calendar": {
"type": "string",
"const": "us-western-v1"
},
"month": {
"type": "integer",
"minimum": 1,
"maximum": 12
},
"day": {
"type": "integer",
"minimum": 1,
"maximum": 31
},
"send_on": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
}
},
"required": [
"kind",
"calendar"
],
"additionalProperties": false
}
},
"required": [
"design_key",
"design_version",
"message",
"recipient"
],
"additionalProperties": false
},
"schedule": {
"type": "object",
"properties": {
"one_off": {
"type": "boolean",
"const": true
},
"time_zone": {
"type": "string"
},
"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])))$"
},
"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])))$"
},
"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])))$"
},
"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])))$"
},
"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])))$"
},
"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)))$"
},
"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)))$"
},
"estimate_basis": {
"type": "string"
},
"late": {
"type": "boolean"
},
"leap_day_observed": {
"type": "boolean"
},
"next_year": {
"type": "boolean"
}
},
"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"
],
"additionalProperties": false
},
"amount_cents": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"currency": {
"type": "string",
"const": "usd"
},
"offer_version": {
"type": "string"
},
"terms_version": {
"type": "string"
},
"title": {
"type": "string"
},
"artist_name": {
"type": [
"string",
"null"
]
},
"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)))$"
},
"fulfillment_status": {
"anyOf": [
{
"type": "string",
"enum": [
"scheduled",
"preparing",
"ready",
"mailed",
"cancel_requested",
"cancelled"
]
},
{
"type": "null"
}
]
},
"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"
}
]
},
"cancellable": {
"type": "boolean"
}
},
"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",
"fulfillment_status",
"mailed_at",
"cancellable"
],
"additionalProperties": false
}
},
"customer_content": {
"type": "object",
"properties": {
"rights_required": {
"type": "boolean"
},
"rights_accepted": {
"type": "boolean"
},
"terms_version": {
"type": "string",
"const": "customer-print-v1"
}
},
"required": [
"rights_required",
"rights_accepted",
"terms_version"
],
"additionalProperties": false
}
},
"required": [
"id",
"revision",
"state",
"payment_state",
"refund_state",
"amount_cents",
"currency",
"card_count",
"tax_ready_count",
"quote_expires_at",
"checkout_url",
"cards"
],
"additionalProperties": false
},
"order_access_token": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$"
},
"review_url": {
"type": "string",
"format": "uri"
},
"reused": {
"type": "boolean"
},
"payment_required": {
"type": "boolean"
}
},
"required": [
"order",
"order_access_token",
"review_url"
],
"additionalProperties": false
}
},
"required": [
"ok",
"data"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}🟢read_order(order_id, order_access_token)
Read a private purchase and its order.cards using the parent order_id and order_access_token. Payment, per-card production and mailing are distinct states.
Esquema de entrada
{
"type": "object",
"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}$"
},
"order_access_token": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$",
"description": "Private purchase capability. Keep it secret; never put it in a public URL or log."
}
},
"required": [
"order_id",
"order_access_token"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}Esquema de salida
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"properties": {
"order": {
"type": "object",
"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}$"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"state": {
"type": "string",
"enum": [
"prepared",
"checkout_pending",
"paid",
"cancel_requested",
"cancelled"
]
},
"payment_state": {
"type": "string",
"enum": [
"unpaid",
"pending",
"paid",
"failed",
"expired",
"refunding",
"refunded"
]
},
"refund_state": {
"type": "string",
"enum": [
"none",
"pending",
"partial",
"succeeded",
"failed",
"unknown"
]
},
"amount_cents": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"currency": {
"type": "string",
"const": "usd"
},
"card_count": {
"type": "integer",
"minimum": 1,
"maximum": 500
},
"tax_ready_count": {
"type": "integer",
"minimum": 0,
"maximum": 500
},
"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)))$"
},
"checkout_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"cards": {
"minItems": 1,
"maxItems": 500,
"type": "array",
"items": {
"type": "object",
"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}$"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"state": {
"type": "string",
"enum": [
"prepared",
"checkout_pending",
"paid",
"cancel_requested",
"cancelled"
]
},
"payment_state": {
"type": "string",
"enum": [
"unpaid",
"pending",
"paid",
"failed",
"expired",
"refunding",
"refunded"
]
},
"refund_state": {
"type": "string",
"enum": [
"none",
"pending",
"processing",
"succeeded",
"failed",
"unknown"
]
},
"refund_review_reason": {
"type": [
"string",
"null"
]
},
"tax_review_reason": {
"type": [
"string",
"null"
]
},
"input": {
"type": "object",
"properties": {
"design_key": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"design_version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 2147483646
},
"message": {
"type": "string",
"maxLength": 4000,
"description": "Personal message, at most 2000 Unicode characters. Printed artwork wording is separate."
},
"format": {
"description": "Postcard, flat card in an envelope, or folded card in an envelope. Omit to select flat_card_in_envelope.",
"type": "string",
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
]
},
"message_font": {
"type": "string",
"enum": [
"serif",
"sans_serif",
"old_school",
"handwriting"
]
},
"include_paddock_gift": {
"type": "boolean"
},
"recipient": {
"type": "object",
"properties": {
"display_name": {
"type": "string",
"maxLength": 240
},
"greeting_name": {
"type": "string",
"maxLength": 240
},
"birthday_month": {
"type": "integer",
"minimum": 0,
"maximum": 12
},
"birthday_day": {
"type": "integer",
"minimum": 0,
"maximum": 31
},
"birthday_year": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 9999
},
{
"type": "null"
}
]
},
"anniversary_month": {
"type": "integer",
"minimum": 0,
"maximum": 12
},
"anniversary_day": {
"type": "integer",
"minimum": 0,
"maximum": 31
},
"mailing_address": {
"type": "object",
"properties": {
"line1": {
"type": "string",
"maxLength": 320
},
"line2": {
"type": "string",
"maxLength": 320
},
"locality": {
"type": "string",
"maxLength": 320
},
"region": {
"type": "string",
"maxLength": 160
},
"postal_code": {
"type": "string",
"maxLength": 48
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$"
}
},
"required": [
"line1",
"line2",
"locality",
"region",
"postal_code",
"country_code"
],
"additionalProperties": false
},
"address_confirmed": {
"type": "boolean",
"const": true
},
"origin": {
"type": "string",
"const": "manual"
}
},
"required": [
"display_name",
"birthday_month",
"birthday_day",
"mailing_address",
"address_confirmed",
"origin"
],
"additionalProperties": false
},
"return_address": {
"type": "object",
"properties": {
"display_name": {
"type": "string",
"maxLength": 240
},
"mailing_address": {
"type": "object",
"properties": {
"line1": {
"type": "string",
"maxLength": 320
},
"line2": {
"type": "string",
"maxLength": 320
},
"locality": {
"type": "string",
"maxLength": 320
},
"region": {
"type": "string",
"maxLength": 160
},
"postal_code": {
"type": "string",
"maxLength": 48
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$"
}
},
"required": [
"line1",
"line2",
"locality",
"region",
"postal_code",
"country_code"
],
"additionalProperties": false
},
"source_kind": {
"type": "string",
"const": "manual"
}
},
"required": [
"display_name",
"mailing_address",
"source_kind"
],
"additionalProperties": false
},
"occasion": {
"description": "Optional occasion and timing context, independent of the selected artwork. Omit for an ordinary just-because card.",
"type": "object",
"properties": {
"kind": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"calendar": {
"type": "string",
"const": "us-western-v1"
},
"month": {
"type": "integer",
"minimum": 1,
"maximum": 12
},
"day": {
"type": "integer",
"minimum": 1,
"maximum": 31
},
"send_on": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
}
},
"required": [
"kind",
"calendar"
],
"additionalProperties": false
}
},
"required": [
"design_key",
"design_version",
"message",
"recipient"
],
"additionalProperties": false
},
"schedule": {
"type": "object",
"properties": {
"one_off": {
"type": "boolean",
"const": true
},
"time_zone": {
"type": "string"
},
"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])))$"
},
"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])))$"
},
"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])))$"
},
"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])))$"
},
"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])))$"
},
"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)))$"
},
"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)))$"
},
"estimate_basis": {
"type": "string"
},
"late": {
"type": "boolean"
},
"leap_day_observed": {
"type": "boolean"
},
"next_year": {
"type": "boolean"
}
},
"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"
],
"additionalProperties": false
},
"amount_cents": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"currency": {
"type": "string",
"const": "usd"
},
"offer_version": {
"type": "string"
},
"terms_version": {
"type": "string"
},
"title": {
"type": "string"
},
"artist_name": {
"type": [
"string",
"null"
]
},
"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)))$"
},
"fulfillment_status": {
"anyOf": [
{
"type": "string",
"enum": [
"scheduled",
"preparing",
"ready",
"mailed",
"cancel_requested",
"cancelled"
]
},
{
"type": "null"
}
]
},
"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"
}
]
},
"cancellable": {
"type": "boolean"
}
},
"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",
"fulfillment_status",
"mailed_at",
"cancellable"
],
"additionalProperties": false
}
},
"customer_content": {
"type": "object",
"properties": {
"rights_required": {
"type": "boolean"
},
"rights_accepted": {
"type": "boolean"
},
"terms_version": {
"type": "string",
"const": "customer-print-v1"
}
},
"required": [
"rights_required",
"rights_accepted",
"terms_version"
],
"additionalProperties": false
}
},
"required": [
"id",
"revision",
"state",
"payment_state",
"refund_state",
"amount_cents",
"currency",
"card_count",
"tax_ready_count",
"quote_expires_at",
"checkout_url",
"cards"
],
"additionalProperties": false
}
},
"required": [
"order"
],
"additionalProperties": false
}
},
"required": [
"ok",
"data"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}🔴cancel_order(order_id, order_access_token, expected_revision, card_ids)
Cancel an eligible purchase at its current revision. Before payment, only whole-purchase cancellation is supported: omit card_ids. After payment, supply returned card_ids to cancel only eligible items, or omit them for the whole eligible purchase. The service verifies ownership and each fulfillment cutoff, and returns actual refund state. Requires the parent order_id and private order_access_token.
Esquema de entrada
{
"type": "object",
"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}$"
},
"order_access_token": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{43}$",
"description": "Private purchase capability. Keep it secret; never put it in a public URL or log."
},
"expected_revision": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 2147483646
},
"card_ids": {
"description": "Omit to cancel the whole eligible purchase. For a paid purchase, list the returned card IDs to cancel only those eligible items. The service verifies every ID belongs to this order.",
"minItems": 1,
"maxItems": 500,
"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}$"
}
}
},
"required": [
"order_id",
"order_access_token",
"expected_revision"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}Esquema de salida
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"properties": {
"order": {
"type": "object",
"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}$"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"state": {
"type": "string",
"enum": [
"prepared",
"checkout_pending",
"paid",
"cancel_requested",
"cancelled"
]
},
"payment_state": {
"type": "string",
"enum": [
"unpaid",
"pending",
"paid",
"failed",
"expired",
"refunding",
"refunded"
]
},
"refund_state": {
"type": "string",
"enum": [
"none",
"pending",
"partial",
"succeeded",
"failed",
"unknown"
]
},
"amount_cents": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"currency": {
"type": "string",
"const": "usd"
},
"card_count": {
"type": "integer",
"minimum": 1,
"maximum": 500
},
"tax_ready_count": {
"type": "integer",
"minimum": 0,
"maximum": 500
},
"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)))$"
},
"checkout_url": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
},
"cards": {
"minItems": 1,
"maxItems": 500,
"type": "array",
"items": {
"type": "object",
"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}$"
},
"revision": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"state": {
"type": "string",
"enum": [
"prepared",
"checkout_pending",
"paid",
"cancel_requested",
"cancelled"
]
},
"payment_state": {
"type": "string",
"enum": [
"unpaid",
"pending",
"paid",
"failed",
"expired",
"refunding",
"refunded"
]
},
"refund_state": {
"type": "string",
"enum": [
"none",
"pending",
"processing",
"succeeded",
"failed",
"unknown"
]
},
"refund_review_reason": {
"type": [
"string",
"null"
]
},
"tax_review_reason": {
"type": [
"string",
"null"
]
},
"input": {
"type": "object",
"properties": {
"design_key": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"design_version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 2147483646
},
"message": {
"type": "string",
"maxLength": 4000,
"description": "Personal message, at most 2000 Unicode characters. Printed artwork wording is separate."
},
"format": {
"description": "Postcard, flat card in an envelope, or folded card in an envelope. Omit to select flat_card_in_envelope.",
"type": "string",
"enum": [
"postcard",
"flat_card_in_envelope",
"folded_card_in_envelope"
]
},
"message_font": {
"type": "string",
"enum": [
"serif",
"sans_serif",
"old_school",
"handwriting"
]
},
"include_paddock_gift": {
"type": "boolean"
},
"recipient": {
"type": "object",
"properties": {
"display_name": {
"type": "string",
"maxLength": 240
},
"greeting_name": {
"type": "string",
"maxLength": 240
},
"birthday_month": {
"type": "integer",
"minimum": 0,
"maximum": 12
},
"birthday_day": {
"type": "integer",
"minimum": 0,
"maximum": 31
},
"birthday_year": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 9999
},
{
"type": "null"
}
]
},
"anniversary_month": {
"type": "integer",
"minimum": 0,
"maximum": 12
},
"anniversary_day": {
"type": "integer",
"minimum": 0,
"maximum": 31
},
"mailing_address": {
"type": "object",
"properties": {
"line1": {
"type": "string",
"maxLength": 320
},
"line2": {
"type": "string",
"maxLength": 320
},
"locality": {
"type": "string",
"maxLength": 320
},
"region": {
"type": "string",
"maxLength": 160
},
"postal_code": {
"type": "string",
"maxLength": 48
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$"
}
},
"required": [
"line1",
"line2",
"locality",
"region",
"postal_code",
"country_code"
],
"additionalProperties": false
},
"address_confirmed": {
"type": "boolean",
"const": true
},
"origin": {
"type": "string",
"const": "manual"
}
},
"required": [
"display_name",
"birthday_month",
"birthday_day",
"mailing_address",
"address_confirmed",
"origin"
],
"additionalProperties": false
},
"return_address": {
"type": "object",
"properties": {
"display_name": {
"type": "string",
"maxLength": 240
},
"mailing_address": {
"type": "object",
"properties": {
"line1": {
"type": "string",
"maxLength": 320
},
"line2": {
"type": "string",
"maxLength": 320
},
"locality": {
"type": "string",
"maxLength": 320
},
"region": {
"type": "string",
"maxLength": 160
},
"postal_code": {
"type": "string",
"maxLength": 48
},
"country_code": {
"type": "string",
"pattern": "^[A-Z]{2}$"
}
},
"required": [
"line1",
"line2",
"locality",
"region",
"postal_code",
"country_code"
],
"additionalProperties": false
},
"source_kind": {
"type": "string",
"const": "manual"
}
},
"required": [
"display_name",
"mailing_address",
"source_kind"
],
"additionalProperties": false
},
"occasion": {
"description": "Optional occasion and timing context, independent of the selected artwork. Omit for an ordinary just-because card.",
"type": "object",
"properties": {
"kind": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"calendar": {
"type": "string",
"const": "us-western-v1"
},
"month": {
"type": "integer",
"minimum": 1,
"maximum": 12
},
"day": {
"type": "integer",
"minimum": 1,
"maximum": 31
},
"send_on": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
}
},
"required": [
"kind",
"calendar"
],
"additionalProperties": false
}
},
"required": [
"design_key",
"design_version",
"message",
"recipient"
],
"additionalProperties": false
},
"schedule": {
"type": "object",
"properties": {
"one_off": {
"type": "boolean",
"const": true
},
"time_zone": {
"type": "string"
},
"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])))$"
},
"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])))$"
},
"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])))$"
},
"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])))$"
},
"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])))$"
},
"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)))$"
},
"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)))$"
},
"estimate_basis": {
"type": "string"
},
"late": {
"type": "boolean"
},
"leap_day_observed": {
"type": "boolean"
},
"next_year": {
"type": "boolean"
}
},
"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"
],
"additionalProperties": false
},
"amount_cents": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"currency": {
"type": "string",
"const": "usd"
},
"offer_version": {
"type": "string"
},
"terms_version": {
"type": "string"
},
"title": {
"type": "string"
},
"artist_name": {
"type": [
"string",
"null"
]
},
"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)))$"
},
"fulfillment_status": {
"anyOf": [
{
"type": "string",
"enum": [
"scheduled",
"preparing",
"ready",
"mailed",
"cancel_requested",
"cancelled"
]
},
{
"type": "null"
}
]
},
"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"
}
]
},
"cancellable": {
"type": "boolean"
}
},
"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",
"fulfillment_status",
"mailed_at",
"cancellable"
],
"additionalProperties": false
}
},
"customer_content": {
"type": "object",
"properties": {
"rights_required": {
"type": "boolean"
},
"rights_accepted": {
"type": "boolean"
},
"terms_version": {
"type": "string",
"const": "customer-print-v1"
}
},
"required": [
"rights_required",
"rights_accepted",
"terms_version"
],
"additionalProperties": false
}
},
"required": [
"id",
"revision",
"state",
"payment_state",
"refund_state",
"amount_cents",
"currency",
"card_count",
"tax_ready_count",
"quote_expires_at",
"checkout_url",
"cards"
],
"additionalProperties": false
}
},
"required": [
"order"
],
"additionalProperties": false
}
},
"required": [
"ok",
"data"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}⚪report_feedback(kind, operation, category, severity, code, ...)
Optionally report a technical problem, suggestion category or neutral successful outcome using fixed choices. Never required to buy a card. Do not include personal content, credentials, links, conversations or hidden reasoning. Reports are unverified feedback, not proof of payment or mailing.
Esquema de entrada
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"problem",
"suggestion",
"success"
]
},
"operation": {
"type": "string",
"enum": [
"search_cards",
"prepare_order",
"read_order",
"cancel_order",
"checkout",
"connection",
"documentation"
]
},
"category": {
"type": "string",
"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"
]
},
"severity": {
"type": "string",
"enum": [
"none",
"minor",
"major",
"blocked"
]
},
"code": {
"default": "none",
"description": "Reported public error code only; no provider error text.",
"type": "string",
"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"
]
},
"field": {
"default": "none",
"description": "Reported field name only; never its value.",
"type": "string",
"enum": [
"none",
"design_key",
"design_version",
"format",
"message",
"recipient.mailing_address",
"return_address",
"occasion",
"price",
"printed_text",
"availability",
"preview"
]
}
},
"required": [
"kind",
"operation",
"category",
"severity"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}Esquema de salida
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"const": true
},
"data": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"recorded",
"duplicate"
]
},
"verification": {
"type": "string",
"const": "unverified_report"
}
},
"required": [
"status",
"verification"
],
"additionalProperties": false
}
},
"required": [
"ok",
"data"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}Comunidad
Evidencia
Observaciones recientes
verificadoversión no registrada5 herramientas