Create a service
Creates a service in the studio's draft: it is live in GET /services only after POST /catalog/publish. Same
rules as the admin: the name, a non-empty description (plain text, or a rich text { "v": 1, "doc": ... }),
a positive basePrice in minor units and durationMinutes, and a known categoryId (an unknown one is 404
with field: categoryId). variants is the full list of the studio's variants (GET /catalog/variants);
left out, the studio's default variants are used, and 400 when it has none. sortOrder left out puts the
service last in its category; slug left out is derived from the name. Plan walls as on the admin: a FREE
studio has a limited number of main services, and more than one employee, FROM / ON_REQUEST pricing, a lead
time, and multi-day beyond the free allowance need a higher plan (403 PLAN_REQUIRED). Audited with the API key
as the actor. Requires the catalog:write scope and an Idempotency-Key header.
ApiKeyAuth catalog:writeAuthorizationBearer <shyni_sk_live_*>An API key, issued once and never retrievable again: an organization key in the developer
portal, or a studio key in the studio's admin (Moje studio → API). Send as Authorization: Bearer shyni_sk_live_....
Scope: catalog:write
Idempotency-Key*stringCaller-chosen idempotency token for this write. A retry under the SAME key with
the SAME body replays the first response; the SAME key with a DIFFERENT body is
422 IDEMPOTENCY_KEY_MISMATCH. See Idempotency above.
length <= 64application/json- body
categoryId*stringname*stringlength <= 255description*|Plain text, or a rich text document { "v": 1, "doc": ... }; at most 1000 plain characters.
scope*ServiceScope"PRIMARY""SECONDARY""ADDON"basePrice*integerMinor units of the studio currency; positive.
int64durationMinutes*integeremployeesRequired?integer1postWorkStrategy?string"NONE""NONE""NEXT_WORKING_DAY""FIXED_DURATION"postWorkMinutes?integerRequired with FIXED_DURATION, otherwise absent.
variants?array<>discountPercent?integer0 <= value <= 990sortOrder?integerslug?stringstorefrontVisible?booleantruemultiDay?booleanfalsepricingMode?string"EXACT""EXACT""FROM""ON_REQUEST"minAdvanceDays?integer0 <= value <= 3650renewalIntervalMonths?integer1 <= value <= 60orderAudience?string"ALL""ALL""KNOWN_CARS"soldOnlyWithServiceIds?array<string>ADDON scope only (400 with field soldOnlyWithServiceIds otherwise). Ids of existing non-ADDON services; empty = with any primary service.
The new draft service.
application/json- response
A service as the catalog write endpoints show it: the DRAFT row the studio edits, with every field the write
endpoints change. id is the logical id every endpoint takes; the live storefront shows the row only after
POST /catalog/publish.
id*stringslug*stringname*stringdescription*Formatted text (a studio's own wording with bold, italic, links and lists). The same text in three projections, so an integration picks what suits it.
Forward compatibility: json.v is the schema version; new node and mark types may be added in
later versions - skip nodes you don't know and fall back to plain.
scope*ServiceScope"PRIMARY""SECONDARY""ADDON"basePrice*integerAmount in minor units of currency (hellers for CZK).
int64currency*stringdurationMinutes*integeremployeesRequired*integerpostWorkStrategy*string"NONE""NEXT_WORKING_DAY""FIXED_DURATION"postWorkMinutes*integer|nullvariants*array<>discountPercent*integerpricingMode*string"EXACT""FROM""ON_REQUEST"minAdvanceDays*integerrenewalIntervalMonths*integer|nullmultiDay*booleanstorefrontVisible*booleansortOrder*integercategoryId*stringhighlight*string"NONE""MOST_POPULAR""BEST_VALUE""RECOMMENDED"active*booleanfalse = archived.
imageId*string|nullincludes*array<string>forWhom*string|nullrecommendedAddonIds*array<string>orderAudience*stringKNOWN_CARS = orderable only for a car that already has a completed order at the studio (POST /orders needs a knownCarToken).
"ALL""KNOWN_CARS"soldOnlyWithServiceIds*array<string>Add-on only (empty otherwise) - ids of the services it may be ordered with; empty = with any primary service.
curl -X POST 'https://api.shyni.io/api/v1/services' \ -H 'Authorization: Bearer shyni_sk_test_YOUR_KEY' \ -H 'Idempotency-Key: 7f3c9a52-1d4e-4b86-a0c7-5e2b9d8f6a13' \ -H 'Content-Type: application/json' \ -d '{ "categoryId": "string", "name": "string", "description": "string", "scope": "PRIMARY", "basePrice": 0, "durationMinutes": 0}'Response 201
The new draft service.
{ "id": "string", "slug": "string", "name": "string", "description": { "plain": "string", "html": "string", "json": { "v": 0, "doc": {} } }, "scope": "PRIMARY", "basePrice": 0, "currency": "string", "durationMinutes": 0, "employeesRequired": 0, "postWorkStrategy": "NONE", "postWorkMinutes": 0, "variants": [ { "code": "string", "priceMultiplier": 0, "extraMinutes": 0 } ], "discountPercent": 0, "pricingMode": "EXACT", "minAdvanceDays": 0, "renewalIntervalMonths": 0, "multiDay": true, "storefrontVisible": true, "sortOrder": 0, "categoryId": "string", "highlight": "NONE", "active": true, "imageId": "string", "includes": [ "string" ], "forWhom": "string", "recommendedAddonIds": [ "string" ], "orderAudience": "ALL", "soldOnlyWithServiceIds": [ "string" ]}Response 400
A parameter, header or request body is missing, malformed, or out of range. A request body property the endpoint does not define answers UNKNOWN_FIELD instead, with field naming it.
{ "code": "INVALID_INPUT", "message": "Parameter perPage must be between 1 and 100."}Response 401
Missing, malformed, unknown, or revoked API key (INVALID_API_KEY).
{ "code": "INVALID_API_KEY", "message": "Missing or invalid API key."}Response 403
The key is valid but the request is refused. Branch on code: INSUFFICIENT_SCOPE (the key lacks the
permission this endpoint requires), PLAN_REQUIRED (the studio is not on a plan that includes API keys,
Pro and above), ORIGIN_NOT_ALLOWED, SECRET_KEY_IN_BROWSER, or DEMO_STUDIO on a write to the demo studio.
See Authentication and Scopes above.
{ "code": "INSUFFICIENT_SCOPE", "message": "This API key does not have the permission this endpoint requires."}Response 404
The resource does not exist, or belongs to a different studio.
{ "code": "NOT_FOUND", "message": "Order not found."}Response 409
The request is well-formed but the studio's current state forbids it.
{ "code": "CONFLICT", "message": "The voucher cannot be deactivated because it is not active."}Response 422
The same Idempotency-Key was already used for a request with a different body, use a new key (see Idempotency above).
{ "code": "IDEMPOTENCY_KEY_MISMATCH", "message": "This Idempotency-Key was already used for a different request. Use a new key."}Response 429
Burst rate limit exceeded.
{ "code": "RATE_LIMITED", "message": "Too many requests. Retry after the time given in the Retry-After header."}