Set customer-unit cap | Paid

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

{
  "externalCustomerUnitId": "tenant-a",
  "customerId": "cus_abc123",
  "creditsCurrencyId": "7f4f5d4c-55e9-4d5b-a3e7-c9eb3d2d01bf",
  "policy": {
    "amount": 10000,
    "frequency": "MONTHLY",
    "effectiveFrom": "2024-01-15T09:30:00Z",
    "effectiveUntil": "null",
    "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 by recording a new cap version; earlier versions are kept and never modified, and the newest version wins where they overlap. The new version applies from effectiveFrom (default now) and its periods are anchored on that day of the month. Select the currency with creditsCurrencyId in the body; it may be omitted only when the organization has exactly one credits currency. A cap on the customer’s root unit is the customer-wide cap. 404 when the customer or the unit does not exist. 409 for customers on seat-based billing. Use the value returned as customer.id, for example cus_abc123; if you have your own customer ID, use the /api/v2/customers/external/{externalId}/… twin.

Sets the cap on this customer unit for one credits currency by recording a new cap version; earlier versions are kept and never modified, and the newest version wins where they overlap. The new version applies from `effectiveFrom` (default now) and its periods are anchored on that day of the month. Select the currency with `creditsCurrencyId` in the body; it may be omitted only when the organization has exactly one credits currency. A cap on the customer's root unit is the customer-wide cap. `404` when the customer or the unit does not exist. `409` for customers on seat-based billing. Use the value returned as `customer.id`, for example `cus_abc123`; if you have your own customer ID, use the `/api/v2/customers/external/{externalId}/…` twin.

Authentication

AuthorizationBearer

API Key authentication using Bearer token

Path parameters

idstringRequiredformat: "^cus_.+"

Paid customer display id

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

Period length. Periods start on the day-of-month of effectiveFrom (UTC), clamped in shorter months.

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 and the anchor day for its periods (UTC). Defaults to now when omitted. Spend earlier in the period that contains it still counts toward the cap.

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.

policyobject

The cap version just recorded. It starts applying at its effectiveFrom, which may be in the future, and is open (effectiveUntil is null).

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