Lightspeed eCom

Overview of Violet's Lightspeed eCom integration for channel developers

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.