> ## Documentation Index > Fetch the complete documentation index at: https://docs.akua.dev/llms.txt > Use this file to discover all available pages before exploring further. # 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/` 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. ## OpenAPI ````yaml /openapi-public.json post /offers openapi: 3.1.0 info: title: Akua API version: 1.0.0 description: >- Public API for managing Akua workspaces, clusters, products, and installs. Authenticate with a workspace API token via the `Authorization: Bearer sk_akua_...` header. A workspace-owned token implies its workspace. Broad tokens select the active workspace via the optional `Akua-Context` header. contact: name: Akua API support email: support@akua.dev url: https://akua.dev/docs servers: - url: https://api.akua.dev/v1 description: Production security: [] tags: - name: Auth description: Authentication and token management. - name: Agent events description: Persisted agent transcripts and response recovery. - name: Custom domains description: Workspace custom domains and routing targets. - name: Cloudflare description: Cloudflare account credentials and gateway control. - name: Clusters description: Kubernetes clusters and cluster access operations. - name: ComputeConfigs description: Workspace compute provider configurations. - name: Entitlements description: Effective workspace capabilities and limits. - name: Dashboards description: Dashboard and widget resources. - name: Installs description: Installation and render operations. - name: Machines description: Compute machines and lifecycle events. - name: Notifications description: User notification state. - name: Offer Channels description: Private offer channels and policy versions. - name: Offers description: Marketplace offers and redemption tracking. - name: Operations description: Long-running operation status and controls. - name: Order Drafts description: Draft checkout orders and checkout sessions. - name: Organizations description: Organizations, memberships, and managed workspaces. - name: Packages description: Software packages, versions, and input schemas. - name: Products description: Marketplace product catalog resources. - name: Preview hostnames description: Install preview hostnames and routing state. - name: Quotas description: Workspace quota limits and usage. - name: Regions description: Available deployment regions. - name: Registry description: Container registry credentials and repositories. - name: Repository change requests description: Fork-backed repository change reviews and lifecycle actions. - name: Repositories description: Source repositories available to the workspace. - name: Secrets description: Workspace secrets and secret versions. - name: Snippets description: Reusable snippets and snippet runs. - name: Workspace subdomains description: Workspace subdomain identity. - name: Workspaces description: Workspace resources, members, and billing state. paths: /offers: post: tags: - Offers summary: Create offer description: >- 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/` 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. operationId: offers.create parameters: - name: akua-context in: header schema: type: string minLength: 1 maxLength: 53 description: >- 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. examples: - ws_j572abc123def456 required: false - name: idempotency-key in: header schema: type: string minLength: 1 maxLength: 64 description: >- Optional caller-supplied idempotency key. Any non-empty key up to 64 characters is accepted. Endpoint-specific documentation describes how the key is used. examples: - create-prod-2026-05-07 required: false requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateOfferBody' required: true responses: '201': description: Offer created content: application/json: schema: $ref: '#/components/schemas/OfferCreated' '400': description: The request is malformed. content: application/json: schema: $ref: '#/components/schemas/ApiBadRequest' '401': description: Missing, invalid or expired credential. content: application/json: schema: $ref: '#/components/schemas/ApiUnauthorized' '403': description: The credential may not act in this workspace. content: application/json: schema: $ref: '#/components/schemas/ApiForbidden' '409': description: >- The request conflicts with existing resource state or immutable intent. content: application/json: schema: $ref: '#/components/schemas/ApiConflict' '422': description: The request is well-formed but cannot be processed. content: application/json: schema: $ref: '#/components/schemas/ApiUnprocessable' security: - BearerAuth: [] components: schemas: CreateOfferBody: oneOf: - type: object properties: product_id: type: string description: >- 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. minLength: 1 maxLength: 55 package_version_id: type: string description: >- 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. minLength: 1 maxLength: 55 allowed_emails: type: array items: type: string format: email maxLength: 254 description: >- Verified customer email allowlist. Empty or omitted means any authenticated customer can redeem the offer. maxItems: 50 field_values: type: object additionalProperties: type: object properties: value: description: Pre-fill value for this schema property locked: type: boolean description: >- When true the customer cannot override; submit ignores client value required: - value - locked additionalProperties: false description: >- 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. customer: $ref: '#/components/schemas/OfferCustomerSnapshot' internal_note: type: string description: >- Seller-only internal context for this offer. Never returned by customer resolve. maxLength: 500 commercial_mode: allOf: - $ref: '#/components/schemas/CommercialMode' - description: >- Requested customer path for channel policy resolution. This is not settlement authority; the active channel policy decides the final terms. pricing_request: $ref: '#/components/schemas/OfferPricingRequest' notes: type: string description: >- Seller-authored offer note. Customer resolve returns it only to authenticated callers authorized through an open allowlist or a verified-email match. maxLength: 500 expires_at: type: integer description: >- Unix timestamp in seconds after which the offer can no longer be redeemed. Omit for no explicit expiration. exclusiveMinimum: 0 max_uses: anyOf: - type: integer maximum: 10000 exclusiveMinimum: 0 - type: 'null' description: >- Maximum number of successful redemptions allowed for this offer. Omit for the default single-use behavior; send null for unlimited redemptions. order_ttl_minutes: type: integer description: >- Per-redemption order TTL in minutes. Defaults to 120; capped at 1440 (24h). maximum: 1440 exclusiveMinimum: 0 tier: type: string description: >- Legacy advisory billing tier for non-channel offers. Channel-backed offers use `commercial_mode` and `pricing_request`. maxLength: 32 required: - product_id additionalProperties: false - type: object properties: package_version_id: type: string description: >- 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. minLength: 1 maxLength: 55 allowed_emails: type: array items: type: string format: email maxLength: 254 description: >- Verified customer email allowlist. Empty or omitted means any authenticated customer can redeem the offer. maxItems: 50 field_values: type: object additionalProperties: type: object properties: value: description: Pre-fill value for this schema property locked: type: boolean description: >- When true the customer cannot override; submit ignores client value required: - value - locked additionalProperties: false description: >- 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. customer: $ref: '#/components/schemas/OfferCustomerSnapshot' internal_note: type: string description: >- Seller-only internal context for this offer. Never returned by customer resolve. maxLength: 500 commercial_mode: allOf: - $ref: '#/components/schemas/CommercialMode' - description: >- Requested customer path for channel policy resolution. This is not settlement authority; the active channel policy decides the final terms. pricing_request: $ref: '#/components/schemas/OfferPricingRequest' notes: type: string description: >- Seller-authored offer note. Customer resolve returns it only to authenticated callers authorized through an open allowlist or a verified-email match. maxLength: 500 expires_at: type: integer description: >- Unix timestamp in seconds after which the offer can no longer be redeemed. Omit for no explicit expiration. exclusiveMinimum: 0 max_uses: anyOf: - type: integer maximum: 10000 exclusiveMinimum: 0 - type: 'null' description: >- Maximum number of successful redemptions allowed for this offer. Omit for the default single-use behavior; send null for unlimited redemptions. order_ttl_minutes: type: integer description: >- Per-redemption order TTL in minutes. Defaults to 120; capped at 1440 (24h). maximum: 1440 exclusiveMinimum: 0 tier: type: string description: >- Legacy advisory billing tier for non-channel offers. Channel-backed offers use `commercial_mode` and `pricing_request`. maxLength: 32 required: - package_version_id additionalProperties: false - type: object properties: product_id: type: string description: >- 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. minLength: 1 maxLength: 55 package_version_id: type: string description: >- 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. minLength: 1 maxLength: 55 allowed_emails: type: array items: type: string format: email maxLength: 254 description: >- Verified customer email allowlist. Empty or omitted means any authenticated customer can redeem the offer. maxItems: 50 field_values: type: object additionalProperties: type: object properties: value: description: Pre-fill value for this schema property locked: type: boolean description: >- When true the customer cannot override; submit ignores client value required: - value - locked additionalProperties: false description: >- 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. customer: $ref: '#/components/schemas/OfferCustomerSnapshot' internal_note: type: string description: >- Seller-only internal context for this offer. Never returned by customer resolve. maxLength: 500 commercial_mode: allOf: - $ref: '#/components/schemas/CommercialMode' - description: >- Requested customer path for channel policy resolution. This is not settlement authority; the active channel policy decides the final terms. pricing_request: $ref: '#/components/schemas/OfferPricingRequest' notes: type: string description: >- Seller-authored offer note. Customer resolve returns it only to authenticated callers authorized through an open allowlist or a verified-email match. maxLength: 500 expires_at: type: integer description: >- Unix timestamp in seconds after which the offer can no longer be redeemed. Omit for no explicit expiration. exclusiveMinimum: 0 max_uses: anyOf: - type: integer maximum: 10000 exclusiveMinimum: 0 - type: 'null' description: >- Maximum number of successful redemptions allowed for this offer. Omit for the default single-use behavior; send null for unlimited redemptions. order_ttl_minutes: type: integer description: >- Per-redemption order TTL in minutes. Defaults to 120; capped at 1440 (24h). maximum: 1440 exclusiveMinimum: 0 offer_channel_id: type: string description: >- Offer Channel whose active policy resolves approval, checkout, support, and pricing terms. minLength: 1 maxLength: 54 required: - product_id - offer_channel_id additionalProperties: false description: >- 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. x-platform-exact-union: true OfferCreated: type: object properties: id: type: string description: Offer ID minLength: 1 maxLength: 56 short_hash: type: string required: - id - short_hash additionalProperties: false ApiBadRequest: type: object properties: _tag: type: string enum: - Validation success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiUnauthorized: type: object properties: _tag: type: string enum: - Unauthorized success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiForbidden: type: object properties: _tag: type: string enum: - Forbidden success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiConflict: type: object properties: _tag: type: string enum: - Conflict success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false ApiUnprocessable: type: object properties: _tag: type: string enum: - Unprocessable success: type: boolean enum: - false errors: type: array prefixItems: - $ref: '#/components/schemas/ApiErrorEntry' minItems: 1 items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object additionalProperties: false required: - _tag - success - errors - result additionalProperties: false OfferCustomerSnapshot: type: object properties: display_name: type: string minLength: 1 maxLength: 200 external_id: type: string minLength: 1 maxLength: 200 required: - display_name additionalProperties: false description: >- Seller-maintained customer context captured when the offer is created. Never returned by customer resolve. CommercialMode: type: string enum: - paid - non_billable_test description: >- Customer commercial path requested for an offer. `paid` routes through checkout when policy requires it; `non_billable_test` creates a non-billable test offer when policy allows it. OfferPricingRequest: type: object properties: currency: type: string enum: - eur - usd description: ISO currency code for the requested price. examples: - eur unit_amount: type: integer description: >- Requested price in the smallest currency unit, for example cents for EUR or USD. minimum: 0 maximum: 100000000 interval: allOf: - $ref: '#/components/schemas/PricingInterval' - description: Billing interval for the requested price. required: - currency - unit_amount - interval additionalProperties: false description: >- Requested customer-visible price for channel policy resolution. The active policy validates the request before the offer is created. ApiErrorEntry: type: object properties: code: type: integer description: Machine-readable error code examples: - 7002 message: type: string description: Human-readable error message examples: - Resource not found path: type: array items: type: string description: Field path that caused the error, when applicable examples: - - body - name metadata: type: object additionalProperties: type: string required: - code - message additionalProperties: false PricingInterval: type: string enum: - month - year securitySchemes: BearerAuth: description: >- workspace API token (sk_akua_...) or OAuth2 JWT. Create tokens at https://akua.dev/developers/api-tokens type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.