Premier Letters

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string', 'description': 'The letter text. Supports {{first_name}}, {{last_name}}, {{greeting}} merge fields per-recipient.'}, 'options': {'type': 'object', 'description': 'handwriting_style, paper_type, product_type, mailing_option, authenticity_preset, include_letter, include_envelope, copies — see /openapi.json for the full field list.'}, 'payment': {'type': 'object', 'properties': {'method': {'enum': ['card_on_file', 'checkout_session'], 'type': 'string', 'description': 'Defaults to "checkout_session".'}, 'return_url': {'type': 'string'}}}, 'recipients': {'type': 'array', 'items': {'type': 'object', 'properties': {'zip': {'type': 'string'}, 'city': {'type': 'string'}, 'state': {'type': 'string'}, 'last_name': {'type': 'string'}, 'first_name': {'type': 'string'}, 'address_line1': {'type': 'string'}, 'address_line2': {'type': 'string'}, 'custom_fields': {'type': 'object'}}}, 'description': 'One or more recipients. At least one is required unless options.product_type is a letter/card with no envelope.'}, 'skip_invalid': {'type': 'boolean', 'description': 'When true, invalid recipients are skipped instead of failing the whole order.'}, 'idempotency_key': {'type': 'string', 'description': 'Optional client-supplied key. Not yet enforced server-side; reserved for future use.'}}}

{'type': 'object', 'required': ['order_id'], 'properties': {'order_id': {'type': 'string', 'description': 'The order UUID returned by create_order.'}}}

{'type': 'object', 'properties': {'char_count': {'type': 'number', 'description': 'Length of the letter message in characters. Longer letters cost more (character meter).'}, 'paper_type': {'enum': ['standard', 'premium'], 'type': 'string', 'description': 'Paper quality. Defaults to "standard".'}, 'letter_count': {'type': 'number', 'description': 'Number of recipients / pieces. Defaults to 1.'}, 'product_type': {'enum': ['letter', 'card', 'a7', 'postcard', 'card_5x7', 'postcard_5x7', 'a4', 'a5', 'a6'], 'type': 'string', 'description': 'Product type (letter, card, postcard, etc). Informational only — does not change pricing components beyond envelope inclusion.'}, 'mailing_option': {'enum': ['we_mail', 'you_mail_stamped', 'you_mail_no_stamp'], 'type': 'string', 'description': 'Delivery option. Defaults to "we_mail" (we write, stamp, and mail it for you).'}}}

{'type': 'object', 'properties': {}}

{'type': 'object', 'properties': {'limit': {'type': 'number', 'description': 'Max orders to return (1-100). Defaults to 20.'}, 'status': {'type': 'string', 'description': 'Optional status filter (pending_payment, paid, in_production, mailed, delivered, cancelled, refunded).'}}}

{'type': 'object', 'properties': {'sort': {'enum': ['recent', 'most_used', 'name'], 'type': 'string', 'description': 'Sort order. Defaults to "recent".'}, 'search': {'type': 'string', 'description': 'Filter templates by name or content substring.'}, 'favorites_only': {'type': 'boolean', 'description': 'Only return favorited templates.'}}}

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string', 'description': 'The letter text to render.'}, 'recipient': {'type': 'object', 'properties': {'last_name': {'type': 'string'}, 'first_name': {'type': 'string'}}, 'description': 'Optional recipient info, used only to personalize {{merge fields}} in the message before rendering.'}, 'product_type': {'type': 'string', 'description': 'Product slug: letter, card, postcard, etc. Defaults to "letter".'}, 'handwriting_style': {'type': 'string', 'description': 'Font UUID from list_handwriting_styles. Defaults to the house font.'}}}

{'type': 'object', 'required': ['address_line1', 'city', 'state', 'zip'], 'properties': {'zip': {'type': 'string', 'description': '5-digit or ZIP+4 postal code'}, 'city': {'type': 'string'}, 'state': {'type': 'string', 'description': 'Two-letter US state code'}, 'address_line1': {'type': 'string', 'description': 'Street address'}, 'address_line2': {'type': 'string', 'description': 'Apt/suite/unit (optional)'}}}