Offers and install links

Shareable offer URLs that drive the install wizard from your Package schema

An offer is a shareable URL (akua.dev/i/<hash>) that takes a customer straight into the install wizard for a product. The wizard is generated entirely from the product’s Akua Package: the input schema, docstrings, and any @ui(...) annotations you have added.

The formal resource is called an Offer. The colloquial term “install link” still refers to the short hash URL a customer clicks. (CEP-0026)

The flow

When you publish a new Package version, Akua exports its input schema and caches the result. Every offer link reads from that cached schema, with no export round-trip on the hot path. (CEP-0026)

What the install wizard renders

The wizard is JSON-Schema-driven. Each property becomes a field; x-ui extensions control presentation:

• order: numeric position in the form (lower = earlier)
• group: section header the field is grouped under
• widget: field renderer hint ("slider", "password", "textarea", "select")
• placeholder: placeholder text for the input
• min / max: numeric bounds, also used by sliders

A package.k schema like this:

schema Input:
    @ui(order=10, group="Identity")
    appName: str
    """Application name. Lowercase, hyphen-separated."""

    @ui(order=20, group="Identity", placeholder="app.example.com")
    hostname: str
    """Public hostname. Must be a valid RFC 1123 DNS name."""

    @ui(order=30, group="Capacity", widget="slider", min=1, max=20)
    replicas: int = 3
    """Number of replicas."""

renders as a wizard with:

• Identity section
  • Application name field with the docstring as help text
  • Public hostname field with app.example.com placeholder
• Capacity section
  • Number of replicas slider, range 1–20, default 3

Field labels come from the property name (sentence-cased); help text comes from the KCL docstring.

Pre-filled and locked fields

Offers can carry pre-filled input values (field_values). Three independent properties apply to each field:

Property	Source	Customer sees
Pre-filled	field_values present in the offer	Form renders with the value populated
Locked	field_values[k].locked: true	Read-only with a lock icon; customer cannot override
Sensitive	x-ui.sensitive: true on the Package schema	Value visually masked (••••••) regardless of editability

A license key is typically pre-filled, locked, and sensitive. An Akua-approved tier is pre-filled, locked, and not sensitive. A customer-supplied API token is not pre-filled, not locked, and sensitive.

field_values are validated against the pinned Package version’s input schema when the offer is created. An offer that would fail at install time cannot be created. (CEP-0026)

What an offer carries

A bare offer link points at a product:

akua.dev/i/<product-slug>

The customer opens it, lands in the wizard, fills in inputs, picks a region, and submits. Akua creates the installation and provisions a package repository for it.

Offer links can also pre-fill inputs via query string:

akua.dev/i/<product-slug>?hostname=app.acme.com&tier=production

Pre-filled fields show up in the wizard already populated; the customer can review and adjust. This is useful for partner-driven flows and for marketplace listings that include a deep link with sensible defaults.

Offer access control

Offers support two access patterns:

Pattern	Configuration	Use case
Public, reusable	No allowed_emails, no max_uses	Website or marketing link
Per-customer, single-use	allowed_emails: [email], max_uses: 1	Private customer onboarding

When allowed_emails is set, the customer must authenticate with a matching verified email before the offer resolves. Offers can also carry an expiry date and a maximum number of redemptions.

What authors control

The wizard’s quality is the schema’s quality. To make a great install experience:

1. Write docstrings on every field: they become help text under each input.
2. Group related fields: use @ui(group="...") consistently; without grouping, fields stack as a flat form.
3. Order intentionally: use @ui(order=...) for the natural fill order. Required fields first, then optional; identity before capacity.
4. Pick widgets with intent: a replicas: int field as a slider with min/max reads better than a number input.
5. Use unions for choices: tier: "startup" | "production" renders as a dropdown automatically.
6. Add check: blocks for cross-field validation; these produce wizard-side error messages on the customer’s inputs.

Updating inputs after install

Once installed, customers can edit their inputs in the wizard (Settings → Inputs), through the CLI, or by pushing to their installation’s git repository. All three update the same inputs.yaml. Akua re-renders on every change.

API

Offers API

Create, resolve, revoke, and manage offers.

Order Drafts API

Track customer order drafts and checkout sessions.

Related topics

Package format

Authoring package.k and @ui annotations.

Marketplace

How products and offers surface to customers.

Customizing inputs

Wizard, CLI, or git push: three views of the same state.

Payments

Customer payment flow and Stripe Connect setup.