Get customer-unit cap

GET

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

GET

/api/v2/customers/:id/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.getCustomerUnitCap({
        id: "cus_abc123",
        externalCustomerUnitId: "tenant-a",
    });
}
main();

{
  "externalCustomerUnitId": "tenant-a",
  "customerId": "cus_abc123",
  "creditsCurrencyId": "7f4f5d4c-55e9-4d5b-a3e7-c9eb3d2d01bf",
  "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
  }
}

Returns the cap in force on this customer unit for one credits currency, with usage in the current period when available. Select the currency with creditsCurrencyId; it may be omitted only when the organization has exactly one credits currency, which is then used and echoed back. 404 when the customer or the unit does not exist, or the unit has no cap in force for that currency. The usage figures are advisory: other spend may land between this read and the next burn. 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.

Query parameters

creditsCurrencyIdstringOptionalformat: "uuid"

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

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 this response is about: the requested creditsCurrencyId, or the organization's only credits currency when it was omitted.

policyobject

The cap version in force now.

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

500

Internal Server Error