{"openapi":"3.1.0","info":{"title":"Postlane","version":"0.1.0","description":"US print and mail. No signup. Capability tokens protect private documents and orders. Upload → quote → approve standardized address and budget → guest checkout → track. Choose human-approved Stripe Checkout or, when enabled, authorized agent payments through MPP (card SPT) or x402 (USDC on Base). Creating an order never pays it."},"servers":[{"url":"https://postlane.tameravci.com"}],"components":{"schemas":{"Address":{"type":"object","additionalProperties":false,"required":["name","address_line1","address_city","address_state","address_zip"],"properties":{"name":{"type":"string"},"address_line1":{"type":"string"},"address_line2":{"type":"string"},"address_city":{"type":"string"},"address_state":{"type":"string","description":"Two-letter state code, 50 states or DC."},"address_zip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$"},"address_country":{"const":"US","default":"US"}}},"Upload":{"type":"object","required":["filename","pdf_base64"],"additionalProperties":false,"properties":{"filename":{"type":"string"},"pdf_base64":{"type":"string","contentEncoding":"base64","description":"1–20 portrait US Letter pages, max 5 MB, no data URL prefix."}}},"QuoteRequest":{"type":"object","additionalProperties":false,"required":["document_id","document_token","destination"],"properties":{"document_id":{"type":"string"},"document_token":{"type":"string","description":"Private capability token returned by the preceding step. Keep secret."},"destination":{"$ref":"#/components/schemas/Address"},"color":{"type":"boolean","default":false},"duplex":{"type":"boolean","default":true}}},"OrderRequest":{"type":"object","additionalProperties":false,"required":["quote_id","quote_token","max_amount_cents","accept_standardized_address"],"properties":{"quote_id":{"type":"string"},"quote_token":{"type":"string","description":"Private capability token returned by the preceding step. Keep secret."},"max_amount_cents":{"type":"integer","minimum":1},"accept_standardized_address":{"const":true},"payment_method":{"type":"string","enum":["checkout","mpp","x402"],"default":"checkout","description":"Choose an enabled method from capabilities.payment.methods. One method per order."},"idempotency_key":{"type":"string","minLength":16,"maxLength":100,"description":"Required in body or Idempotency-Key header. Reuse for identical retries."}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}}}}},"Document":{"type":"object","required":["id","document_token","pages","filename","sha256","expires_at"],"properties":{"id":{"type":"string"},"document_token":{"type":"string","description":"Private capability token returned by the preceding step. Keep secret."},"filename":{"type":"string"},"pages":{"type":"integer","minimum":1,"maximum":20},"sha256":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"print_note":{"type":"string"}}},"Verification":{"type":"object","required":["address","deliverability","provider","verified"],"properties":{"address":{"$ref":"#/components/schemas/Address"},"deliverability":{"type":"string","enum":["deliverable","deliverable_unnecessary_unit","demo_unverified"]},"provider":{"type":"string","enum":["lob","simulator"]},"verified":{"type":"boolean","description":"Only true for live Lob verification, never demo/test fixtures."}}},"Quote":{"type":"object","required":["id","quote_token","document_id","destination","amount_cents","currency","expires_at","preview_url","mode"],"properties":{"id":{"type":"string"},"quote_token":{"type":"string","description":"Private capability token returned by the preceding step. Keep secret."},"document_id":{"type":"string"},"filename":{"type":"string"},"pages":{"type":"integer"},"sheets":{"type":"integer"},"color":{"type":"boolean"},"duplex":{"type":"boolean"},"destination":{"$ref":"#/components/schemas/Address"},"verification":{"$ref":"#/components/schemas/Verification"},"mode":{"type":"string","enum":["demo","test","live"]},"currency":{"const":"usd"},"amount_cents":{"type":"integer","minimum":0,"description":"USD cents, never floating-point dollars."},"expires_at":{"type":"string","format":"date-time"},"preview_url":{"type":"string","format":"uri","description":"Private PDF preview link containing a quote capability. Do not share publicly."},"breakdown":{"type":"array","items":{"type":"object","required":["label","amount_cents"],"properties":{"label":{"type":"string"},"amount_cents":{"type":"integer","minimum":0,"description":"USD cents, never floating-point dollars."}}}}}},"Order":{"type":"object","required":["id","status","mode","amount_cents","currency","destination","order_token","receipt_url","events"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["awaiting_payment","queued","submitting","submitted","in_transit","delivered","returned","expired","refund_pending","refunded","needs_attention"]},"mode":{"type":"string","enum":["demo","test","live"]},"amount_cents":{"type":"integer","minimum":0,"description":"USD cents, never floating-point dollars."},"currency":{"const":"usd"},"destination":{"$ref":"#/components/schemas/Address"},"pages":{"type":"integer"},"color":{"type":"boolean"},"duplex":{"type":"boolean"},"order_token":{"type":"string","description":"Private capability token returned by the preceding step. Keep secret."},"receipt_url":{"type":"string","format":"uri","description":"Private order link. Store securely."},"checkout_url":{"type":["string","null"],"format":"uri"},"payment_url":{"type":["string","null"],"format":"uri"},"payment_method":{"type":"string","enum":["checkout","mpp","x402"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"attention":{"type":["string","null"]},"refund":{"type":["object","null"],"properties":{"id":{"type":"string"},"status":{"type":"string"}}},"mail":{"type":["object","null"],"properties":{"provider":{"type":"string"},"expected_delivery_date":{"type":["string","null"]},"proof_url":{"type":["string","null"],"format":"uri"},"tracking_events":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"at":{"type":"string"},"name":{"type":"string"}}}}}},"events":{"type":"array","items":{"type":"object","required":["type","at"],"properties":{"type":{"type":"string"},"at":{"type":"string","format":"date-time"}}}}}},"Capabilities":{"type":"object","required":["name","version","mode","signup_required","countries","document","printing","mail","pricing","payment","mcp_url","openapi_url"],"properties":{"name":{"type":"string"},"version":{"type":"string"},"mode":{"type":"string","enum":["demo","test","live"]},"sends_real_mail":{"type":"boolean"},"signup_required":{"const":false},"support_email":{"type":["string","null"]},"countries":{"type":"array","items":{"const":"US"}},"regions":{"type":"string"},"document":{"type":"object","properties":{"format":{"const":"PDF"},"max_bytes":{"type":"integer"},"max_pages":{"type":"integer"},"paper":{"type":"string"},"orientation":{"type":"string"},"safe_margin_inches":{"type":"number"}}},"printing":{"type":"object","properties":{"color":{"type":"boolean"},"duplex":{"type":"boolean"},"copies_per_order":{"type":"integer"},"address_cover_sheet":{"type":"boolean"},"stapling":{"type":"boolean"}}},"mail":{"type":"object","properties":{"service":{"type":"string"},"certified":{"type":"boolean"},"delivery_guaranteed":{"type":"boolean"},"tracking":{"type":"string"}}},"pricing":{"type":"object","properties":{"currency":{"const":"usd"},"base_cents":{"type":"integer","minimum":0,"description":"USD cents, never floating-point dollars."},"bw_page_cents":{"type":"integer","minimum":0,"description":"USD cents, never floating-point dollars."},"color_page_cents":{"type":"integer","minimum":0,"description":"USD cents, never floating-point dollars."},"flat_envelope_surcharge_cents":{"type":"integer","minimum":0,"description":"USD cents, never floating-point dollars."},"tax":{"type":"string"},"quote_valid_minutes":{"type":"integer"}}},"payment":{"type":"object","properties":{"provider":{"type":"string"},"method":{"const":"guest_checkout"},"methods":{"type":"array","items":{"type":"string","enum":["checkout","mpp","x402"]}},"requires_payment_approval":{"const":true}}},"mcp_url":{"type":"string","format":"uri"},"openapi_url":{"type":"string","format":"uri"}}}},"securitySchemes":{"capability":{"type":"http","scheme":"bearer","description":"The order_token (or quote_token for preview), not an account API key."}}},"paths":{"/v1/orders/{id}/pay/mpp":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"operationId":"payOrderMpp","summary":"Pay with an authorized Stripe Shared Payment Token via MPP","description":"Send no payment credential to receive a 402 challenge. An authorized payment client retries with the protocol credential. Repeat the same order after a timeout; never create a replacement payment for an uncertain result. The amount and method are fixed by the order. Keep order tokens and payment credentials private.","parameters":[{"name":"X-Order-Token","in":"header","schema":{"type":"string","description":"Private capability token returned by the preceding step. Keep secret."},"description":"Required unless order_token is supplied in the JSON body."},{"name":"Authorization","in":"header","schema":{"type":"string"},"description":"Payment credential from an authorized payment client. Omit to request the challenge."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"order_token":{"type":"string","description":"Private capability token returned by the preceding step. Keep secret."}}}}}},"responses":{"200":{"description":"Current order state. A paid receipt is returned in Payment-Receipt (MPP) or PAYMENT-RESPONSE (x402). Check status; needs_attention requires operator reconciliation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"202":{"description":"Payment is processing. Poll the order; do not pay again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"402":{"description":"Payment required or credential rejected. WWW-Authenticate contains the MPP challenge; PAYMENT-REQUIRED contains the base64 x402 requirements.","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders/{id}/pay/x402":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"operationId":"payOrderX402","summary":"Pay with USDC on Base via x402","description":"Send no payment credential to receive a 402 challenge. An authorized payment client retries with the protocol credential. Repeat the same order after a timeout; never create a replacement payment for an uncertain result. The amount and method are fixed by the order. Keep order tokens and payment credentials private.","parameters":[{"name":"X-Order-Token","in":"header","schema":{"type":"string","description":"Private capability token returned by the preceding step. Keep secret."},"description":"Required unless order_token is supplied in the JSON body."},{"name":"PAYMENT-SIGNATURE","in":"header","schema":{"type":"string"},"description":"Payment credential from an authorized payment client. Omit to request the challenge."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"order_token":{"type":"string","description":"Private capability token returned by the preceding step. Keep secret."}}}}}},"responses":{"200":{"description":"Current order state. A paid receipt is returned in Payment-Receipt (MPP) or PAYMENT-RESPONSE (x402). Check status; needs_attention requires operator reconciliation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"202":{"description":"Payment is processing. Poll the order; do not pay again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"402":{"description":"Payment required or credential rejected. WWW-Authenticate contains the MPP challenge; PAYMENT-REQUIRED contains the base64 x402 requirements.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/capabilities":{"get":{"operationId":"getCapabilities","summary":"Capabilities, mode and pricing","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Capabilities"}}}},"default":{"description":"Error. See error.code; use the same idempotency key on retries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/documents":{"post":{"operationId":"uploadDocument","summary":"Validate and upload a PDF","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Upload"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"default":{"description":"Error. See error.code; use the same idempotency key on retries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/addresses/verify":{"post":{"operationId":"verifyAddress","summary":"Verify a US destination","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Address"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Verification"}}}},"default":{"description":"Error. See error.code; use the same idempotency key on retries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/quotes":{"post":{"operationId":"quoteDocument","summary":"Create a fixed 30-minute quote","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"default":{"description":"Error. See error.code; use the same idempotency key on retries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/quotes/{id}/preview":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"previewQuote","summary":"Preview print-ready PDF; cover sheet is blank until the provider adds addresses","security":[{"capability":[]}],"responses":{"200":{"description":"PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}}}}},"/v1/orders":{"post":{"operationId":"createOrder","summary":"Create or recover an idempotent order with a selected payment method","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRequest"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"default":{"description":"Error. See error.code; use the same idempotency key on retries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":16}}]}},"/v1/orders/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"getOrder","summary":"Order status and event history; poll every 10 seconds or slower","security":[{"capability":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"default":{"description":"Error. See error.code; use the same idempotency key on retries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}