Have It Printed

What Have It Printed does, what it costs, what file types and sizes are accepted, and how mailing works. Needs a Bearer API key, like every tools/call (POST /v1/onboard to get one).

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Start a print-and-mail job. Returns an opaque job_handle used by every later call. Creates nothing chargeable.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Get a short-lived upload URL for the customer's document. PUT the bytes to it. File type and size limits are the same as the website.

{
  "type": "object",
  "properties": {
    "job_handle": {
      "type": "string"
    },
    "filename": {
      "type": "string"
    },
    "content_type": {
      "type": "string"
    }
  },
  "required": [
    "job_handle",
    "filename"
  ],
  "additionalProperties": false
}

Set the documents, print options and US mailing recipient on a job. Price fields are rejected: the server computes all amounts.

{
  "type": "object",
  "properties": {
    "job_handle": {
      "type": "string"
    },
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string"
          },
          "pages": {
            "type": "integer",
            "minimum": 1
          },
          "quantity": {
            "type": "integer",
            "minimum": 1
          },
          "color": {
            "type": "string",
            "enum": [
              "bw",
              "color"
            ]
          },
          "size": {
            "type": "string",
            "enum": [
              "8.5x11",
              "8x10",
              "11x17"
            ]
          }
        },
        "required": [
          "filename",
          "pages"
        ],
        "additionalProperties": false
      }
    },
    "options": {
      "type": "object",
      "additionalProperties": true
    },
    "recipient": {
      "type": "object",
      "description": "US mailing address",
      "properties": {
        "name": {
          "type": "string"
        },
        "line1": {
          "type": "string"
        },
        "line2": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "state": {
          "type": "string",
          "description": "2-letter US state code"
        },
        "zip": {
          "type": "string"
        },
        "country": {
          "type": "string",
          "default": "US"
        }
      },
      "required": [
        "name",
        "line1",
        "city",
        "state",
        "zip"
      ]
    }
  },
  "required": [
    "job_handle"
  ],
  "additionalProperties": false
}

Exact price for the job, computed by the same pricing the website checkout uses. Tax, if any, is added by Stripe at payment.

{
  "type": "object",
  "properties": {
    "job_handle": {
      "type": "string"
    }
  },
  "required": [
    "job_handle"
  ],
  "additionalProperties": false
}

Create a Stripe Checkout session for the job and return its URL. This does NOT take payment: the customer completes payment at that URL. Show them the quote first.

{
  "type": "object",
  "properties": {
    "job_handle": {
      "type": "string"
    },
    "customer_email": {
      "type": "string",
      "description": "for the receipt and tracking email"
    }
  },
  "required": [
    "job_handle"
  ],
  "additionalProperties": false
}

Whether the customer has paid yet. Payment truth comes from the order record Stripe's webhook creates, never from a browser redirect.

{
  "type": "object",
  "properties": {
    "job_handle": {
      "type": "string"
    }
  },
  "required": [
    "job_handle"
  ],
  "additionalProperties": false
}

Resolve the EXACT amount HIP will charge, before any payment authorization is obtained or spent. This does NOT charge anything. Returns subtotal_cents, tax_cents, total_cents, currency, a pricing fingerprint and the authorization types HIP accepts. Tax is calculated by Stripe from the destination, so hip_quote alone is not the payable amount. The returned total is bound to this job's documents, options and recipient: change any of them and payment is refused with QUOTE_STALE until you prepare again. Use this when paying autonomously with a delegated payment authorization; a human paying in a browser does not need it. Commits the job to the autonomous payment rail.

{
  "type": "object",
  "properties": {
    "job_handle": {
      "type": "string"
    },
    "buyer_email": {
      "type": "string",
      "description": "optional: the buyer's email address. Have It Printed sends its order confirmation there once the payment succeeds."
    }
  },
  "required": [
    "job_handle"
  ],
  "additionalProperties": false
}

Pay for the job with a delegated payment authorization, with no browser and no human step. payment_authorization must be a Stripe shared payment token (spt_...) granted to Have It Printed whose maximum is at least the total from hip_prepare_payment; HIP charges exactly that total and never more. NEVER send a card number, expiry, CVV or any reusable credential to this tool. If the cardholder's bank requires authentication, this returns payment_status=requires_user_action rather than bypassing it.

{
  "type": "object",
  "properties": {
    "job_handle": {
      "type": "string"
    },
    "payment_authorization": {
      "type": "string",
      "description": "opaque delegated payment token (spt_...)"
    }
  },
  "required": [
    "job_handle",
    "payment_authorization"
  ],
  "additionalProperties": false
}

Status and USPS tracking for the paid order belonging to this job.

{
  "type": "object",
  "properties": {
    "job_handle": {
      "type": "string"
    }
  },
  "required": [
    "job_handle"
  ],
  "additionalProperties": false
}