Create offer
Creates an Offer for a product or a specific package version. Idempotency is workspace-scoped: reusing an Idempotency-Key with the same create intent returns the original Offer, while reusing it with a changed create intent returns HTTP 409 Conflict. Product-only requests that expire before an Offer is created retain their resolved-version binding and reject key reuse for 24 hours after reservation expiry; after that retention window the abandoned binding may be purged. When product_id is supplied without package_version_id, the server resolves the product’s current package version pin, validates field_values against that resolved version’s input schema, and stores the concrete package version on the Offer. Customers reach the Offer at /i/<short_hash> to start an install. When allowed_emails is non-empty, only those email addresses can use the Offer; when empty or omitted, any authenticated customer can.
Authorizations
workspace API token (sk_akua_...) or OAuth2 JWT. Create tokens at https://akua.dev/developers/api-tokens
Headers
Optional workspace/scope context for the request. Carries a single workspace wire id (ws_…) today. Only needed for broad tokens — a workspace-owned token implies its workspace.
1 - 53"ws_j572abc123def456"
Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used.
1 - 64"create-prod-2026-05-07"
Body
- Option 1
- Option 2
- Option 3
Provide either product_id or package_version_id. Product-backed requests may omit package_version_id; the server resolves the product’s current package version pin at create time, validates field_values against the resolved package version input schema, and stores the resolved package version on the offer.
Product ID for attribution and package-version resolution. Required for channel-backed offers. When package_version_id is omitted, the server uses the product’s current package version pin.
1 - 55Package version ID to pin explicitly at create time. Optional when product_id is supplied; if both are supplied, this value overrides the product’s current package version pin.
1 - 55Verified customer email allowlist. Empty or omitted means any authenticated customer can redeem the offer.
50254Package input pre-fills keyed by input-schema property name. Values are validated against the resolved package version input schema before the offer is created.
Seller-maintained customer context captured when the offer is created. Never returned by customer resolve.
Seller-only internal context for this offer. Never returned by customer resolve.
500Requested customer path for channel policy resolution. This is not settlement authority; the active channel policy decides the final terms.
paid, non_billable_test Requested customer-visible price for channel policy resolution. The active policy validates the request before the offer is created.
Seller-authored offer note. Customer resolve returns it only to authenticated callers authorized through an open allowlist or a verified-email match.
500Unix timestamp in seconds after which the offer can no longer be redeemed. Omit for no explicit expiration.
Maximum number of successful redemptions allowed for this offer. Omit for the default single-use behavior; send null for unlimited redemptions.
x <= 10000Per-redemption order TTL in minutes. Defaults to 120; capped at 1440 (24h).
x <= 1440Legacy advisory billing tier for non-channel offers. Channel-backed offers use commercial_mode and pricing_request.
32