> ## Documentation Index
> Fetch the complete documentation index at: https://docs.liteshop.me/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK reference

> Methods, arguments, return values, and errors of the Liteshop browser SDK.

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](https://docs.liteshop.me/develop/local-development.md).

## 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:

```html theme={null}
<script src="/_liteshop/sdk/v1.js"></script>
```

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

```sh theme={null}
npm install @liteshop.ai/sdk
```

```ts theme={null}
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.

```ts theme={null}
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](https://docs.liteshop.me/reference/forms.md).

## `liteshop.bookings.getAvailability`

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

```ts theme={null}
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.

```ts theme={null}
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](https://docs.liteshop.me/bookings.md).

## `liteshop.catalogue.list`

Returns the published Catalogue Items and collections.

```ts theme={null}
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.

```ts theme={null}
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](https://docs.liteshop.me/reference/catalogue.md).

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.