Keystone Developers
Open Keystone
API reference

Console API

Pricing

7 endpoints.

GET/api/v1/admin/pricing/books

List price books (platform admin)

Every book with its current version and the plans pointing at it. The live-subscriber count on each plan is the blast radius of an edit — and the only place a `price_book_id` is discoverable at all.

Parameters

NameInTypeDescription
authorizationheaderstring | null

Responses

200Successful Response
application/jsonSuccessResponse_PriceBooksData_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredPriceBooksData
PriceBooksData fields
FieldTypeDescription
price_booksrequiredPriceBookData[]
PriceBookData[] fields

PriceBookData (not expanded)

metadataResponseMetadata | null
ResponseMetadata fields
FieldTypeDescription
paginationPaginationMetadata | null
PaginationMetadata fields
FieldTypeDescription
limitrequiredinteger
next_cursorstring | null
prev_cursorstring | null
has_morerequiredboolean
has_prevbooleandefault false
total_countinteger | null
status_countsobject | null
object | null fields

Map of string to integer

lifecycle_countsLifecycleCounts | null
LifecycleCounts fields
FieldTypeDescription
leadintegerdefault 0
prospectintegerdefault 0
customerintegerdefault 0
former_customerintegerdefault 0
classification_countsClassificationCounts | null
ClassificationCounts fields
FieldTypeDescription
signalobject
object fields

Nested object (not expanded)

touchobject
object fields

Nested object (not expanded)

stageobject
object fields

Nested object (not expanded)

metaResponseMeta | null
ResponseMeta fields
FieldTypeDescription
totalinteger | null
total_countinteger | null
pageinteger | null
per_pageinteger | null
  • 400Bad request
  • 401Unauthorized
  • 403Forbidden
  • 404Not found
  • 422Validation error
  • 500Internal server error
  • 503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/pricing/books/{book_id}/versions

List a price book's versions (platform admin)

Every version, newest first, with full contents — enough to diff any two, or to republish an old one as the newest, which is what a rollback is.

Parameters

NameInTypeDescription
book_idrequiredpathstring (uuid)
authorizationheaderstring | null

Responses

200Successful Response
application/jsonSuccessResponse_PriceBookVersionsData_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredPriceBookVersionsData
PriceBookVersionsData fields
FieldTypeDescription
versionsrequiredPriceBookVersionData[]
PriceBookVersionData[] fields

PriceBookVersionData (not expanded)

metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | null
ResponseMeta fields

ResponseMeta, expanded above.

  • 400Bad request
  • 401Unauthorized
  • 403Forbidden
  • 404Not found
  • 422Validation error
  • 500Internal server error
  • 503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/pricing/books/{book_id}/versions

Publish a price book version (platform admin)

Publish the next version. Holds authorized after it commits price against the new version; every hold already open keeps the one it was opened under and settles at that one's prices, so an edit can never reprice work a customer has already started.

Parameters

NameInTypeDescription
book_idrequiredpathstring (uuid)
authorizationheaderstring | null

Request bodyrequired

application/jsonCreateVersionBody
FieldTypeDescription
rulesrequiredobject
object fields

Map of string to object

markup_multiplierrequiredstringmin length 1 · max length 64
expected_versionrequiredintegermin 1
reasonrequiredstringmin length 1 · max length 256

Responses

200Successful Response
application/jsonSuccessResponse_PriceBookVersionData_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredPriceBookVersionData
PriceBookVersionData fields
FieldTypeDescription
version_idrequiredstring (uuid)
price_book_idrequiredstring (uuid)
versionrequiredinteger
credit_dollar_valuerequiredstring
markup_multiplierrequiredstring
rulesrequiredobject
object fields

Map of string to object

created_bystring | null
reasonstringdefault ""
created_atstring (date-time) | null
metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | null
ResponseMeta fields

ResponseMeta, expanded above.

  • 400Bad request
  • 401Unauthorized
  • 403Forbidden
  • 404Not found
  • 422Validation error
  • 500Internal server error
  • 503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/pricing/dimensions

List rating dimensions (platform admin)

The quantities the rater understands and the rate-sheet key each is priced under — a code constant served so the editor's field-level validation cannot drift from the code that does the pricing. It says nothing about which sheet is in force.

Parameters

NameInTypeDescription
authorizationheaderstring | null

Responses

200Successful Response
application/jsonSuccessResponse_RatingDimensionsData_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredRatingDimensionsData
RatingDimensionsData fields
FieldTypeDescription
dimensionsrequiredRatingDimensionData[]
RatingDimensionData[] fields

RatingDimensionData (not expanded)

metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | null
ResponseMeta fields

ResponseMeta, expanded above.

  • 400Bad request
  • 401Unauthorized
  • 403Forbidden
  • 404Not found
  • 422Validation error
  • 500Internal server error
  • 503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/pricing/rates

List vendor rate sheets (platform admin)

Newest first, full tables inline — one call serves the list, a row's detail and the editor's starting point (the row payments marks `in_force`).

Parameters

NameInTypeDescription
limitqueryintegerdefault 20
authorizationheaderstring | null

Responses

200Successful Response
application/jsonSuccessResponse_RateSheetsData_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredRateSheetsData
RateSheetsData fields
FieldTypeDescription
rate_sheetsrequiredRateSheetData[]
RateSheetData[] fields

RateSheetData (not expanded)

metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | null
ResponseMeta fields

ResponseMeta, expanded above.

  • 400Bad request
  • 401Unauthorized
  • 403Forbidden
  • 404Not found
  • 422Validation error
  • 500Internal server error
  • 503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/pricing/rates

Schedule a vendor rate sheet (platform admin)

Schedule a complete new sheet for a future instant. It is a draft until then: settle cannot see it, and it can still be edited. Only one may be pending at a time.

Parameters

NameInTypeDescription
authorizationheaderstring | null

Request bodyrequired

application/jsonRateSheetCreateBody
FieldTypeDescription
namerequiredstringmin length 1 · max length 256
ratesrequiredobject
object fields

Map of string to object

Map of string to string

effective_fromrequiredstring (date-time)
reasonrequiredstringmin length 1 · max length 256

Responses

200Successful Response
application/jsonSuccessResponse_RateSheetData_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredRateSheetData
RateSheetData fields
FieldTypeDescription
rates_idrequiredstring (uuid)
namestring | null
ratesrequiredobject
object fields

Map of string to object

Nested object (not expanded)

effective_fromstring (date-time) | null
statusrequiredstring
created_bystring | null
reasonstring | null
created_atstring (date-time) | null
updated_atstring (date-time) | null
metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | null
ResponseMeta fields

ResponseMeta, expanded above.

  • 400Bad request
  • 401Unauthorized
  • 403Forbidden
  • 404Not found
  • 422Validation error
  • 500Internal server error
  • 503Service unavailable

Error bodies: ErrorResponse. See Errors.

PUT/api/v1/admin/pricing/rates/{rates_id}

Edit the scheduled rate sheet (platform admin)

Edit the draft in place: its instant may move later or earlier while it stays in the future, and moving it alone is a real edit. Once the instant passes the sheet is frozen — settled usage rows point at it — and this answers 409 `RATE_SHEET_IN_FORCE`.

Parameters

NameInTypeDescription
rates_idrequiredpathstring (uuid)
authorizationheaderstring | null

Request bodyrequired

application/jsonRateSheetEditBody
FieldTypeDescription
ratesrequiredobject
object fields

Map of string to object

Map of string to string

effective_fromrequiredstring (date-time)
reasonrequiredstringmin length 1 · max length 256

Responses

200Successful Response
application/jsonSuccessResponse_RateSheetData_
FieldTypeDescription
request_idrequiredstring
successtruedefault true
datarequiredRateSheetData
RateSheetData fields

RateSheetData, expanded above.

metadataResponseMetadata | null
ResponseMetadata fields

ResponseMetadata, expanded above.

metaResponseMeta | null
ResponseMeta fields

ResponseMeta, expanded above.

  • 400Bad request
  • 401Unauthorized
  • 403Forbidden
  • 404Not found
  • 422Validation error
  • 500Internal server error
  • 503Service unavailable

Error bodies: ErrorResponse. See Errors.