> For the complete documentation index, see [llms.txt](https://docs.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.violet.io/ecom-platforms/lightspeed.md).

# Lightspeed eCom

Lightspeed eCom (formerly SEOshop) is a cloud-based ecommerce platform for retail merchants. Violet integrates using HTTP Basic authentication with an API key and secret provided by the merchant.

## Connection

Merchants provide three credentials:

| Field          | Description                                                         |
| -------------- | ------------------------------------------------------------------- |
| **Store URL**  | Lightspeed API base URL (e.g. `https://api.shoplightspeed.com/en/`) |
| **API Key**    | Generated in the Lightspeed merchant admin                          |
| **API Secret** | Generated alongside the API key                                     |

Credentials are validated during onboarding by hitting the Lightspeed Account endpoint. There is no OAuth consent flow. Lightspeed does not have a scope model; all permissions are determined by the API key at the time it is created.

## Webhooks

Violet registers webhooks automatically after a merchant connects. The following topics are subscribed:

| Topic             | Event                  |
| ----------------- | ---------------------- |
| `product.created` | Product created        |
| `product.updated` | Product updated        |
| `product.deleted` | Product deleted        |
| `order.created`   | Order placed           |
| `order.updated`   | Order updated          |
| `order.paid`      | Order payment received |
| `order.shipped`   | Order shipped          |
| `return.created`  | Return initiated       |
| `return.updated`  | Return updated         |
| `return.deleted`  | Return deleted         |

> **Note**: Lightspeed does not sign webhook deliveries — there is no HMAC signature to verify. Authenticity is established at registration time via the credentialed merchant URL.

## Direct Order Submission

Order submission follows a multi-step checkout pipeline:

1. `POST /checkouts.json` — create checkout with customer and addresses
2. `POST /checkouts/{id}/products.json` — add each line item
3. `PUT /checkouts/{id}.json` — set shipping method
4. `PUT /checkouts/{id}.json` — set payment method (always external "Violet")
5. `GET /checkouts/{id}/validate.json` — must return `{validated: true}`
6. `POST /checkouts/{id}/order.json` — finalize and retrieve order ID
7. `PUT /orders/{id}.json` — mark payment status as paid

## Discounts

Both custom discounts and synced promo codes are supported:

* **Custom discounts** (fixed or percentage): Amount is calculated and the bag total is decremented before checkout creation.
* **Discount codes**: Passed at checkout finalization. Lightspeed does not have a dedicated discount-code endpoint — the code is included when the checkout is submitted, and Violet reads the finalized order response to determine whether the code was applied.

## Products

Lightspeed's product model separates the product container from its purchasable variants:

* **Product**: Container only — holds name, description, and media. Not directly purchasable.
* **Variant**: Holds price, inventory, and dimensions. These map to Violet SKUs.

Variant titles use a `Type:Value, Type:Value` format (e.g. `Color:Red, Size:M`), which Violet parses into individual variant dimensions.

## Pagination

Lightspeed uses `?page=N&limit=N` pagination with a hard limit of 250 results per page. Order polling uses `?updated_at_min` (ISO-8601 with `+0000` offset) to fetch only recently modified records.

## Notable Behavior

* **No scope model**: Lightspeed does not use OAuth scopes. All permissions are implicit in the API key.
* **Webhook signatures**: Inbound webhooks are not signed. Violet does not perform signature verification for this platform.
* **Shipping validation**: Violet verifies that at least one shipping method is configured on the store during connection.
* **Fulfillment status mapping**: Only `shipped` and `partially_shipped` shipment statuses are mapped to Violet's fulfillment states. Orders in `not_shipped` or `cancelled` states leave the bag's fulfillment status unset.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.violet.io/ecom-platforms/lightspeed.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.