SDK reference

The Liteshop SDK sends Form submissions and booking and catalogue requests from a Site’s pages to Liteshop. It calls the Site’s own address, so it needs no keys and works only on a published Liteshop Site or with the local dev plugin.

Load the SDK

A Site without a build step loads the SDK with a script tag, before any script that uses it. The script defines the liteshop global:

<script src="/_liteshop/sdk/v1.js"></script>

A Site built with a framework installs the npm package and imports the SDK:

npm install @liteshop.ai/sdk

import { liteshop } from "@liteshop.ai/sdk";

The package includes TypeScript types. To type the liteshop global in a Site that uses the script tag, add /// <reference types="@liteshop.ai/sdk/global" /> to a TypeScript file. Call the SDK from event handlers or effects that run in the browser, not while a page is prerendered.

`liteshop.forms.submit`

Sends a Visitor’s answers to a declared Form.

liteshop.forms.submit(formId: string, values: Record<string, unknown>): Promise<{ accepted: true }>

Argument	Description
`formId`	The Form’s `id` in `liteshop.json`. Pass it as a literal string, such as `"contact"`, so that validation can find the call.
`values`	One entry per declared field, keyed by field `id`. Send numbers for `number` fields and booleans for `checkbox` fields; Liteshop doesn’t convert strings. An optional `_liteshop_honeypot` entry is used for spam protection and isn’t stored.

For details, see Forms.

`liteshop.bookings.getAvailability`

Returns which dates or slots of an Offer a Visitor can request.

liteshop.bookings.getAvailability({ offerId, from, to }): Promise<Availability>

Argument	Description
`offerId`	The Offer’s `id` in `liteshop.json`.
`from`	First date, in `YYYY-MM-DD` format.
`to`	Day after the last date. A timed Offer accepts at most 31 dates; nightly and daily Offers accept at most 366.

The response always includes offerId, from, to, and unit:

For a nightly or daily Offer, dates lists { date, available } for each date.
For a timed Offer, slots lists { start, end, available }. start and end are ISO 8601 times with the Site’s time-zone offset, such as 2027-06-01T09:00:00+02:00.

Availability shows what a Visitor can request, not what is reserved: it doesn’t report whether imported calendars are up to date. Present dates and slots as open for requests.

`liteshop.bookings.request`

Sends a Booking Request for an Offer. The Owner confirms or declines it; the request doesn’t block the dates until the Owner confirms it.

liteshop.bookings.request(input): Promise<{ accepted: true }>

Field	Description
`offerId`	The Offer’s `id`.
`arrival`, `departure`	For a `nightly` Offer: the arrival date and the check-out date, in `YYYY-MM-DD` format.
`startDate`, `endDate`	For a `daily` Offer: the first and the last booked day.
`start`	For a `timed` Offer: a slot’s `start`, exactly as `getAvailability` returned it.
`guests`	Number of guests, from 1 to the Offer’s `maximumGuests`.
`contact`	One entry per field in `requestFields`, keyed by field `id`.
`locale`	The page language, for example `document.documentElement.lang`.
`message`	Optional. Up to 2,000 characters.

For details, see Bookings.

`liteshop.catalogue.list`

Returns the published Catalogue Items and collections.

liteshop.catalogue.list(): Promise<{ items, collections }>

Each item has id, kind (product or service), name, optional description, optional price (amount in minor units and currency), optional images (Site-relative URLs, main image first) and image (the main image), maximumQuantity, and available. available is false when the Owner tracks stock and none is left. name and description are objects keyed by language. Each collection has id, name, and the ordered items IDs.

`liteshop.catalogue.request`

Sends a request for one Catalogue Item. The Owner confirms or declines it and arranges payment outside Liteshop.

liteshop.catalogue.request({ itemId, quantity, contact, message }): Promise<{ accepted: true }>

Field	Description
`itemId`	A declared item’s `id`.
`quantity`	Optional. A whole number from 1 to the item’s `maximumQuantity`. The default is 1.
`contact`	One entry per field in the catalogue’s `requestFields`. Omit optional fields instead of sending empty values.
`message`	Optional. Up to 2,000 characters.

The SDK sends the page language from <html lang>. For details, see Catalogue.

Errors

When Liteshop rejects a call, the promise rejects with an error that has these properties:

Property	Description
`code`	A stable code from the tables below.
`message`	A message you can show to Visitors. On pages whose `<html lang>` is French, the message is in French, except for `INVALID_ARGUMENT`.
`field`	The rejected field’s ID, when the error concerns one field.
`retryable`	`true` if trying again later might succeed.

Errors for all methods

Code	Meaning
`INVALID_ARGUMENT`	The SDK rejected malformed input before sending it. The message is for developers and is in English.
`NETWORK_ERROR`	The request got no response.
`INVALID_RESPONSE`	Liteshop returned a response that the SDK can’t read.
`INVALID_REQUEST`	Liteshop rejected the shape or size of the request.
`METHOD_NOT_ALLOWED`	The request used the wrong HTTP method.
`CAPABILITY_NOT_DECLARED`	The live Deployment doesn’t declare the Form, Offer, or Catalogue Item.
`CAPABILITY_UNAVAILABLE`	The feature isn’t available.
`IDEMPOTENCY_CONFLICT`	The same request identifier was used with different input.
`RATE_LIMITED`	Too many submissions from this Visitor or for this Site. Try again later.
`INTERNAL_ERROR`	Liteshop failed to handle the request.

Field errors

Forms, Booking Requests, and catalogue requests check each value against its declared field, and report these codes with the field’s ID in field: VALUES_INVALID, FIELD_UNDECLARED, FIELD_REQUIRED, FIELD_TYPE_INVALID, FIELD_TOO_SHORT, FIELD_TOO_LONG, FIELD_EMAIL_INVALID, FIELD_BELOW_MINIMUM, FIELD_ABOVE_MAXIMUM, and FIELD_OPTION_INVALID.

Booking errors

Code	Meaning
`DATE_INVALID`	A date isn’t a valid `YYYY-MM-DD` date.
`DATE_RANGE_INVALID`	The end of the range isn’t after its start.
`DATE_RANGE_TOO_LARGE`	The range covers more dates than allowed.
`BOOKING_MINIMUM_NIGHTS`	The stay is shorter than the Offer’s `minimumNights`.
`BOOKING_GUESTS_INVALID`	`guests` is outside the Offer’s limit.
`BOOKING_ADVANCE_INVALID`	The dates are too soon or too far ahead.
`BOOKING_MESSAGE_TOO_LONG`	`message` is longer than 2,000 characters.
`BOOKING_DATES_UNAVAILABLE`	Some of the dates are no longer available.
`BOOKING_SLOT_UNAVAILABLE`	The slot is no longer available.

Catalogue errors

Code	Meaning
`CATALOGUE_QUANTITY_INVALID`	`quantity` is outside 1 to the item’s `maximumQuantity`.
`CATALOGUE_MESSAGE_TOO_LONG`	`message` is longer than 2,000 characters.
`CATALOGUE_OUT_OF_STOCK`	Not enough tracked stock is left.

Retries and spam protection

The SDK gives each call an identifier and retries one network failure with the same identifier, so a retry never creates a duplicate. Liteshop accepts at most five submissions per Visitor for each Form, Offer, or Catalogue Item every 10 minutes, and at most 100 per Site every hour.

Get started

Build with code

Frameworks

Reference