# GET & PATCH /v1/organizations/:orgId/credit-config (/docs/api/reference/organizations/credit-config)



A child organization's spend governance lives in its **credit config** — the monthly cap and the auto-refill rule. You read and set it with your parent (`org:admin`) key; a child key never sees or changes its own config. All amounts are in **credits** (not cents), and each is nullable: `null` means "no cap" / "no auto-refill".

<Endpoint method="GET" path="/v1/organizations/{orgId}/credit-config" auth="Bearer" scope="org:admin" phase="1" />

Returns the child's current config plus its live `balance` and `available`, so a single call answers "what are this customer's limits, and where's their wallet?".

<Parameters
  title="Path"
  rows="[
  { name: 'orgId', type: 'string (org_…)', required: true, description: 'The child organization. Must be a direct child of your org — otherwise 404.' },
]"
/>

## GET example [#get-example]

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

<Response status="200" description="OK">
  ```json
  {
    "organizationId": "org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80",
    "config": {
      "monthlyCreditCap": 5000,
      "refillThreshold": 1000,
      "refillAmount": 2000,
      "autoRefillEnabled": true
    },
    "balance": 5000,
    "available": 4880
  }
  ```
</Response>

<Endpoint method="PATCH" path="/v1/organizations/{orgId}/credit-config" auth="Bearer" scope="org:admin" phase="1" />

Partial update: send only the fields you're changing. A number **sets**, `null` **clears**, an omitted field is **left unchanged**. Returns the merged config with the same shape as GET.

<Parameters
  title="Body"
  rows="[
  { name: 'monthlyCreditCap', type: 'integer ≥ 0 | null', required: false, description: 'Per-billing-period spend ceiling, in credits. `null` removes the cap.' },
  { name: 'refillThreshold', type: 'integer ≥ 0 | null', required: false, description: 'When the child\'s `available` drops below this, auto-refill fires. Paired with `refillAmount`.' },
  { name: 'refillAmount', type: 'integer > 0 | null', required: false, description: 'Credits moved from the parent on each auto-refill. Paired with `refillThreshold`.' },
]"
/>

<Parameters
  title="Headers"
  rows="[
  { name: 'Idempotency-Key', type: 'string (UUID)', required: false, description: 'Honored — a replay returns the same result without re-applying the patch.' },
]"
/>

<Callout type="info">
  **Auto-refill is both-or-neither.** After your patch, `refillThreshold` and `refillAmount` must be *both* set (to enable) or *both* null (to disable). A patch that would leave exactly one set is rejected with `422` (`details.code: REFILL_REQUIRES_THRESHOLD_AND_AMOUNT`). Setting one side while the other is already set in the stored config is fine — the rule is checked against the merged result. `autoRefillEnabled` is derived (read-only): it's `true` exactly when both are set.
</Callout>

## PATCH example [#patch-example]

```bash
# Cap this customer at 5,000 credits/month and auto-refill 2,000 when they drop below 1,000.
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
  }'
```

<Response status="200" description="OK — config updated, current balances echoed">
  ```json
  {
    "organizationId": "org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80",
    "config": {
      "monthlyCreditCap": 5000,
      "refillThreshold": 1000,
      "refillAmount": 2000,
      "autoRefillEnabled": true
    },
    "balance": 5000,
    "available": 4880
  }
  ```
</Response>

To turn auto-refill off, clear both refill fields: `{ "refillThreshold": null, "refillAmount": null }`. To remove the cap, `{ "monthlyCreditCap": null }`. An empty body `{}` is a no-op that echoes the current config.

### Field notes [#field-notes]

* All three knobs are **credits**, never cents.
* `autoRefillEnabled` is computed from the two refill fields — you don't (and can't) set it directly.
* The same `config` object rides along on the [`GET /v1/organizations/:orgId`](/docs/api/reference/organizations/get-organization) summary as `summary.creditConfig`.
* A **never-funded** child (no wallet row yet) returns an all-null `config` with `autoRefillEnabled: false` and `balance`/`available` of `0` — `GET` never 404s on this. A `PATCH` on such a child **creates** its config row.
* What a child *experiences* from these settings is covered in the [Credits concept](/docs/api/concepts/credits#credit-config--caps-and-auto-refill): an over-cap reservation gets `402 BILLING_EXHAUSTED` with `details.reason: "cap"`; auto-refill tops the child up transparently from the parent.

## Errors [#errors]

| Status | Code              | When                                                                                                                                  |
| ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| 403    | `FORBIDDEN_SCOPE` | Key lacks `org:admin`.                                                                                                                |
| 404    | `NOT_FOUND`       | `:orgId` is not a direct child of your org (anti-enumeration).                                                                        |
| 409    | `CONFLICT`        | The child is **archived** — a terminal org's config can't be changed.                                                                 |
| 422    | `VALIDATION`      | A field is out of bounds, or the patch breaks the both-or-neither refill rule (`details.code: REFILL_REQUIRES_THRESHOLD_AND_AMOUNT`). |
| 503    | `KILL_SWITCH`     | Your key or org is suspended.                                                                                                         |

## See also [#see-also]

* [Credits concept → caps and auto-refill](/docs/api/concepts/credits#credit-config--caps-and-auto-refill) — what these settings do.
* [Allocate credits](/docs/api/reference/organizations/credits/allocate) — manual parent→child funding.
* [Child wallet](/docs/api/reference/organizations/credits/get-credits) — read `balance` / `available`.