Estimate Response

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/thanks-io/json-schema/thanks-io-estimate-response-schema.json",
  "title": "Estimate Response",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/thanks-io-openapi.json#/components/schemas/estimate-response",
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Mailer type that was priced. A 6x9 postcard is reported as `postcard6x9` and a 6x11 postcard as `postcard6x11`; `postcard` means 4x6.",
          "enum": [
            "postcard",
            "postcard6x9",
            "postcard6x11",
            "letter",
            "windowlessletter",
            "notecard",
            "magnacard",
            "giftcard"
          ]
        },
        "size": {
          "type": [
            "string",
            "null"
          ],
          "description": "Postcard size that was priced. `null` for other mailer types."
        },
        "total_recipients": {
          "type": "integer",
          "description": "Number of pieces the order would mail."
        },
        "recipients": {
          "type": "object",
          "description": "`total_recipients` split by destination.",
          "properties": {
            "united_states": {
              "type": "integer"
            },
            "international": {
              "type": "integer"
            }
          }
        },
        "pending_email_lookups": {
          "type": "integer",
          "description": "Recipients sent with an email address but no mailing address. The estimate does not run the email-to-address lookup, so they are priced as if an address is found. Any whose address can't be found when you send are not mailed or charged."
        },
        "costs_in_cents": {
          "type": "object",
          "description": "Breakdown of the total, in cents.",
          "properties": {
            "united_states": {
              "type": "integer",
              "description": "Printing and postage for US pieces."
            },
            "international": {
              "type": "integer",
              "description": "Printing and postage for international pieces."
            },
            "additional_pages": {
              "type": "integer",
              "description": "Additional letter pages, priced per page. `0` for other mailer types."
            },
            "giftcard_face_value": {
              "type": "integer",
              "description": "Combined face value of every gift card in the order. `0` for other mailer types."
            },
            "grand_total": {
              "type": "integer",
              "description": "Everything except gift card face value. This can include fees not broken out above, such as radius search records."
            }
          }
        },
        "total_cost_in_cents": {
          "type": "integer",
          "description": "The order total: `grand_total` plus `giftcard_face_value`. For every mailer type except gift cards, this is what the same request is charged when you send it. See Estimate Giftcard for how gift card face value is billed."
        },
        "total_cost": {
          "type": "string",
          "description": "`total_cost_in_cents` formatted in dollars."
        },
        "current_balance_in_cents": {
          "type": "integer",
          "description": "Your account's credit balance right now."
        },
        "covered_by_balance": {
          "type": "boolean",
          "description": "`true` if `current_balance_in_cents` covers `total_cost_in_cents`."
        },
        "test_mode": {
          "type": "boolean",
          "description": "`true` if API Test Mode is on for your account. The estimate always quotes your real rates, while a send in test mode is not charged."
        },
        "notes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Plain-language caveats about anything that could make the real charge differ, such as email-only recipients or a PDF whose pages could not be counted. Empty when there are none."
        }
      }
    }
  }
}