Raw schema
{
"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}$",
"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."
},
"cards": {
"minItems": 1,
"maxItems": 500,
"type": "array",
"items": {
"type": "object",
"properties": {
"design_key": {
"type": "string",
"minLength": 1,
"maxLength": 160,
"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."
},
"design_version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 2147483646,
"description": "Matching card.design.version from the same search result, or design_version returned for the private composition. Never infer a version."
},
"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."
},
"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": {
"description": "Font for the personal message: serif, sans_serif, old_school or handwriting. Omission uses serif. Artwork lettering is unchanged.",
"type": "string",
"enum": [
"serif",
"sans_serif",
"old_school",
"handwriting"
]
},
"include_paddock_gift": {
"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.",
"type": "boolean"
},
"recipient": {
"type": "object",
"properties": {
"display_name": {
"type": "string",
"maxLength": 240,
"description": "Name on the envelope or address panel."
},
"greeting_name": {
"description": "Name printed in the automatic greeting, such as Ida for \"Dear Ida,\". Defaults to display_name.",
"type": "string",
"maxLength": 240
},
"birthday_month": {
"default": 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.",
"type": "integer",
"minimum": 0,
"maximum": 12
},
"birthday_day": {
"default": 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.",
"type": "integer",
"minimum": 0,
"maximum": 31
},
"birthday_year": {
"description": "Known birth year, optional. Requires a valid full birth date that is not in the future. Omit or use null when unknown.",
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 9999
},
{
"type": "null"
}
]
},
"anniversary_month": {
"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.",
"type": "integer",
"minimum": 0,
"maximum": 12
},
"anniversary_day": {
"description": "Optional anniversary day valid for anniversary_month; supply both fields together or omit both. Paired zeros mean unknown.",
"type": "integer",
"minimum": 0,
"maximum": 31
},
"mailing_address": {
"type": "object",
"properties": {
"line1": {
"type": "string",
"maxLength": 320,
"description": "Street address or postal delivery line supplied by the buyer."
},
"line2": {
"default": "",
"description": "Optional second line, such as an apartment or suite. Omitted means empty.",
"type": "string",
"maxLength": 320
},
"locality": {
"type": "string",
"maxLength": 320,
"description": "City, town or postal locality."
},
"region": {
"type": "string",
"maxLength": 160,
"description": "State, province or region; use an empty string where the destination does not require one."
},
"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."
}
},
"required": [
"line1",
"locality",
"region",
"postal_code",
"country_code"
],
"additionalProperties": false,
"description": "Recipient mailing address supplied and confirmed by the buyer."
},
"address_confirmed": {
"type": "boolean",
"const": true,
"description": "Must be true: the buyer has confirmed the supplied mailing address."
},
"origin": {
"type": "string",
"const": "manual",
"description": "Must be manual: recipient details come from the buyer, without a member recipient ID or Contacts import."
}
},
"required": [
"display_name",
"mailing_address",
"address_confirmed",
"origin"
],
"additionalProperties": false,
"description": "Buyer-supplied recipient details for this card. This does not create or select a saved member recipient."
},
"return_address": {
"type": "object",
"properties": {
"display_name": {
"type": "string",
"maxLength": 240,
"description": "Sender name printed with the return address."
},
"mailing_address": {
"type": "object",
"properties": {
"line1": {
"type": "string",
"maxLength": 320,
"description": "Street address or postal delivery line supplied by the buyer."
},
"line2": {
"default": "",
"description": "Optional second line, such as an apartment or suite. Omitted means empty.",
"type": "string",
"maxLength": 320
},
"locality": {
"type": "string",
"maxLength": 320,
"description": "City, town or postal locality."
},
"region": {
"type": "string",
"maxLength": 160,
"description": "State, province or region; use an empty string where the destination does not require one."
},
"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."
}
},
"required": [
"line1",
"locality",
"region",
"postal_code",
"country_code"
],
"additionalProperties": false,
"description": "Sender return mailing address supplied by the buyer."
},
"source_kind": {
"type": "string",
"const": "manual",
"description": "Must be manual: the buyer supplies this address; billing and saved Home addresses are not inferred."
}
},
"required": [
"display_name",
"mailing_address",
"source_kind"
],
"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."
},
"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,
"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."
},
"calendar": {
"type": "string",
"const": "us-western-v1",
"description": "Must be us-western-v1, the supported occasion calendar."
},
"month": {
"description": "Required with day for a personal annual occasion such as anniversary. Omit for holidays and one-off occasions; birthdays use recipient.birthday_month.",
"type": "integer",
"minimum": 1,
"maximum": 12
},
"day": {
"description": "Day valid for occasion.month, required for personal annual occasions such as anniversary. Birthdays use recipient.birthday_day.",
"type": "integer",
"minimum": 1,
"maximum": 31
},
"send_on": {
"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.",
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
}
},
"required": [
"kind",
"calendar"
],
"additionalProperties": false
}
},
"required": [
"design_key",
"design_version",
"message",
"recipient",
"return_address"
],
"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_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."
},
"expected_revision": {
"type": "integer",
"exclusiveMinimum": 0,
"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."
}
},
"required": [
"request_id",
"cards",
"order_id",
"order_access_token",
"expected_revision"
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}