README

A PHP client for the Lightspeed X-Series (formerly Vend) API with built-in OAuth2 support.

Requirements

• PHP 8.0+
• cURL extension
• JSON extension

Installation

composer require anytech/lightspeed-x-series-api

Quick Start

use LightspeedXSeries\LightspeedAPI; $api = new LightspeedAPI( 'https://mystore.retail.lightspeed.app', 'Bearer', 'your-access-token' ); // Get all products $products = $api->apiRequest('products', 'get'); foreach ($products->data as $product) { echo $product->name . "\n"; } // Get a single product $product = $api->apiRequest('products/abc-123-uuid', 'get'); // Create a customer $customer = $api->apiRequest('customers', 'post', '2.0', [ 'first_name' => 'John', 'last_name' => 'Doe', 'email' => 'john@example.com', ]); // Update a product $api->apiRequest('products/abc-123-uuid', 'put', '2.0', [ 'name' => 'Updated Product Name', ]); // Delete a product $api->apiRequest('products/abc-123-uuid', 'delete');

API Versions

The library supports all Lightspeed X-Series API versions:

use LightspeedXSeries\LightspeedAPI; // Using version constants $api->apiRequest('products', 'get', LightspeedAPI::VERSION_20); $api->apiRequest('fulfillments', 'get', LightspeedAPI::VERSION_30_BETA); // Or using string values $api->apiRequest('products', 'get', '2.0'); $api->apiRequest('fulfillments', 'get', '3.0b');

The apiRequest Method

All API calls use the single apiRequest() method:

$api->apiRequest( string $endpoint, // The endpoint path (e.g., 'products', 'customers/123') string $method, // HTTP method: 'get', 'post', 'put', 'delete' string $version, // API version (default: '2.0') ?array $data // Request body (POST/PUT) or query params (GET) ): object

GET Requests with Query Parameters

// With pagination $products = $api->apiRequest('products', 'get', '2.0', [ 'page_size' => 100, 'after' => 'cursor-value', ]); // With filters $customers = $api->apiRequest('customers', 'get', '2.0', [ 'email' => 'john@example.com', ]);

POST Requests

$customer = $api->apiRequest('customers', 'post', '2.0', [ 'first_name' => 'John', 'last_name' => 'Doe', 'email' => 'john@example.com', ]);

PUT Requests

$api->apiRequest('customers/abc-123', 'put', '2.0', [ 'phone' => '+1234567890', ]);

DELETE Requests

$api->apiRequest('customers/abc-123', 'delete');

OAuth2 Authentication

Step 1: Create OAuth Client

use LightspeedXSeries\LightspeedOAuth; $oauth = new LightspeedOAuth( 'your-client-id', 'your-client-secret', 'mystore', // Your store prefix 'https://yoursite.com/oauth/callback', // Redirect URI ['products:read', 'products:write'] // Scopes (required from March 2026) );

Step 2: Generate Authorization URL

$auth = $oauth->getAuthorizationUrl(); // Store state in session for CSRF protection $_SESSION['oauth_state'] = $auth['state']; // Redirect user to Lightspeed header('Location: ' . $auth['url']);

Step 3: Handle Callback

// Verify state matches if ($_GET['state'] !== $_SESSION['oauth_state']) { throw new Exception('Invalid state'); } // Exchange code for tokens $tokens = $oauth->exchangeCodeForToken($_GET['code']); // Store tokens securely $accessToken = $tokens['access_token']; $refreshToken = $tokens['refresh_token']; $expiresIn = $tokens['expires_in'];

Step 4: Refresh Tokens

$newTokens = $oauth->refreshToken($refreshToken); $accessToken = $newTokens['access_token']; $refreshToken = $newTokens['refresh_token'];

API Endpoints Reference

All endpoints use the apiRequest() method. Replace {id} with the actual UUID.

Products

// List products with pagination $products = $api->apiRequest('products', 'get', '2.0', ['page_size' => 100]); // Get single product $product = $api->apiRequest('products/abc-123', 'get'); // Create product $product = $api->apiRequest('products', 'post', '2.0', [ 'name' => 'New Product', 'sku' => 'SKU001', 'retail_price' => 99.99, ]); // Update product (use 2.1 for common fields) $api->apiRequest('products/abc-123', 'put', '2.1', [ 'common' => [ 'name' => 'Updated Name', 'description' => 'New description', ] ]); // Delete product $api->apiRequest('products/abc-123', 'delete'); // Upload image $api->apiRequest('products/abc-123/images', 'post', '2.0', [ 'url' => 'https://example.com/image.jpg', ]);

Product Images

// Set image position $api->apiRequest('product_images/abc-123', 'put', '2.0', ['position' => 1]); // Delete image $api->apiRequest('product_images/abc-123', 'delete');

Product Types

Variant Attributes

Customers

// Search by email $customers = $api->apiRequest('customers', 'get', '2.0', [ 'email' => 'john@example.com', ]); // Create customer $customer = $api->apiRequest('customers', 'post', '2.0', [ 'first_name' => 'John', 'last_name' => 'Doe', 'email' => 'john@example.com', 'phone' => '+1234567890', ]); // Update customer $api->apiRequest('customers/abc-123', 'put', '2.0', [ 'phone' => '+0987654321', ]);

Customer Groups

// Add customers to group $api->apiRequest('customer_groups/abc-123/customers', 'post', '2.0', [ 'customer_ids' => ['cust-1', 'cust-2', 'cust-3'], ]);

Brands

Tags

Product Categories

// Bulk update categories $api->apiRequest('product_categories/bulk', 'post', '2.0', [ 'categories' => [ ['id' => 'cat-1', 'name' => 'Updated Name 1'], ['id' => 'cat-2', 'name' => 'Updated Name 2'], ] ]);

Inventory

// Create inventory adjustment $api->apiRequest('inventory', 'post', '2.0', [ 'product_id' => 'prod-123', 'outlet_id' => 'outlet-456', 'adjustment' => 10, ]);

Suppliers

Price Books

Price Book Products

Promotions

Promo Codes (Bulk)

Discount

Sales

// Get sales with filters $sales = $api->apiRequest('sales', 'get', '2.0', [ 'status' => 'CLOSED', 'page_size' => 50, ]);

Fulfillments

// Fulfill entire sale $api->apiRequest('fulfillments/fulfill', 'post', '2.0', [ 'sale_id' => 'sale-123', ]); // Update fulfillment status $api->apiRequest('fulfillments/abc-123', 'put', '2.0', [ 'status' => 'SHIPPED', 'tracking_number' => 'TRACK123', ]);

Registers

Register Closures

Outlets

Payments

Payment Types

Taxes

Consignments

Consignment Products

Service Orders

Gift Cards

// Create gift card $api->apiRequest('gift_cards', 'post', '2.0', [ 'number' => '1234567890', 'initial_balance' => 100.00, ]); // Redeem gift card $api->apiRequest('gift_cards/1234567890/transactions', 'post', '2.0', [ 'type' => 'REDEEMING', 'amount' => -25.00, // Negative for redemption 'client_id' => 'unique-transaction-id', ]); // Reload gift card $api->apiRequest('gift_cards/1234567890/transactions', 'post', '2.0', [ 'type' => 'RELOADING', 'amount' => 50.00, // Positive for reload ]);

Users

Webhooks

// Create webhook $api->apiRequest('webhooks', 'post', '2.0', [ 'url' => 'https://yoursite.com/webhook', 'type' => 'sale.update', ]); // Webhook types: // - sale.update // - inventory.update // - customer.update // - product.update

Search

$results = $api->apiRequest('search', 'post', '2.0', [ 'query' => 'blue shirt', 'type' => 'products', ]);

Loyalty

Channel Requests (Ecommerce)

Store Credit

Line Items

Common Query Parameters

Most GET endpoints support these query parameters:

Debug Mode

Enable debug mode to see request/response details:

$api->debug(true); // Make requests... // Access debug data $rawResponse = $api->getLastResultRaw(); $httpCode = $api->getLastHttpCode();

Rate Limiting

The API client automatically handles rate limiting (HTTP 429). When rate limited, it will wait and retry.

// Allow time slip for servers with clock drift $api->allowTimeSlip = true;

OAuth Scopes

From March 31, 2026, OAuth requests must include scopes. Request only the scopes your application needs.

Selecting Scopes

1. Review all endpoints used by your application
2. Check the required scope(s) for each endpoint
3. Combine and remove duplicates to form your scope list

$oauth = new LightspeedOAuth( $clientId, $clientSecret, $domainPrefix, $redirectUri, ['products:read', 'sales:read', 'customers:read'] // Space-delimited in URL );

Available Scopes

License

MIT License. See LICENSE for details.

Links

• Lightspeed X-Series API Documentation
• API Changelog