Skip to main content
POST
Create offer

Authorizations

Authorization
string
header
required

workspace API token (sk_akua_...) or OAuth2 JWT. Create tokens at https://akua.dev/developers/api-tokens

Headers

akua-context
string

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.

Required string length: 1 - 53
Example:

"ws_j572abc123def456"

Body

application/json

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
string
required

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.

Required string length: 1 - 55
package_version_id
string

Package 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.

Required string length: 1 - 55
allowed_emails
string<email>[]

Verified customer email allowlist. Empty or omitted means any authenticated customer can redeem the offer.

Maximum array length: 50
Maximum string length: 254
field_values
object

Package input pre-fills keyed by input-schema property name. Values are validated against the resolved package version input schema before the offer is created.

tier
string

Legacy advisory billing tier for non-channel offers. Do not send this with offer_channel_id; channel-backed offers use commercial_mode and pricing_request.

Maximum string length: 32
offer_channel_id
string

Offer Channel whose active policy resolves approval, checkout, support, and pricing terms. Requires product_id.

Required string length: 1 - 54
commercial_mode
enum<string>

Requested customer path for channel policy resolution. This is not settlement authority; the active channel policy decides the final terms.

Available options:
paid,
non_billable_test
pricing_request
object

Requested customer-visible price for channel policy resolution. The active policy validates the request before the offer is created.

notes
string

Seller-private note for operators reviewing or supporting the offer. Not shown to the customer.

Maximum string length: 500
expires_at
integer

Unix timestamp in seconds after which the offer can no longer be redeemed. Omit for no explicit expiration.

max_uses
integer

Maximum number of successful redemptions allowed for this offer. Omit for the default single-use behavior.

Required range: x <= 10000
order_ttl_minutes
integer

Per-redemption order TTL in minutes. Defaults to 120; capped at 1440 (24h).

Required range: x <= 1440

Response

Offer created

id
string
required

Offer ID

Required string length: 1 - 56
short_hash
string
required