Services API
POST/api/v1/services
Product availabilityAlgaPSA

Create service

Creates a new service catalog entry. Resolve custom_service_type_id with GET /api/v1/service-types and category_id with GET /api/v1/categories/service before calling this endpoint. Use this endpoint for fixed, hourly, or usage-based service offerings. Supply prices (rates in integer minor units) to set the displayed prices; prices[0] is primary and is mirrored into default_rate, so default_rate may then be omitted. scheduled_prices sets future-dated prices.

RBAC · service

Request body

Content type: application/json

service_namestringRequired
min length 1 · max length 255
custom_service_type_idstring <uuid>Required
billing_methodstringRequired
Enum: fixedhourlyusage
default_ratenumber
≥ 0
unit_of_measurestring
min length 1 · max length 128
unit_codestring
category_idanyOf
anyOf (option 1)string <uuid>
anyOf (option 2)null
anyOf (option 3)null
tax_rate_idanyOf
anyOf (option 1)string <uuid>
anyOf (option 2)null
anyOf (option 3)null
descriptionanyOf
anyOf (option 1)string
max length 2048
anyOf (option 2)null
anyOf (option 3)null
is_activeboolean
pricesarray of object
Full set of current prices, rate in integer minor units (e.g. cents), currency_code from the supported currency list. Replaces the entire current price window; omitted currencies are removed and prices: [] clears it. prices[0] is the primary price and is mirrored into default_rate. Currencies must be unique.
itemsobject
currency_codestringRequired
rateintegerRequired
≥ 0
effective_dateany
price_idany
service_idany
tenantany
created_atany
updated_atany
display_orderany
scheduled_pricesarray of object
Full set of future-dated prices (each effective_date must be after today). Replaces the entire future price window; scheduled_prices: [] clears it. Does not change the current prices or default_rate.
itemsobject
currency_codestringRequired
rateintegerRequired
≥ 0
effective_dateany
price_idany
service_idany
tenantany
created_atany
updated_atany
display_orderany
currency_codeany
Not accepted. Send prices[].currency_code instead; a top-level currency_code returns 400.

Response body

Success response 201 · schema ServiceEnvelope

dataobjectRequired
Service catalog entry.
service_idstring <uuid>Required
tenantstring <uuid>Required
service_namestringRequired
custom_service_type_idstring <uuid>Required
billing_methodstringRequired
Enum: fixedhourlyusage
default_ratenumberRequired
unit_of_measurestringRequired
unit_codestringNullable
category_idstring <uuid>Nullable
tax_rate_idstring <uuid>Nullable
descriptionstringNullable
item_kindstring
Enum: serviceproduct
is_activeboolean
skustringNullable
costnumberNullable
cost_currencystringNullable
min length 3 · max length 3
vendorstringNullable
manufacturerstringNullable
product_categorystringNullable
is_licenseboolean
license_termstringNullable
license_billing_cadencestringNullable
service_type_namestring
pricesarray of ServicePrice
Current price per currency (latest effective on or before today).
itemsobject
currency_codestringRequired
min length 3 · max length 3
ratenumberRequired
Rate in integer minor units (e.g. cents).
display_orderinteger
Position within its window; 0 is the primary price. Responses are sorted by display_order, then currency_code.
effective_datestringNullable
Calendar date the price takes effect; the epoch when untagged.
scheduled_pricesarray of ServicePrice
Future-dated prices that are not yet billed.
itemsobject
currency_codestringRequired
min length 3 · max length 3
ratenumberRequired
Rate in integer minor units (e.g. cents).
display_orderinteger
Position within its window; 0 is the primary price. Responses are sorted by display_order, then currency_code.
effective_datestringNullable
Calendar date the price takes effect; the epoch when untagged.
metaobject

Response codes

201
Service created successfully.
400
Validation error, including rejected price writes: unsupported currency, fractional or negative rate, duplicate currency, scheduled date not in the future, default_rate conflicting with prices[0].rate, or a top-level currency_code.
401
Authentication failed.
403
Authenticated user lacks the required permission.