Skip to contentPostalForm

Content

Refund Request Packets API reference

Collect customer, business-recipient, transaction, refund, prior-contact, deadline, signature, acknowledgement, and optional evidence inputs needed to generate and mail a refund request packet.

Published Jul 10, 2026

Open guided form

Workflow slug: refund-request-packets. Workflow version: 1. Live schema · Markdown reference.

How it works

Step 1

Fill out form

Complete the guided fields online.

Step 2

Preview PDF

Review the generated PDF before mailing.

Step 3

Mail

We print and mail it via USPS.

How does an agent prepare this form?

PostalForm uses the same workflow definition for this API reference and its guided browser form. Fetch the live schema, collect the active required fields and attachments, and validate the completed request. Review the generated PDF, resolved recipient, mailing service and price with the owner before authorizing payment.

Submission and recipient rules

Setting Current workflow value
Form slug refund-request-packets
Recipient mode user
Certified Mail optional
Base U.S. mail service USPS First-Class Mail (mail_class="standard" in the API); not USPS Marketing Mail
Attachment total limit 12 MB
Validate without payment POST /api/machine/orders/validate or POST /api/machine/mpp/orders/validate
Machine order POST /api/machine/orders (x402) or POST /api/machine/mpp/orders (MPP)

Send a top-level form instead of pdf or letter; those three document sources are mutually exclusive. Workflow forms are letters, not postcards. The machine envelope requires buyer, sender and recipient fields. For predefined or computed recipients, the server binds the final recipient to the workflow rules. Inspect the resolved recipient returned by validation; do not substitute a convenient office address.

The template below is structural, not ready to submit: replace every placeholder, complete the active fields, omit unused optional attachments, and use the field options and visibility rules in the schema. Empty strings and unchecked checkboxes are not user answers. Never infer a signature, legal eligibility, factual declaration or consent from a default value.

JSON request template

{
  "request_id": "<new UUID; preserve on retry>",
  "buyer_name": "<buyer name>",
  "buyer_email": "<buyer email>",
  "sender_name": "<sender name>",
  "sender_address_type": "Manual",
  "sender_address_manual": {
    "line1": "<street address>",
    "city": "<city>",
    "state": "<state or region>",
    "zip": "<postal code>",
    "countryCode": "US"
  },
  "recipient_name": "<confirmed recipient name>",
  "recipient_address_type": "Manual",
  "recipient_address_manual": {
    "line1": "<street address>",
    "city": "<city>",
    "state": "<state or region>",
    "zip": "<postal code>",
    "countryCode": "US"
  },
  "mail_class": "standard",
  "double_sided": true,
  "color": false,
  "certified": false,
  "form": {
    "slug": "refund-request-packets",
    "fields": {
      "letter_date": "",
      "sender_name": "",
      "sender_email": "",
      "sender_phone": "",
      "sender_address": "",
      "recipient_name": "",
      "recipient_address": "",
      "product_or_service": "",
      "transaction_date": "",
      "amount_paid": "",
      "include_transaction_reference": false,
      "transaction_reference": "",
      "refund_reason": "",
      "problem_description": "",
      "prior_resolution_attempt": false,
      "prior_resolution_details": "",
      "refund_amount_requested": "",
      "requested_refund_method": "",
      "requested_response_date": "",
      "include_return_instructions": false,
      "return_instructions": "",
      "signature": "",
      "date_signed": "",
      "facts_acknowledged": false,
      "process_limits_acknowledged": false
    },
    "attachments": [
      {
        "id": "purchase_records",
        "file_name": "<filename>",
        "base64": "<base64 file content>"
      },
      {
        "id": "prior_correspondence",
        "file_name": "<filename>",
        "base64": "<base64 file content>"
      },
      {
        "id": "product_or_service_evidence",
        "file_name": "<filename>",
        "base64": "<base64 file content>"
      },
      {
        "id": "other_supporting_documents",
        "file_name": "<filename>",
        "base64": "<base64 file content>"
      }
    ]
  }
}

Field reference

Field ID Label Type Required when active Choices
letter_date Letter date date Yes See schema
sender_name Customer full name text Yes See schema
sender_email Reply email (optional) text No See schema
sender_phone Reply phone (optional) text No See schema
sender_address Customer return address address Yes See schema
recipient_name Customer service or recipient name text Yes See schema
recipient_address Business mailing address address Yes See schema
product_or_service Product or service text Yes See schema
transaction_date Transaction date date Yes See schema
amount_paid Amount paid text Yes See schema
include_transaction_reference Include an order, account, or invoice reference checkbox No See schema
transaction_reference Transaction reference text Yes See schema
refund_reason Reason for requesting a refund select Yes Product was defective or damaged, Product or service was not as described, Service was not completed or did not resolve the problem, Order was canceled or not delivered, Billing or price was incorrect, Other
problem_description Problem description textarea Yes See schema
prior_resolution_attempt A prior resolution attempt was made checkbox No See schema
prior_resolution_details Prior resolution details textarea Yes See schema
refund_amount_requested Refund amount requested text Yes See schema
requested_refund_method Requested refund method select Yes Original payment method, Check mailed to my return address, Account credit, Other method confirmed in writing
requested_response_date Requested response date date Yes See schema
include_return_instructions Ask for product-return instructions checkbox No See schema
return_instructions Return instruction request textarea Yes See schema
signature Customer signature signature Yes See schema
date_signed Date signed date Yes See schema
facts_acknowledged I reviewed the letter and confirm that its transaction details, dates, and factual statements are accurate. checkbox Yes See schema
process_limits_acknowledged I understand this request does not guarantee a refund or replace a seller, warranty, card-dispute, or legal deadline. checkbox Yes See schema

Compound fields use nested objects keyed by subfield ID. Evaluate group and field visibility before deciding which fields are active. Conditional requirements, validation rules, recipient rules, attachment formats and compliance policies are preserved in the complete schema below.

Complete workflow schema

{
  "schema_version": 1,
  "workflow_version": 1,
  "slug": "refund-request-packets",
  "name": "Refund Request Packets",
  "description": "Create a signed refund request letter, attach purchase records, preview the PDF packet, and mail it to a business.",
  "agent_summary": "Collect customer, business-recipient, transaction, refund, prior-contact, deadline, signature, acknowledgement, and optional evidence inputs needed to generate and mail a refund request packet.",
  "form_summary": "Use this workflow to organize a refund request with transaction facts, the problem, prior resolution attempts, requested amount and method, a response date, and optional supporting records.",
  "data_collected": [
    "Customer name, contact details, return address, and signature",
    "Business or customer-service recipient and mailing address",
    "Product or service, transaction date, amount paid, and optional reference number",
    "Problem description, refund reason, requested refund amount and method, and response deadline",
    "Optional receipts, invoices, warranties, photos, repair records, and prior correspondence"
  ],
  "topics": [
    "consumer",
    "refunds",
    "customer complaints",
    "purchases",
    "billing disputes"
  ],
  "category": "guided_letter",
  "publish_state": "published",
  "aliases": [
    "refund-request-letter",
    "customer-refund-request-letter",
    "consumer-complaint-refund-letter"
  ],
  "llms": true,
  "indexable": true,
  "certified_mail": "optional",
  "recipient": {
    "mode": "user"
  },
  "checkout_flow": "forms_order",
  "published_at": "2026-07-10",
  "updated_at": "2026-07-10",
  "groups": [
    {
      "id": "sender",
      "label": "Customer and return address",
      "description": "Provide the customer details that should appear on the request and envelope.",
      "depends_on": []
    },
    {
      "id": "recipient",
      "label": "Business recipient",
      "description": "Use the address the business designates for returns, billing questions, or written complaints when one is available.",
      "depends_on": []
    },
    {
      "id": "transaction",
      "label": "Purchase or service details",
      "description": "Identify the transaction, amount, and optional reference information.",
      "depends_on": []
    },
    {
      "id": "request",
      "label": "Problem and requested refund",
      "description": "Explain what happened, what you already tried, and the specific resolution you want.",
      "depends_on": []
    },
    {
      "id": "signature",
      "label": "Signature and review",
      "description": "Sign the letter and confirm the facts, recipient, and process limitations.",
      "depends_on": []
    }
  ],
  "fields": [
    {
      "id": "letter_date",
      "label": "Letter date",
      "type": "date",
      "required": true,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "sender",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "sender_name",
      "label": "Customer full name",
      "type": "text",
      "required": true,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "sender",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "sender_email",
      "label": "Reply email (optional)",
      "type": "text",
      "required": false,
      "meta_class": "email",
      "ui_width": "half",
      "group_id": "sender",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "sender_phone",
      "label": "Reply phone (optional)",
      "type": "text",
      "required": false,
      "meta_class": "phone",
      "ui_width": "half",
      "group_id": "sender",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "sender_address",
      "label": "Customer return address",
      "type": "address",
      "required": true,
      "meta_class": null,
      "ui_width": null,
      "group_id": "sender",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "recipient_name",
      "label": "Customer service or recipient name",
      "type": "text",
      "required": true,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "recipient",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "recipient_address",
      "label": "Business mailing address",
      "type": "address",
      "required": true,
      "meta_class": null,
      "ui_width": null,
      "group_id": "recipient",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "product_or_service",
      "label": "Product or service",
      "type": "text",
      "required": true,
      "meta_class": null,
      "ui_width": null,
      "group_id": "transaction",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "transaction_date",
      "label": "Transaction date",
      "type": "date",
      "required": true,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "transaction",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "amount_paid",
      "label": "Amount paid",
      "type": "text",
      "required": true,
      "meta_class": "currency",
      "ui_width": "half",
      "group_id": "transaction",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "include_transaction_reference",
      "label": "Include an order, account, or invoice reference",
      "type": "checkbox",
      "required": false,
      "meta_class": null,
      "ui_width": null,
      "group_id": "transaction",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "transaction_reference",
      "label": "Transaction reference",
      "type": "text",
      "required": true,
      "meta_class": null,
      "ui_width": null,
      "group_id": "transaction",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "include_transaction_reference",
        "operator": "truthy"
      },
      "depends_on": [
        "include_transaction_reference"
      ],
      "compound": null
    },
    {
      "id": "refund_reason",
      "label": "Reason for requesting a refund",
      "type": "select",
      "required": true,
      "meta_class": null,
      "ui_width": null,
      "group_id": "request",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "options": [
        "Product was defective or damaged",
        "Product or service was not as described",
        "Service was not completed or did not resolve the problem",
        "Order was canceled or not delivered",
        "Billing or price was incorrect",
        "Other"
      ],
      "compound": null
    },
    {
      "id": "problem_description",
      "label": "Problem description",
      "type": "textarea",
      "required": true,
      "meta_class": null,
      "ui_width": null,
      "group_id": "request",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "prior_resolution_attempt",
      "label": "A prior resolution attempt was made",
      "type": "checkbox",
      "required": false,
      "meta_class": null,
      "ui_width": null,
      "group_id": "request",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "prior_resolution_details",
      "label": "Prior resolution details",
      "type": "textarea",
      "required": true,
      "meta_class": null,
      "ui_width": null,
      "group_id": "request",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "prior_resolution_attempt",
        "operator": "truthy"
      },
      "depends_on": [
        "prior_resolution_attempt"
      ],
      "compound": null
    },
    {
      "id": "refund_amount_requested",
      "label": "Refund amount requested",
      "type": "text",
      "required": true,
      "meta_class": "currency",
      "ui_width": "half",
      "group_id": "request",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "requested_refund_method",
      "label": "Requested refund method",
      "type": "select",
      "required": true,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "request",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "options": [
        "Original payment method",
        "Check mailed to my return address",
        "Account credit",
        "Other method confirmed in writing"
      ],
      "compound": null
    },
    {
      "id": "requested_response_date",
      "label": "Requested response date",
      "type": "date",
      "required": true,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "request",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "include_return_instructions",
      "label": "Ask for product-return instructions",
      "type": "checkbox",
      "required": false,
      "meta_class": null,
      "ui_width": null,
      "group_id": "request",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "return_instructions",
      "label": "Return instruction request",
      "type": "textarea",
      "required": true,
      "meta_class": null,
      "ui_width": null,
      "group_id": "request",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "include_return_instructions",
        "operator": "truthy"
      },
      "depends_on": [
        "include_return_instructions"
      ],
      "compound": null
    },
    {
      "id": "signature",
      "label": "Customer signature",
      "type": "signature",
      "required": true,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "signature",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "date_signed",
      "label": "Date signed",
      "type": "date",
      "required": true,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "signature",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "facts_acknowledged",
      "label": "I reviewed the letter and confirm that its transaction details, dates, and factual statements are accurate.",
      "type": "checkbox",
      "required": true,
      "meta_class": null,
      "ui_width": null,
      "group_id": "signature",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "process_limits_acknowledged",
      "label": "I understand this request does not guarantee a refund or replace a seller, warranty, card-dispute, or legal deadline.",
      "type": "checkbox",
      "required": true,
      "meta_class": null,
      "ui_width": null,
      "group_id": "signature",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    }
  ],
  "attachments": [
    {
      "id": "purchase_records",
      "label": "Receipt, invoice, or order record",
      "required": false,
      "instructions": "Attach copies of receipts, invoices, order confirmations, statements, or payment records.",
      "allowed_types": [
        "pdf",
        "jpg",
        "jpeg",
        "png"
      ],
      "max_files": 10,
      "max_size_mb": 12
    },
    {
      "id": "prior_correspondence",
      "label": "Prior customer-service correspondence",
      "required": false,
      "instructions": "Attach copies of relevant emails, chat records, letters, cancellation confirmations, or promised resolutions.",
      "allowed_types": [
        "pdf",
        "jpg",
        "jpeg",
        "png"
      ],
      "max_files": 12,
      "max_size_mb": 12
    },
    {
      "id": "product_or_service_evidence",
      "label": "Product or service evidence",
      "required": false,
      "instructions": "Attach relevant photos, warranty pages, repair records, delivery records, or service reports.",
      "allowed_types": [
        "pdf",
        "jpg",
        "jpeg",
        "png"
      ],
      "max_files": 12,
      "max_size_mb": 12
    },
    {
      "id": "other_supporting_documents",
      "label": "Other supporting documents",
      "required": false,
      "instructions": "Attach other relevant copies and keep your originals.",
      "allowed_types": [
        "pdf",
        "jpg",
        "jpeg",
        "png"
      ],
      "max_files": 10,
      "max_size_mb": 12
    }
  ],
  "attachments_max_total_size_mb": 12,
  "machine_submission": {
    "payload_property": "form",
    "create_paths": {
      "x402": "/api/machine/orders",
      "mpp": "/api/machine/mpp/orders"
    }
  }
}

Preview, payment and retries

Validation does not mail the document. For a human checkout, use MCP postalform.create_form_order_draft and present the returned preview, total and checkout URL. Machine API clients must handle the returned MPP or x402 challenge only within owner-approved spending authority. Preserve request_id and the exact payload for retries; changing the content requires a new request ID. After an uncertain payment, retrieve order status before creating another order. Provider handoff is not USPS delivery.

Ready to get started?

Upload your PDF and we will handle printing and mailing.

Open guided form

Resources

All machine form schemasGuided formCurrent JSON schemaMachine order guidePricing
View it in markdown