Set customer-unit cap (by external customer id)

PUT

https://api.agentpaid.io/api/v2/customers/external/:externalId/customer-units/:externalCustomerUnitId/cap

PUT

/api/v2/customers/external/:externalId/customer-units/:externalCustomerUnitId/cap

import { PaidClient } from "@paid-ai/paid-node";
async function main() {
    const client = new PaidClient({
        token: "YOUR_TOKEN_HERE",
    });
    await client.customers.setCustomerUnitCapByExternalId({
        externalId: "customer_123",
        externalCustomerUnitId: "tenant-a",
        body: {
            amount: 10000,
        },
    });
}
main();

{
  "externalCustomerUnitId": "tenant-a",
  "customerId": "cus_abc123",
  "creditsCurrencyId": "7f4f5d4c-55e9-4d5b-a3e7-c9eb3d2d01bf",
  "changed": true,
  "policy": {
    "amount": 10000,
    "frequency": "MONTHLY",
    "schedule": {
      "type": "ANCHORED",
      "anchorDay": 15
    },
    "effectiveFrom": "2024-01-15T09:30:00Z",
    "effectiveUntil": "2024-01-15T09:30:00Z",
    "createdAt": "2024-01-15T09:30:00Z",
    "source": "api"
  },
  "currentPeriod": {
    "window": {
      "start": "2024-01-15T09:30:00Z",
      "end": "2024-01-15T09:30:00Z"
    },
    "used": 1.1,
    "remaining": 1.1
  }
}

Sets the cap on this customer unit for one credits currency. Returns changed: false without creating a version when the effective timeline is unchanged; otherwise records a new version, preserving earlier rows. The newest version wins where they overlap. effectiveFrom controls applicability; schedule defines monthly UTC boundaries independently. Omit schedule to inherit the version covering effectiveFrom, or use the creation-time UTC day if none applies. Select the currency with creditsCurrencyId in the body; it may be omitted only when the organization has exactly one credits currency. A cap covers the unit and every unit beneath it, so a cap on the customer’s root unit covers every unit of that customer; spend from a signal that names no unit counts toward no cap. 404 when the customer or the unit does not exist. 409 for customers on seat-based billing, a deleted unit (CUSTOMER_UNIT_DELETED) or a draft (CUSTOMER_UNIT_DRAFT). Addresses the customer by your external customer id.

Authentication

AuthorizationBearer

API Key authentication using Bearer token

Path parameters

externalIdstringRequired>=1 character

Customer ID from your system, stored on Paid as the customer's externalId.

externalCustomerUnitIdstringRequired>=1 character

Your own id for the unit (its externalId), unique within this customer.

Request

Body

amountdoubleRequired

The cap, in credits of the currency, per period. Must be positive.

frequencyenumOptionalDefaults to MONTHLY

Monthly UTC periods, with boundaries defined by schedule.

Allowed values:

scheduleobjectOptional

Omit to inherit the schedule in force at effectiveFrom. If none applies, use the creation-time UTC day. An explicit change counts spend from the new schedule’s ordinary period start, including earlier spend.

creditsCurrencyIdstringOptionalformat: "uuid"

The credits currency to cap. Omit it only when the organization has exactly one credits currency, which is then used; otherwise it is required.

effectiveFromdatetimeOptional

ISO 8601 timestamp. When the cap starts applying, independently of its schedule. Defaults to now. Spend earlier in the schedule’s current period still counts.

Response

200

externalCustomerUnitIdstring>=1 character

Your own id for the unit (its externalId), the identifier the unit and cap routes take.

customerIdstringformat: "^cus_.+"

The Paid display id of the customer the unit belongs to.

creditsCurrencyIdstringformat: "uuid"

The credits currency the cap was set on: the requested creditsCurrencyId, or the organization's only credits currency when it was omitted.

changedboolean

Whether this save created a policy version. False when the effective timeline was already identical.

policyobject

The new version, or the existing version covering the requested effectiveFrom when changed is false. New versions are open; an existing version may have a finite end.

currentPeriodobject

Usage in the current period, when the returned version is in force now and usage is available; otherwise null.

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

500

Internal Server Error