Skip to main content
POST
/
api
/
credits
/
provision
Auto-attach the free plan to a new customer
curl --request POST \
  --url https://app.puffle.ai/api/credits/provision \
  --header 'Authorization: Bearer <token>'
{ "provisioned": true }

​
Overview

Idempotently attaches the Autumn free plan — 1,000 one-time credits — to the authenticated customer. Server-side, no checkout UI, no billing info required (the free tier is, well, free). This endpoint exists so new workspaces have a credit balance before they hit the first gated endpoint. It’s normally called automatically on first sign-in; calling it again is a safe no-op that returns { provisioned: false, reason: "already_has_plan" }.

​
The credit system

Puffle gates paid integrations (enrichment, deep research, LLM generation) behind a credit balance. Plans top up; actions deduct. The free plan grants 1,000 one-time credits — enough to sample every journey but not to run a production campaign. Paid plans reset monthly. For agents, the pre-flight pattern is:
  1. Read per-action prices via getCreditsConfig.
  2. Before any billable call, run createCreditPreview to confirm the balance covers the batch.
  3. If sufficient: false, stop and report the exact shortfall to the human.
See the credit system in the Agent Playbook for the full pattern.

​
AI agent notes

Agents rarely call this directly. Provisioning runs behind the scenes on first sign-in. Only call it explicitly if a freshly-created workspace is returning 402 on billable endpoints when the balance should be 1,000 — that means the initial provision didn’t land, and this is the retry.Idempotent. Safe to call repeatedly. The second call returns { provisioned: false, reason: "already_has_plan" } — that’s not an error, that’s confirmation the workspace already has credit access.This does not purchase credits. It only attaches the free plan. Upgrading to Pro or Enterprise goes through the Autumn billing portal, not the API.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Response

Plan attached (provisioned: true) or already present (provisioned: false).

Idempotent attach — calling this twice is safe, the second call returns { provisioned: false, reason: "already_has_plan" }.

​
provisioned
boolean
required

true when the free plan was just attached. false when the caller already had a plan with credit access — the call is a no-op.

​
reason
string

Present only when provisioned: false. Current value: already_has_plan.