GET & PATCH /v1/organizations/:orgId/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".

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?".

GET example

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

{
  "organizationId": "org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80",
  "config": {
    "monthlyCreditCap": 5000,
    "refillThreshold": 1000,
    "refillAmount": 2000,
    "autoRefillEnabled": true
  },
  "balance": 5000,
  "available": 4880
}

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.

PATCH example

# 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
  }'

{
  "organizationId": "org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80",
  "config": {
    "monthlyCreditCap": 5000,
    "refillThreshold": 1000,
    "refillAmount": 2000,
    "autoRefillEnabled": true
  },
  "balance": 5000,
  "available": 4880
}

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

• 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 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: an over-cap reservation gets 402 BILLING_EXHAUSTED with details.reason: "cap"; auto-refill tops the child up transparently from the parent.

Errors

See also

• Credits concept → caps and auto-refill — what these settings do.
• Allocate credits — manual parent→child funding.
• Child wallet — read balance / available.