- Business models say how the service may be sold: one session at a time, as a package, and so on.
- Offerings are the bookable variants. Each one carries a duration and a price. A client books an offering, never a bare service.
The service lifecycle
A new service is alwaysDRAFT, whatever you send on create.
POST /v1/projects/{projectId}/services/{serviceId}/status moves it:
DRAFT→LIVE,INACTIVELIVE→INACTIVEINACTIVE→LIVE
DRAFT. To keep working on a service privately after
you publish it, set it INACTIVE. Any other move, including LIVE to
LIVE, is a 400, and nothing changes:
LIVE.
What the status controls
LIVE is what makes a service visible. A supplier’s services, on
GET /suppliers, on a supplier’s profile and on every search result, lists
only LIVE services. A DRAFT or INACTIVE service stays linked to its
suppliers but doesn’t appear. A status change can take up to a minute to show
there.
Only a LIVE service sells. POST /orders and
POST .../orders/{orderId}/items refuse a line for a service that isn’t
LIVE, or was deleted.
The refusal is a 422, and nothing is written:
Service srv_… was deleted and is no longer sold.
Retiring a service stops new sales only. Order items already bought stay
bookable: POST /bookings, package bookings and hold conversion don’t check
the service’s status. They check only the offering, which must still be
ACTIVE. Bookings and orders already placed are never touched by a status
change.
Show clients only services you listed with status=LIVE.
Deleting a service
DELETE /v1/projects/{projectId}/services/{serviceId} is a soft-delete. The
service is set INACTIVE and disappears from lists and reads, so a GET of
it is a 404. The record is kept, so bookings and orders against it still
resolve.
Deleting releases the service’s name at once, so a new service can take it.
That is how you free a name you typed wrong.
Offerings aren’t deleted with the service. They keep their own status and
stay readable one by one. Set them INACTIVE first if anything of yours reads
offerings without checking the service.
Anatomy of a service
GET /v1/projects/{projectId}/services/{serviceId} returns the service on its
own. Offerings, business models and packages are separate reads, so pricing
and duration always take a second call.
A service has no externalId. Store the serviceId against your own record.
Creating a service
POST /v1/projects/{projectId}/services:
nameandprimaryLanguageare required.businessModelscreates the service’s business models in the same call. Each one takes the same fields as Adding a business model.taxSettingsdefaults to{ "taxable": false }.bufferBeforeStartMinutesdefaults to0. See Buffer before start.
409, and nothing is written:
Updating a service
PUT /v1/projects/{projectId}/services/{serviceId} changes the descriptive
fields. Send only the fields you’re changing, but send each one whole:
nameanddescriptionreplace the stored map. Send every language you want to keep, or the ones you leave out are dropped.participantSettingsreplaces the stored object. Send every field. The one exception isclient.participantDisplay: leave it out and the stored value stays.- A new name in
primaryLanguageis checked for uniqueness again. A clash is the same409 CONFLICT, and nothing else in the update is applied either. - A name changed only in another language isn’t checked, and isn’t reserved.
- Renaming the
primaryLanguagename while keeping another language’s name unchanged fails today with a500. Change the primary name on its own, or every language at once.
status isn’t settable here. Use the status route.
Buffer before start
bufferBeforeStartMinutes is the spacing a supplier needs before this
service starts, such as time to set up. Send an integer from 0 to 120 on
create or update:
400 VALIDATION_ERROR.
The buffer shapes suggestions and checks only:
- Suggested times leave the buffer free before each session of this service.
- It applies to online sessions too, not only to sessions with travel.
- It’s never written as busy time, so it never blocks another booking.
travelTimeMinsnever includes it.- A booking at a time you name is never refused because of it.
Listing services
GET /v1/projects/{projectId}/services returns the whole catalog in one
response, sorted by name within each status. It isn’t paginated:
nextCursor is always null and there’s no limit.
Without
status, DRAFT and INACTIVE services are included. Deleted
services never are. The list also accepts a search parameter, but doesn’t
apply it today: filter by name on your side.
Business models
A business model says one way a service may be sold. An order line needs an active business model that matches it, or it’s refused.Anatomy of a business model
Adding a business model
POST /v1/projects/{projectId}/services/{serviceId}/business-models:
type twice
leaves two rows, both active. List the service’s business models before you
add one:
active on each. It isn’t
paginated.
Changing a business model
PUT .../business-models/{businessModelId}editspaymentOptions,feesandconfig. Each one you send replaces the stored value whole. Send"fees": []to clear the fees. Leave a field out to keep it.POST .../business-models/{businessModelId}/statuswith{ "active": false }turns the model off, and{ "active": true }turns it back on. Its type, payment options and fees are kept either way.typecan’t be changed. To sell the service another way, turn this model off and add a new one.- There is no delete. Turn the model off instead.
- An unknown
businessModelIdis404 NOT_FOUND, “Business model not found”, on both routes. Nothing is written.
PACKAGE model does more than stop new packages. While
the service has no active PACKAGE model:
- A package can’t be created:
400 BAD_REQUEST. - A
PACKAGEorder line is422 SERVICE_NOT_SOLD_AS, unless the service has an activeSCHEDULED_PACKAGEmodel. - Sessions of packages clients already bought can’t be booked, through package bookings or hold conversion:
A line with no active business model
An order line whose service has no active business model of the right type is refused onPOST /orders and on POST .../orders/{orderId}/items. Each
returns a 422:
SINGLE_SESSION line the message names SINGLE_BOOKING. Nothing is
written. Add or reactivate the business model, then retry.
Offerings
An offering is what a client actually books: a duration and a price. Every booking and order line names one.The offering lifecycle
An offering is createdACTIVE. There is no draft step.
POST /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}/status
with { "status": "INACTIVE" } takes it off sale, and ACTIVE puts it back.
Either move is allowed at any time.
Only an ACTIVE offering can be ordered or booked. An order line, a booking,
a package booking or a hold conversion for an INACTIVE one is a 422:
offeringId on the status route is 404 NOT_FOUND,
“Offering not found”, and nothing is written.
Anatomy of an offering
skills and locations come back on the list and on the single read. An id
that no longer resolves, such as an inactive skill, is left out of skills,
so it can be shorter than skillIds.
Pricing rules
pricing is a list of rules, not a single amount. Each rule has a ruleId
you choose, a scope and a price:
- Amounts are integer minor units.
4500is $45.00. A decimal is a400 VALIDATION_ERROR. - Exactly one
DEFAULTrule. It’s the price wherever no more specific rule matches, in its own currency. - A child rule needs its parent. A
STATErule needs aCOUNTRYrule for the same country. APOSTALrule needs theSTATErule for its state. - One rule per region. Two
COUNTRYrules for the same country are refused. - Country and state are stored as ISO codes. You can send
"Canada"or"Ontario". They’re stored asCAandON, so read the offering back rather than assuming your spelling survived.
POSTAL, then STATE, then COUNTRY,
then DEFAULT. See Regional pricing.
A rule set that breaks one of these is a 400, and nothing is written. The
message names the rule’s position:
An offering with no DEFAULT rule
Create and update refuse a rule set with noDEFAULT rule. An offering can
still end up without one, for example one written before that check existed.
Any write that prices such an offering returns a 422:
POST /orders, POST .../orders/{orderId}/items, POST /bookings, a package
booking and hold conversion.
DEFAULT rule with PUT.
An offering created before regional pricing existed reads back with one
DEFAULT rule whose ruleId is r_legacy_default. Treat it as real pricing.
It’s derived when the offering is read, so send a full pricing list when you
next update the offering.
Creating an offering
POST /v1/projects/{projectId}/services/{serviceId}/offerings takes the body
above. pricing and duration are required.
Every id in skillIds and locationIds must name an existing, active skill
or Location in the project. Otherwise the whole call is a 400:
GET /skills and GET /locations. Both are read-only on the
public API: see Locations and skills.
A service id that doesn’t exist is 404 NOT_FOUND, Service not found. A
deleted service isn’t refused, and still takes new offerings.
Updating an offering
PUT .../offerings/{offeringId} is a partial update, despite the verb. Only
the fields you send are written.
- An array you send replaces the stored one whole:
pricing,skillIds,locationIdsandattributeValues. To add one skill, send the full new list. pricingis checked against the same rules as on create. A list that drops theDEFAULTrule is a400.- An order item already placed keeps the price it was captured at. A new price applies to new order lines only.
offeringId is 404 NOT_FOUND, “Offering not found”,
and nothing is written.
Deleting an offering
DELETE .../offerings/{offeringId} is a soft-delete. The offering is set
INACTIVE, leaves the lists, and the service’s counts.offerings drops by
one. The record is kept, so bookings and order items that captured it still
resolve. The API can’t undo a delete.
An unknown or already-deleted offeringId is 404 NOT_FOUND, “Offering not
found”, and changes nothing. So a retried delete is safe: treat its 404 as
done.
Packages built on the offering aren’t deleted with it, and keep selling. But
sessions bought from them can no longer be booked: each booking is
404 NOT_FOUND, Offering off_… not found. Archive those packages before you
delete the offering. To take an offering off sale and keep the option of
selling it again, use the status route instead.
Listing offerings
GET /v1/projects/{projectId}/services/{serviceId}/offerings returns every
offering of the service in one response. It isn’t paginated: nextCursor is
always null.
Deleted offerings are left out. INACTIVE ones are included unless you send
status=ACTIVE.
Endpoint index
POST /v1/projects/{projectId}/servicesGET /v1/projects/{projectId}/servicesGET /v1/projects/{projectId}/services/{serviceId}PUT /v1/projects/{projectId}/services/{serviceId}POST /v1/projects/{projectId}/services/{serviceId}/statusDELETE /v1/projects/{projectId}/services/{serviceId}GET /v1/projects/{projectId}/services/{serviceId}/business-modelsPOST /v1/projects/{projectId}/services/{serviceId}/business-modelsPUT /v1/projects/{projectId}/services/{serviceId}/business-models/{businessModelId}POST /v1/projects/{projectId}/services/{serviceId}/business-models/{businessModelId}/statusPOST /v1/projects/{projectId}/services/{serviceId}/offeringsGET /v1/projects/{projectId}/services/{serviceId}/offeringsGET /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}PUT /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}POST /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}/statusDELETE /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}- Packages,
.../offerings/{offeringId}/packagesand/packages/{packageId}— see Packages