# Provision and fund a customer (/docs/api/guides/provision-and-fund-a-customer)



This is the linear quickstart: run these calls in order and you'll have a customer modeled as an isolated [child organization](/docs/api/concepts/organizations) — funded, capped, with its own API key, and feeding events into your webhook. Every call uses your parent (`org:admin`) key. For the per-operation reference (suspend/resume, offboard, working inside a child via the header), see [Manage customers with sub-organizations](/docs/api/guides/manage-customers-with-sub-organizations).

The running example onboards **Acme Coffee**. You'll need a parent key with the [`org:admin`](/docs/api/concepts/api-keys#scopes) scope. Send a fresh `Idempotency-Key` on every call.

<Steps>
  <Step>
    ## 1 · Create the child org [#1--create-the-child-org]

    ```bash
    curl -X POST https://api.layers.com/v1/organizations \
      -H "Authorization: Bearer $PARENT_KEY" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{ "name": "Acme Coffee", "metadata": { "externalId": "acme-coffee" } }'
    ```

    Keep `id` from the response — `org_d4e5f6a7-…`. It's the `:orgId` in every call below.
  </Step>

  <Step>
    ## 2 · Mint the customer's API key [#2--mint-the-customers-api-key]

    ```bash
    curl -X POST https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80/api-keys \
      -H "Authorization: Bearer $PARENT_KEY" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{ "name": "acme-integration", "scopes": ["content:read", "content:write"] }'
    ```

    Grab `secret` — it's shown **once**. Scopes must be a subset of your parent key's; `org:admin` is never delegable.
  </Step>

  <Step>
    ## 3 · Allocate credits [#3--allocate-credits]

    ```bash
    curl -X POST https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80/credits/allocate \
      -H "Authorization: Bearer $PARENT_KEY" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{ "credits": 5000 }'
    ```

    Moves 5,000 credits from your parent wallet into Acme's. The response returns the transfer `id` (`txn_`-prefixed — your reconciliation handle) alongside the child's post-allocation `balance` and `available`. The `Idempotency-Key` header is required on this route.
  </Step>

  <Step>
    ## 4 · Set the cap + auto-refill [#4--set-the-cap--auto-refill]

    ```bash
    curl -X PATCH https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80/credit-config \
      -H "Authorization: Bearer $PARENT_KEY" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{ "monthlyCreditCap": 5000, "refillThreshold": 1000, "refillAmount": 2000 }'
    ```

    Caps Acme at 5,000 credits/month and tops them up 2,000 whenever `available` drops below 1,000. Response confirms `config.autoRefillEnabled: true`. (Refill is both-or-neither — set both refill fields or neither.)
  </Step>

  <Step>
    ## 5 · Subscribe the firehose [#5--subscribe-the-firehose]

    ```bash
    curl -X POST https://api.layers.com/v1/webhook-endpoints \
      -H "Authorization: Bearer $PARENT_KEY" \
      -H "Idempotency-Key: $(uuidgen)" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://quinns-crm.example.com/layers/webhooks",
        "events": ["content.generated", "post.published"],
        "scope": "all_children"
      }'
    ```

    One endpoint, every child's events. Store the returned `signingSecret` (shown once). Each delivery's `data.organizationId` tells you which customer it's for.
  </Step>

  <Step>
    ## 6 · Verify [#6--verify]

    ```bash
    curl https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80 \
      -H "Authorization: Bearer $PARENT_KEY"
    ```

    The `summary` confirms the whole setup in one read: `balance` / `available` (funded), and `creditConfig` (`monthlyCreditCap: 5000`, `autoRefillEnabled: true`). Acme is now a funded, capped, observable customer authenticating with its own key.
  </Step>
</Steps>

## What you have now [#what-you-have-now]

* An isolated child org (`org_d4e5f6a7-…`) — its projects, wallet, and audit trail are invisible to your other customers.
* A dedicated child key Acme's integration uses directly (never your parent key).
* 5,000 credits allocated, a 5,000/month cap, and 2,000 auto-refill below 1,000.
* One parent webhook endpoint receiving Acme's events, attributed by `data.organizationId`.

## Next [#next]

* [Manage customers with sub-organizations](/docs/api/guides/manage-customers-with-sub-organizations) — suspend/resume, offboard (archive reclaims unspent credits), and working inside a child with the `X-Layers-Organization` header.
* [Credits concept](/docs/api/concepts/credits) — balance vs available, allocation, caps, and auto-refill in depth.
* [Migrate existing projects](/docs/api/reference/organizations/migrate) — already have flat projects? Move them under child orgs in one call.