PT EN

Revisões de preços

URL base: $BUSINESS_API

Listar revisões de preços

Registos

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.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Price revisions and generic before-and-after samples

Permissões tariffs:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

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

Price revisions and generic before-and-after samples

Propor uma revisão de preços

Registos

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.

Corpo application/json

percent_bpinteger · opcional

Basis-point percentage adjustment; 750 means +7.5 percent

fixed_delta_minorinteger · opcional

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

scope_targetstring · opcional · predefinição all

um de all, rates_only, fixed_fees_only

rounding_step_minorinteger · opcional

Round adjusted amounts to the nearest number of minor units

target_idsarray of string · opcional

Explicit active price or tariff IDs; mutually exclusive with category

categorystring · opcional

Target price category; mutually exclusive with target_ids

effective_fromstring (date-time) · obrigatório
reasonstring · obrigatório

Devolve

201 Proposed price revision with generic impact preview

Permissões tariffs:write · Funções: admin, finance, owner

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

Proposed price revision with generic impact preview

Obter uma revisão de preços

Registos

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.

Devolve

200 OK

Permissões tariffs:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

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

OK

Aprovar uma revisão de preços

Registos

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.

Devolve

200 OK

Permissões tariffs:approve · Funções: admin, finance, owner

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

OK

Rejeitar uma revisão de preços

Registos

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.

Devolve

200 OK

Permissões tariffs:approve · Funções: admin, finance, owner

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

OK