Skip to main content
A service is the thing you sell, such as “Private swim lesson”. On its own it sells nothing. Two kinds of record hang off it:
  • 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.
A package is a prepaid bundle of sessions of one offering. Packages have their own page: see Packages.
To set all of this up in order, follow Provision your catalog and suppliers. This page is the reference for each object.

The service lifecycle

A new service is always DRAFT, whatever you send on create.
POST /v1/projects/{projectId}/services/{serviceId}/status moves it:
  • DRAFT → LIVE, INACTIVE
  • LIVE → INACTIVE
  • INACTIVE → LIVE
Nothing goes back to 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:
Publishing checks nothing else. A service with no offerings and no business models goes 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:
A deleted service says 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:
  • name and primaryLanguage are required.
  • businessModels creates the service’s business models in the same call. Each one takes the same fields as Adding a business model.
  • taxSettings defaults to { "taxable": false }.
  • bufferBeforeStartMinutes defaults to 0. See Buffer before start.
Names are unique in a project, per language. The comparison ignores case, surrounding spaces and repeated spaces, but not accents or punctuation. A duplicate is a 409, and nothing is written:
The catalog routes take no idempotency key. The unique name protects a service from a retried create, but not an offering, business model or package. After a timeout, list what exists before you retry.

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:
  • name and description replace the stored map. Send every language you want to keep, or the ones you leave out are dropped.
  • participantSettings replaces the stored object. Send every field. The one exception is client.participantDisplay: leave it out and the stored value stays.
  • A new name in primaryLanguage is checked for uniqueness again. A clash is the same 409 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 primaryLanguage name while keeping another language’s name unchanged fails today with a 500. 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:
A value outside that range is a 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.
  • travelTimeMins never 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:
The business model is created active. Business models aren’t de-duplicated. Posting the same type twice leaves two rows, both active. List the service’s business models before you add one:
The list includes inactive models, so read active on each. It isn’t paginated.

Changing a business model

  • PUT .../business-models/{businessModelId} edits paymentOptions, fees and config. 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}/status with { "active": false } turns the model off, and { "active": true } turns it back on. Its type, payment options and fees are kept either way.
  • type can’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 businessModelId is 404 NOT_FOUND, “Business model not found”, on both routes. Nothing is written.
A fee on an inactive business model is stored but never charged, because an order line resolves only against active models. Turning off the 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 PACKAGE order line is 422 SERVICE_NOT_SOLD_AS, unless the service has an active SCHEDULED_PACKAGE model.
  • Sessions of packages clients already bought can’t be booked, through package bookings or hold conversion:
To stop selling one package, archive it instead. See The package lifecycle.

A line with no active business model

An order line whose service has no active business model of the right type is refused on POST /orders and on POST .../orders/{orderId}/items. Each returns a 422:
For a 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 created ACTIVE. 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:
This applies to order items already bought, too. Bookings already made against the offering stand. An unknown or deleted 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. 4500 is $45.00. A decimal is a 400 VALIDATION_ERROR.
  • Exactly one DEFAULT rule. It’s the price wherever no more specific rule matches, in its own currency.
  • A child rule needs its parent. A STATE rule needs a COUNTRY rule for the same country. A POSTAL rule needs the STATE rule for its state.
  • One rule per region. Two COUNTRY rules for the same country are refused.
  • Country and state are stored as ISO codes. You can send "Canada" or "Ontario". They’re stored as CA and ON, so read the offering back rather than assuming your spelling survived.
The most specific matching rule wins: 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 no DEFAULT 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.
It’s a gap in the catalog, not in your request, so retrying won’t help. Give the offering a 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:
Take the ids from 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, locationIds and attributeValues. To add one skill, send the full new list.
  • pricing is checked against the same rules as on create. A list that drops the DEFAULT rule is a 400.
  • An order item already placed keeps the price it was captured at. A new price applies to new order lines only.
An unknown or deleted 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}/services
  • GET /v1/projects/{projectId}/services
  • GET /v1/projects/{projectId}/services/{serviceId}
  • PUT /v1/projects/{projectId}/services/{serviceId}
  • POST /v1/projects/{projectId}/services/{serviceId}/status
  • DELETE /v1/projects/{projectId}/services/{serviceId}
  • GET /v1/projects/{projectId}/services/{serviceId}/business-models
  • POST /v1/projects/{projectId}/services/{serviceId}/business-models
  • PUT /v1/projects/{projectId}/services/{serviceId}/business-models/{businessModelId}
  • POST /v1/projects/{projectId}/services/{serviceId}/business-models/{businessModelId}/status
  • POST /v1/projects/{projectId}/services/{serviceId}/offerings
  • GET /v1/projects/{projectId}/services/{serviceId}/offerings
  • GET /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}
  • PUT /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}
  • POST /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}/status
  • DELETE /v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}
  • Packages, .../offerings/{offeringId}/packages and /packages/{packageId} — see Packages