Payments

{
  "title": "Home consultation",
  "priceCents": 10000,
  "customizations": [
    {
      "customizationId": "job-address",
      "label": "Property address",
      "kind": "address",
      "required": true,
      "includeInReceipt": false
    }
  ]
}

frontpage payments buttons create --id consultation --file consultation.json --site acme --json

{
  "ok": true,
  "command": "payments",
  "data": {
    "slug": "acme",
    "button": {
      "itemId": "consultation",
      "title": "Home consultation",
      "checkout": "instant",
      "variants": [
        {
          "variantId": "default",
          "priceCents": 10000,
          "stock": null
        }
      ]
    },
    "markup": "<button data-fp-pay=\"consultation\" data-fp-requires=\"pay\">Pay now <span data-fp-pay-bind=\"price\"></span></button>"
  }
}

{
  "recipient": {
    "name": "Docs test customer",
    "email": "customer@example.com",
    "address": {
      "line1": "354 Oyster Point Blvd",
      "city": "South San Francisco",
      "region": "CA",
      "postal": "94080",
      "country": "US"
    }
  },
  "description": "Website maintenance",
  "amountCents": 12500,
  "kind": "once",
  "collection": "manual",
  "dueDays": 14
}

frontpage payments invoices preview --file invoice.json --site acme --json

{
  "ok": true,
  "command": "payments",
  "data": {
    "slug": "acme",
    "currency": "usd",
    "subtotalCents": 12500,
    "taxCents": 1234,
    "totalCents": 13734,
    "taxEnabled": true,
    "billingContactChanged": false,
    "previewHash": "ce04ecbbe777c9cf57cf7a0abcf4dbf13ceedfad10cee87db1fd5c8b765cf723"
  }
}

frontpage payments invoices send --file invoice.json --preview-hash "$PREVIEW_HASH" --operation-key "$OPERATION_KEY" --yes --site acme --json

{
  "ok": true,
  "command": "payments",
  "data": {
    "slug": "acme",
    "invoice": {
      "id": "aeb31529-2a3a-4cd5-9391-c52b27664c27",
      "source": "invoice",
      "status": "open",
      "operationState": "complete",
      "currency": "usd",
      "subtotalCents": 12500,
      "taxCents": 1234,
      "totalCents": 13734,
      "amountPaidCents": 0,
      "amountRemainingCents": 13734,
      "delivery": "accepted",
      "paidAt": null
    }
  }
}

frontpage payments invoices get "$INVOICE_ID" --site acme --json

curl --fail-with-body "https://app.frontpage.host/api/v1/sites/acme/payments/invoices/$INVOICE_ID"   -H "Authorization: Bearer $FRONTPAGE_API_KEY"

{
  "ok": false,
  "command": "payments",
  "error": {
    "code": "bad_request",
    "message": "amountCents must be an integer number of cents. $49.99 is 4999.",
    "httpStatus": 400,
    "exitCode": 2,
    "requestId": "2fff6eca-ac37-4303-a30c-f30e6321829b"
  }
}

Requires frontpage-host 0.2.1 or later. Install with npm i -g frontpage-host@latest.

Frontpage keeps one Stripe Express account per site. Store owns products, cart checkout, fulfillment, buyer service fees, the default receipt and orders. Payments owns Stripe setup, the shared currency, tax, payment activity, saved Offerings behind Pay now buttons, their receipt templates and customer invoices. Frontpage subscription billing stays separate.

Use frontpage help payments --json for discoverable command help. Normal --site, authentication, --json, --quiet and exit-code rules apply. The API requires Scale, Enterprise or Internal CLI access. This does not remove product permissions or invoice entitlements.

frontpage payments buttons create --id digital-bundle --title "E-book + workbook" --price-cents 2500 --active false --json

{
  "checkout": "standalone",
  "requiresFulfillment": false,
  "button": {
    "itemId": "digital-bundle",
    "active": false
  },
  "setup": {
    "status": {
      "state": "not_connected",
      "ready": false
    },
    "url": "https://app.frontpage.host/api/payments/connect/start?slug=YOUR_SITE"
  }
}

frontpage payments buttons update digital-bundle --receipt-template-id TEMPLATE_UUID --json
frontpage payments buttons receipt-preview digital-bundle --json
frontpage payments buttons update digital-bundle --active true --json

POST /api/v1/sites/YOUR_SITE/payments/buttons/digital-bundle/receipt-preview
Content-Type: application/json

{"vars":{"buyer_name":"Casey"}}

Access and output

All routes authorize the API-key owner against the requested site. A different site's record returns 404. Request fields cannot grant a role, change the trusted site or choose a connected account. JSON success uses the existing CLI envelope { "ok": true, "command": "payments", "data": { ... } }. Failure uses the existing error envelope with request ID and exit code. Human mode prints the returned fields, including partial outcomes. A successful HTTP request does not mean a payment settled or an email arrived.

Setup, availability and history

frontpage payments status
frontpage payments settings --json
frontpage payments connect --no-open
frontpage payments availability preview --json
frontpage payments availability off --yes
frontpage payments availability on --yes
frontpage payments activity list --json
frontpage payments activity get <record-uuid> --source order

Connect returns the existing signed-in admin browser URL. Without --no-open, human mode opens it. The CLI does not accept Stripe terms, finish onboarding or create another account to get around a restriction. Recheck status after the browser flow. Account existence or a return URL alone does not prove readiness. Payments saves the shared currency during the existing Stripe setup. Store, Offerings, invoices and Printify read that same currency. It is read-only; do not set a second Store currency. Existing payments retain their captured currencies.

Payments off first blocks new charges, then stops recurring billing and voids unpaid issued invoices. It preserves paid history and the Express account. Review the counts with availability preview. off reads current counts before its confirmed write; a changed set returns 409. A bounded request may return pause.complete:false, remaining counts and failed record IDs. New charging stays blocked. Resolve errors and repeat off; do not turn Payments on while a pause is incomplete. A payment already processing may settle and keeps its real result.

Turning Payments on rechecks Stripe readiness. It does not enable Store, restore void invoices, resume arrangements or collect missed periods. Store off affects only Store; it leaves standalone payments and billing running.

Activity combines the latest 200 Store orders and 200 Pay now payments with up to 100 invoices and 100 recurring arrangements each. mayHaveMore states when older records may exist. It preserves captured currencies, amounts and payment states. Recurring amounts are per-period amounts before tax. Use invoice/recurring list commands for their paginated history. Get an order/payment with its explicit source; equal IDs in different tables do not identify the same record.

Activity uses Customer, Type, Status, Amount and Date. Date is the verified payment time, not creation or due date. Unpaid invoices and recurring arrangements show no payment date; historic payments without a verified timestamp remain unknown. Summary counts cover the full site, independent of recent-list caps.

Tax

frontpage payments tax get --json
frontpage payments tax settings --file tax-settings.json --yes
frontpage payments tax registrations list
frontpage payments tax registrations add --country US --state CA --yes
frontpage payments tax registrations end <tax-registration-id> --yes

Tax settings JSON contains country, line1, city, optional state, postal and an existing supported taxCode. GET returns current choices and registrations. Use the business's actual address and registrations. Frontpage does not choose jurisdictions or provide tax advice. End uses the exact registration ID returned by Stripe. These operations reuse current connected-account tax helpers. They do not expose Account Session secrets or a second tax calculator. An invoice preview blocks if tax settings cannot be confirmed; it does not silently drop tax.

Invoice input and review

For an existing CRM person:

{
  "recipient": { "personId": "<crm-person-uuid>" },
  "description": "Website maintenance",
  "amountCents": 12500,
  "kind": "once",
  "collection": "manual",
  "dueDays": 14
}

To add or match a CRM customer when sending, replace recipient with:

{
  "name": "Customer name",
  "email": "customer@example.com",
  "address": {
    "line1": "Customer billing street",
    "city": "City",
    "region": "CA",
    "postal": "94080",
    "country": "US"
  }
}

address also accepts line2. Supply a real billing address when automatic tax needs it. A CRM person must be visible and have a valid billing email. Inline matching stays within the site and does not grant marketing permission. Preview creates no CRM person, Stripe Customer, invoice, invitation or charge.

Money fields use integer minor units in the account currency despite the existing Cents field names. USD 12500 means $125.00; JPY 12500 means ¥12500. The current amount range is 50 through 10,000,000 minor units. Description contains 1–500 characters. dueDays is 7, 14 or 30; omitted means 7. A one-time invoice uses manual collection and cannot carry recurring date/cadence fields.

frontpage payments invoices preview --file invoice.json --json
frontpage payments invoices send --file invoice.json \
  --preview-hash <hash-from-preview> --operation-key <stable-uuid> --yes --json

Preview returns the normalized recipient/terms, currency, subtotal, tax, total, tax status and previewHash. When billingContactChanged is true, review the CRM email, name and address and pass --confirm-billing-contact to update the saved Stripe contact for future billing. This does not rewrite issued invoices or prior consent. Send repeats those exact terms and hash. It rechecks readiness and totals before finalization/delivery. Changed terms or totals return 409. Common flags can replace simple JSON fields: --person or --email with --name, --description, --amount-cents, --kind, --collection, --due-days, --cadence, --first-date, --time-zone. Nested addresses use --file.

The operation key contains 16–120 letters, digits, dots, colons, underscores or hyphens and starts with a letter/digit. A UUID is suitable. Preserve the same key and input after a timeout or uncertain result. Do not use a new key to force a send. Repeated requests return the same local/Stripe invoice rather than charging again. If Stripe's safe retry window has passed, reconcile the saved object first.

Invoice management

frontpage payments invoices list --limit 50 --offset 0 --json
frontpage payments invoices list --arrangement <arrangement-uuid> --json
frontpage payments invoices get <invoice-uuid>
frontpage payments invoices refresh <invoice-uuid>
frontpage payments invoices resend <invoice-uuid> --operation-key <stable-uuid> --yes
frontpage payments invoices void <invoice-uuid> --yes

List accepts limit 1–100 and offset 0–100000; it returns nextOffset or null. Records include immutable recipient/terms, actual currency/subtotal/tax/total, paid/remaining amounts, due/issued/paid dates, Hosted Invoice Page/PDF, delivery and any last error. Expected platform fee and actual collected fee are separate. An unpaid invoice does not claim a collected fee. Source account/setup secrets and customer-access nonces are not returned.

Resend only accepts an open invoice and uses its existing saved billing customer. It never creates a replacement invoice. Void requires confirmation and cannot restore an invoice after Stripe confirms it is void. A payment race preserves an actual paid result. An unsent draft's cancellation is recorded separately from Stripe's real draft state. There is no manual mark-paid, refund or raw charge API.

Stripe sends invoice emails and hosts payment/recovery. delivery:accepted means the send API accepted the request, not that the email arrived or was opened. Stripe test mode may suppress email delivery; provider acceptance is the most that a test-mode report may claim.

Recurring manual invoices and autopay

Use the same recipient, description, amount and due window. Set kind:recurring, cadence, firstDate and timeZone. Collection is manual or autopay.

{
  "recipient": { "personId": "<crm-person-uuid>" },
  "description": "Monthly maintenance",
  "amountCents": 12500,
  "kind": "recurring",
  "collection": "manual",
  "cadence": "monthly",
  "firstDate": "2026-12-01",
  "timeZone": "America/Chicago",
  "dueDays": 14
}

Supported cadences are weekly, fortnightly, monthly, quarterly, yearly. The first date is YYYY-MM-DD in an explicit IANA zone. Billing begins at 09:00 in that zone. Choose a future date. Stripe owns later native calendar periods, including short months/leap years. No Frontpage recurring scheduler, backfill or proration is added.

New recurring arrangements use Stripe's native platform fee: 2% of the invoice total, including tax, unless the existing server fee setting is zero. The saved arrangement freezes that server-controlled rate before billing starts. For example, a $100 invoice plus $9.88 tax has a $2.20 platform fee. The fee is deducted from the business's proceeds, not added as a customer surcharge. Stripe's own processing and Billing/Invoicing charges are separate. Store, Pay now and one-time invoice fee calculations keep their existing basis. Reconciliation records expected and actual fees; it does not set the fee or collect recurring payments. Stripe handles collection even if a webhook is late.

frontpage payments recurring preview --file recurring.json --json
frontpage payments recurring create --file recurring.json \
  --preview-hash <hash> --operation-key <stable-uuid> --yes
frontpage payments recurring list --limit 50 --offset 0 --json
frontpage payments recurring get <arrangement-uuid>
frontpage payments recurring refresh <arrangement-uuid>
frontpage payments recurring cancel <arrangement-uuid> --yes
frontpage payments recurring resend-invitation <arrangement-uuid> \
  --operation-key <stable-uuid> --yes

Manual collection creates a native future Stripe schedule. It does not issue an immediate first invoice. Stripe creates one invoice per period and emails the hosted payment link. Autopay create saves a pending authorization and sends an invitation. The customer reviews the amount, tax, cadence and first date, agrees, and finishes Stripe-hosted setup on the same connected account/customer. Only verified setup can start the schedule. A saved method, setup return query or owner flag alone never supplies consent. Setup itself is not a payment.

Arrangement cancellation stops future billing without changing issued invoices or adding a final prorated charge. Payments off pauses arrangements by stopping their native future schedule. Only paused arrangements may resume. Preview the same recipient/amount/cadence/collection with a new future date, then:

frontpage payments recurring resume <paused-arrangement-uuid> \
  --first-date 2026-12-01 --preview-hash <hash-from-preview> \
  --operation-key <stable-uuid> --yes

Resume creates a linked future arrangement with no missed-period invoices. A second different resume request is refused. Autopay seeks fresh customer consent. Changed terms require cancellation and a new reviewed request; there is no hidden edit/proration action. Invitation resend applies only while awaiting authorization. It expires/replaces an unfinished old setup and keeps its own retry key.

Customer billing access

frontpage payments customers send-billing-link <customerMapId> \
  --operation-key <stable-uuid> --yes
frontpage payments customers billing-link <customerMapId> \
  --operation-key <stable-uuid> --json

Use customerMapId from the site's invoice/arrangement. It is not a raw Stripe customer ID. Send uses the mapped customer's current saved Stripe billing email; the caller cannot choose another recipient. Links expire after 30 minutes. A raw returned link is sensitive: do not log/share it. The website agent only sends links; it cannot request raw customer access.

Customer access needs no owner login. It stays scoped to site/account/customer and uses a small customer page plus the connected-account Stripe portal. The customer can pay an invoice, change the saved method, cancel future billing or choose manual payment for future invoices. These actions do not pay an existing balance, authorize another arrangement or expose Frontpage subscription billing. Authorization invitations expire after 24 hours; an expired link requires a new invitation. A completed authorization exposes Manage billing.

Offerings behind Pay now

Every website Pay now payment requires a saved, registered Offering in Payments. Store carts and invoices keep their own saved payment records. Markup, an arbitrary amount, a nonshipping Store item or an old instant flag cannot authorize a charge. The workspace, CLI and website agent use the same Offering service and existing item/price storage.

frontpage payments buttons list --limit 50 --offset 0 --json
frontpage payments buttons create --id consultation --title "Initial consultation" --price-cents 10000
frontpage payments buttons get consultation
frontpage payments buttons update consultation --title Consultation --price-cents 12500 --active true
frontpage payments buttons update consultation --receipt-template-id TEMPLATE_UUID
frontpage payments buttons update consultation --default-receipt
frontpage payments buttons update consultation --active false
frontpage payments buttons archive consultation --yes
frontpage payments buttons list --archived true
frontpage payments buttons restore consultation --yes

Create/update accepts --file offering.json. Price, details, questions and template choice save together. IDs use 2–40 lowercase kebab characters. Customer-chosen amounts use --amount open --min-cents 1000 --price-cents 1000 in the connected account's minor units. Currency comes from Stripe; a page cannot supply it. Shipping and fulfillment belong to Store.

Create/update returns the saved object and this markup. Bind it in the same change:

<button data-fp-pay="consultation" data-fp-requires="pay">Pay now <span data-fp-pay-bind="price"></span></button>

The platform loads the saved price, minimum and availability. Do not use data-amount, substitute a Store product ID, build card inputs, or call Stripe directly. Paused, archived, wrong-site and unregistered Offerings cannot charge. Archive removes an Offering from new checkout and retains history; restore can bring it back. Standalone Offering management is available on every plan; charging still requires normal Payments readiness.

--receipt-template-id selects an available Emails template from the same site. --default-receipt uses the existing site default; the flags are mutually exclusive. Checkout freezes that choice. A deleted template uses the stock receipt, with the same retry identity to prevent a second send. Receipts follow verified payment and existing email limits; they do not grant marketing consent.

Payments drawer design

Pay now Offerings do not need a Store cart or Cart button. Fixed payments without questions proceed to Stripe Checkout. Custom amounts and saved questions use the platform's independent Payments drawer. Changing questions in Payments, the CLI or agent tools updates the next opening without republishing the site.

A default drawer works without a template. To design your own, include one shared template using the following hooks. The platform fills the price, amount field, saved questions and errors and handles submission. Keep forms, scripts, manually written questions and Store hooks out of this template.

<template data-fp-payment-drawer>
  <section data-fp-payment-panel>
    <header><h2 data-fp-payment-bind="title"></h2><button data-fp-payment-close>Close</button></header>
    <p data-fp-payment-bind="description"></p>
    <p data-fp-payment-bind="price"></p>
    <div data-fp-payment-amount></div>
    <div data-fp-payment-fields></div>
    <p data-fp-payment-error></p>
    <button data-fp-payment-confirm>Continue to payment</button>
  </section>
</template>

Defaults use the soft fp-defaults CSS layer. Override appearance with your own root class and global CSS, as with Store templates. Payments supports --fp-payment-bg, --fp-payment-fg, --fp-payment-border, --fp-payment-radius, --fp-payment-width, --fp-payment-padding, --fp-payment-action-bg, --fp-payment-action-fg and --fp-payment-focus. Style generated fields beneath your root using .fp-payment-customization and .fp-payment-address. Design changes use normal website publishing. Stripe Checkout keeps its supported branding controls.

Customer details

Save questions on the Offering through customizations, using the same shared fields as Store. Example offering.json:

{
  "title": "Home consultation",
  "priceCents": 10000,
  "customizations": [
    {
      "customizationId": "job-address",
      "label": "Property address",
      "kind": "address",
      "required": true
    },
    {
      "customizationId": "contact",
      "label": "Preferred contact",
      "kind": "choice",
      "values": [
        "Phone",
        "Email"
      ]
    },
    {
      "customizationId": "instructions",
      "label": "Access instructions",
      "kind": "textarea",
      "maxLength": 1000,
      "includeInReceipt": false
    }
  ]
}

frontpage payments buttons update consultation --file offering.json --json
frontpage payments buttons get consultation --json
frontpage payments activity get ORDER_UUID --source order --json

At most eight questions. Types: short text (up to 200 characters), long text (up to 2000), choice (up to 20 values), checkbox, email, phone, number, date and structured address. API kinds are text, textarea, choice, checkbox, email, phone, number, date and address. Text accepts maxLength; numbers accept min/max. Choices require explicit selection and required checkboxes require an affirmative check.

The existing payment drawer renders and validates these questions before Stripe Checkout. Zero and false retain their meaning. A service address does not enable shipping; a preferred date is a request, not a confirmed booking. Intake answers cannot change money, currency or tax, and do not overwrite People. An unrelated page form does not automatically become a paid submission.

Keep stable customizationId values when renaming/reordering. Replacing the array changes future checkouts. Paid records retain the captured labels, kinds and answers under Customer details, even after questions change or disappear. Answers default out of receipts; opt in per field with includeInReceipt:true. Keep answers out of page markup, URLs and Stripe product names. Files, conditional questions, paid selections and public recurring Offering signup are not supported.

A normal request such as “add a $100 consultation button and ask for the property address” lets the website agent find/reuse or create an Offering and bind its button in the same turn. Customers do not need to know object IDs. Missing essential terms such as price need clarification. The agent cannot authorize customer autopay consent.

Confirmation emails from customer answers

Use the existing Emails templates. There is no separate email engine or variable mapping UI. Offering create, get and update responses include receiptVariables: the exact names and labels available for that Offering. Read the response before writing the template.

The five purchase variables are buyer_name, buyer_email, total, currency and items. A field with includeInReceipt:true also exposes answer_<customizationId>. For a saved field called review-date, use {{answer_review-date}}. Names follow stable IDs, so renaming a label does not break its email. Private answers never become variables or enter the items summary.

frontpage payments buttons get portfolio-review --json
frontpage mail template create --file confirmation.json --json
frontpage payments buttons update portfolio-review --receipt-template-id TEMPLATE_UUID --json
frontpage payments buttons get portfolio-review --json
frontpage mail template get TEMPLATE_UUID --json

Declare each used name in the template's variables array, then use it in its subject, preview or blocks. The server rejects attachment or question changes when the template uses an unavailable answer. Detach the template, change it, or keep the field included before retrying. Shared templates must work for every unarchived Offering attached to them. To restore an Offering with an incompatible template, use --default-receipt or fix its template first.

Confirmed purchases use the captured answers, not later field edits. Blank optional answers stay blank; private answers stay private. The normal verified-payment receipt path sends once and retains its existing limits and stock fallback if a template is deleted. Do not manually send the customer's receipt or enrol them in marketing. Forms keep their existing input-name variables and confirmTemplateId; Offerings use receiptTemplateId. The website agent uses these same services.

Activity and dates

Activity includes all saved Offerings, including archived ones in the management list. Payment summaries show gross receipts, successful-payment count and average payment over the last 30 days across Store, Offerings and invoices. They cover the full ledger, not only the visible recent rows. Each currency has its own total; currencies are never added together. Gross receipts precede fees and refunds.

The Date column shows when a verified payment happened. An unpaid invoice or recurring arrangement has no payment date. New payments save the webhook event's date. The activity service can recover recent missing dates from matching Stripe events without replaying purchases, emails or fulfillment. Stripe retains Events for 30 days; older or unverified dates remain unavailable rather than using checkout creation as a payment date.

REST paths

All paths below use /api/v1/sites/{slug}/payments. GET query fields match the documented filters. POST/PATCH fields match the reviewed domain inputs above. Financial consequences need confirm:true; stable retryable sends additionally need operationKey. This is a resource API, not arbitrary action dispatch.

Common failures: 400 invalid input/retired write; 401 no authentication; 403 role, CLI tier or product entitlement; 404 wrong site/record; 409 stale review, conflict, unfinished pause or unknown provider outcome; 429 existing rate limit; 503 missing rate-limit service, tax-read failure or provider failure. Keep the request ID when reporting a failure. Never retry a financial send with a new key just because an HTTP response was lost.

Breaking release

Version 0.2.0 removes Store connect/status/disconnect/payments, writable currency and checkout mode from CLI/public API/agent contracts. Use payments for money operations. Store remains cart-only and keeps existing resource paths under /shop. Saved products/orders, Express accounts, current visitor hooks, /__pay, Connect webhooks and old browser callbacks remain intact. Old binaries may fail on retired endpoints; no compatibility alias or data conversion runs.