customers

Set customer-unit cap (by external customer id)

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.

put/customers/external/{externalId}/customer-units/{externalCustomerUnitId}/cap

Request

  • Base URL: https://api.agentpaid.io/api/v2
  • URL: https://api.agentpaid.io/api/v2/customers/external/{externalId}/customer-units/{externalCustomerUnitId}/cap
  • Auth: HTTP bearer

Path parameters

externalIdstring required

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

externalCustomerUnitIdstring required

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

Request body

amountnumber double required

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

frequency'MONTHLY'

Monthly UTC periods, with boundaries defined by schedule.

scheduleCustomerUnitCapScheduleInput

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.

creditsCurrencyIdstring 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.

effectiveFromstring date-time

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 required

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

customerIdstring required

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

creditsCurrencyIdstring uuid required

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

changedboolean required

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

Changes

No recorded changes to this operation across all 1 revision of this API.