Price revisions

Base URL: $BUSINESS_API

List proposed and applied price revisions

Logs

GET /price-revisions

Returns one cursor-paginated page (limit, after) of the tenant's price revisions, filtered by the optional status query parameter (proposed, applied or rejected). Requires the tariffs:read permission.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Price revisions and generic before-and-after samples

Permissions tariffs:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/price-revisions" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Price revisions and generic before-and-after samples

Preview and propose an effective-dated price revision

Logs

POST /price-revisions

Proposes a bulk price change and stores it as proposed, with a preview of every affected price, so another person can review it before it takes effect. The body needs at least one of percent_bp (-5000 to 50000) and fixed_delta_minor, an effective_from in the future, and a reason. Optional fields are scope_target (all, rates only or fixed fees only), rounding_step_minor, and either target_ids or category, not both. Returns 400 when no active price matches, or when a listed target is inactive or outside the category. Requires the tariffs:write permission and records an audit entry.

Body application/json

percent_bpinteger · optional

Basis-point percentage adjustment; 750 means +7.5 percent

fixed_delta_minorinteger · optional

Fixed adjustment in currency minor units; may be combined with percent_bp

scope_targetstring · optional · default all

one of all, rates_only, fixed_fees_only

rounding_step_minorinteger · optional

Round adjusted amounts to the nearest number of minor units

target_idsarray of string · optional

Explicit active price or tariff IDs; mutually exclusive with category

categorystring · optional

Target price category; mutually exclusive with target_ids

effective_fromstring (date-time) · required
reasonstring · required

Returns

201 Proposed price revision with generic impact preview

Permissions tariffs:write · Roles: admin, finance, owner

curl -X POST "$BUSINESS_API/price-revisions" \
  -H "Authorization: Bearer sk_test_..."
Response 201

Proposed price revision with generic impact preview

Get a price revision and its impact preview

Logs

GET /price-revisions/{id}

Returns one price revision with its adjustment, targets, effective date, preview lines, status and, once decided, who decided, when and the IDs of the prices it created. Requires the tariffs:read permission, and returns 404 when the revision does not exist.

Returns

200 OK

Permissions tariffs:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/price-revisions/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200

OK

Create effective-dated price versions

Logs

POST /price-revisions/{id}/approve

Create effective-dated price versions; the proposer cannot approve

Applies a proposed revision: it creates new price versions effective from the revision's date, marks the revision applied and records an audit entry. The optional body carries a decision reason. The proposer cannot approve their own revision (403). A revision that is no longer proposed, or whose effective date has passed, returns 409. A 409 is also returned when the affected prices changed since the preview, and then a new revision must be proposed. Requires the tariffs:approve permission.

Returns

200 OK

Permissions tariffs:approve · Roles: admin, finance, owner

curl -X POST "$BUSINESS_API/price-revisions/{id}/approve" \
  -H "Authorization: Bearer sk_test_..."
Response 200

OK

Reject a proposed price revision

Logs

POST /price-revisions/{id}/reject

Marks a proposed revision as rejected without changing any price, storing who decided, when and the optional reason from the body. A revision that is no longer proposed returns 409. Requires the tariffs:approve permission and records an audit entry.

Returns

200 OK

Permissions tariffs:approve · Roles: admin, finance, owner

curl -X POST "$BUSINESS_API/price-revisions/{id}/reject" \
  -H "Authorization: Bearer sk_test_..."
Response 200

OK