\n\n# LiquidCommerce Cloud SDK\n\nThe LiquidCommerce Cloud SDK provides an easy way to interact with our APIs through a server-side SDK for Node.js and Web JS script.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Configuration](#configuration)\n - [API Key Authentication](#api-key-authentication)\n - [Order API Authentication](#order-api-authentication)\n- [Services & Usage](#services-and-usage)\n - [Address](#address)\n - [Catalog](#catalog)\n - [Cart](#cart)\n - [User](#user)\n - [Payment Element](#payment-element)\n - [Legacy Payment](#legacy-payment)\n - [Checkout](#checkout)\n - [Orders](#orders)\n - [Webhook](#webhook)\n- [Response Types](#response-types)\n- [Error Handling](#error-handling)\n- [Documentation](#documentation)\n\n## Installation\n\nInstall the package with:\n\n```sh\nnpm install @liquidcommerce/cloud-sdk\n# or\nyarn add @liquidcommerce/cloud-sdk\n# or\npnpm add @liquidcommerce/cloud-sdk\n```\n\n## Configuration\n\n### API Key Authentication\n\nThe LiquidCommerce API Key Authentication provides a secure method to obtain an access token for all other API calls to LiquidCommerce Services.\n\nExample using LiquidCommerce client:\n\n```typescript\n// The SDK automatically handles authentication\nconst client = await LiquidCommerce('YOUR_LIQUIDCOMMERCE_API_KEY', {\n googlePlacesApiKey: 'YOUR_GOOGLE_PLACES_API_KEY', // Required for address services\n env: LIQUID_COMMERCE_ENV.STAGE, // or PROD\n});\n```\n\n[Click Here For Manual Authentication](https://docs.liquidcommerce.cloud/authentication-api-integration/get-access-token)\n\n### Order API Authentication\n\nLiquidCommerce provides a separate authentication mechanism for Order API endpoints. The Order client uses Basic Authentication with a username and password.\n\nExample using LiquidCommerceOrders client:\n\n```typescript\nconst orderClient = await LiquidCommerceOrders({\n userID: 'YOUR_ORDER_API_USER_ID',\n password: 'YOUR_ORDER_API_PASSWORD',\n env: LIQUID_COMMERCE_ENV.STAGE, // or PROD\n});\n```\n\n[Click Here For Manual Authentication](https://docs.liquidcommerce.cloud/services/orders-api/authentication)\n\nNote: Order authentication credentials are required to access Order API. The SDK will return appropriate authentication errors if these credentials are missing or invalid.\n\n## Response Types\n\nAll API responses follow a consistent structure:\n\n```typescript\ninterface ApiResponse {\n statusCode: number;\n message: string;\n metadata: {\n languages: string[];\n timestamp: number;\n timezone: string;\n requestId: string;\n path: string;\n version: string;\n };\n data?: T; // Present in responses with data\n}\n```\n\n## Services and Usage\n\n### Auth\n\nWhile the SDK handles authentication automatically, you can also manually retrieve the authentication details:\n\n```typescript\n// Manually retrieve authentication details\ntry {\n const authDetails = await client.auth();\n console.log('Access Token:', authDetails.token);\n console.log('Expires In:', authDetails.exp);\n} catch (error) {\n console.error('Failed to get auth details:', error);\n}\n```\n\n### Address\n\nServices for address validation and lookup:\n\n```typescript\n// Address autocompletion\nconst autocompleteResponse = await client.address.autocomplete({\n input: '100 Madison Ave, New York',\n});\n\n// Response type: IApiResponseWithData\n// {\n// id: string;\n// description: string;\n// }\n\n// Get detailed address information\nconst detailsResponse = await client.address.details({\n id: 'ChIJd8BlQ2BZwokRjMKtTjMezRw',\n});\n\n// Response type: IApiResponseWithData\n// {\n// formattedAddress: string;\n// coords: {\n// lat: number;\n// long: number;\n// }\n// address: {\n// one: string,\n// two: string,\n// city\": string,\n// state: string,\n// zip: string,\n// country: \"US\"\n// }\n// }\n```\n\n### Catalog\n\nProduct catalog search and availability services:\n\n```typescript\n// Check product availability\nconst availabilityResponse = await client.catalog.availability({\n upcs: ['123456789012', '210987654321'], // UPC codes\n grouping: ['group1', 'group2'], // Optional group identifiers\n ids: ['id1', 'id2'], // Optional product IDs\n loc: {\n address: {\n one: '123 Main St',\n city: 'New York',\n state: 'NY',\n zip: '10001',\n },\n },\n shouldShowOffHours: true,\n});\n\n// Search catalog with filters\nconst searchResponse = await client.catalog.search({\n search: 'whiskey',\n // Requires a complete loc.address. When false or omitted, legacy ordering is used.\n deliveryFirst: true,\n pageToken: '',\n entity: '',\n page: 1,\n perPage: 20,\n orderBy: ENUM_ORDER_BY.PRICE,\n orderDirection: ENUM_NAVIGATION_ORDER_DIRECTION_TYPE.ASC,\n filters: [\n {\n key: ENUM_FILTER_KEYS.CATEGORIES,\n values: [ENUM_SPIRITS.WHISKEY],\n },\n {\n key: ENUM_FILTER_KEYS.PRICE,\n values: { min: 2000, max: 10000 }, // Prices in cents\n },\n {\n key: ENUM_FILTER_KEYS.AVAILABILITY,\n values: ENUM_AVAILABILITY_VALUE.IN_STOCK,\n },\n ],\n loc: {\n address: {\n one: '123 Main St',\n city: 'New York',\n state: 'NY',\n zip: '10001',\n country: 'US',\n },\n },\n});\n\n// Search-as-you-type suggestions (cheap per-keystroke endpoint; no facets,\n// availability or price — only the final token is prefix-matched)\nconst suggestions = await client.catalog.autocomplete({\n term: 'hendricks oasi',\n limit: 8, // 1–25, defaults to 10\n});\n// suggestions.data: [{ itemType: 'catalog', grouping: '...', name: \"Hendrick's Oasium Gin\", image?: '...' }]\n\n// Enumerate every product in your own catalog — for building a sitemap.\n// The partner comes from the API key, so there is no partner argument.\nfor await (const product of client.catalog.iterateProducts()) {\n console.log(product.grouping, product.upc); // upc is zero-padded: use it verbatim\n}\n\n// Or page manually. Terminate on `nextCursor`, NOT on an empty `items`:\n// products are dropped after a page is read, so a page can be empty and\n// still have successors — stopping there truncates the enumeration silently.\n// Page manually when you need to resume: `iterateProducts` keeps the cursor\n// to itself, so a page that fails mid-walk restarts the whole enumeration.\nlet cursor: string | undefined;\ndo {\n const page = await client.catalog.listProducts({ pageSize: 1000, cursor });\n for (const { grouping, upc } of page.data.items) {\n console.log(grouping, upc);\n }\n // counts: { inScope, emitted, droppedNoUpc, droppedUnresolvable }\n // `inScope - emitted` is how many of your products are currently unlinkable.\n console.log(page.data.counts);\n cursor = page.data.nextCursor;\n} while (cursor);\n```\n\n> The enumeration is availability-blind by design: it lists products whose page\n> exists, not products purchasable right now. Products whose barcode does not\n> resolve are dropped rather than published as dead URLs, so the total can fall\n> short of your assignment count — `counts` reports how many and why.\n\n#### Optional catalog composition capabilities\n\nThe SDK client provides `catalog.compose()` and `catalog.createLocationContext()`.\n`compose()` assembles product sections for homepages, category pages, or other\ndiscovery experiences through `POST /catalog/compose`. Cloud shares location\nresolution, availability, and offer selection across all sections in the request.\nThese members are optional in `ICatalogMethod` so existing custom catalog/client\nimplementations and typed mocks remain assignable without adding methods. Callers\nusing these capabilities must check for them first:\n\n```typescript\nif (typeof client.catalog.compose !== 'function') {\n throw new Error('This client does not support catalog composition');\n}\nconst composition = await client.catalog.compose({\n sections: [{ sectionId: 'whiskey', search: 'whiskey', perPage: 12 }],\n});\n```\n\nCheck `createLocationContext` the same way before calling it. Both methods require\nthe corresponding Cloud endpoints to be deployed. Existing catalog calls and the\n`LiquidCommerce()` factory signature are unchanged; upgrading alone does not enable\ncatalog composition.\n\n### Cart\n\nShopping cart management:\n\n```typescript\n// Create new cart\nconst newCart = await client.cart.get();\n\n// Retrieve existing cart\nconst existingCart = await client.cart.get('cart_id', true); // Second parameter for refresh\n\n// Update cart\nconst updatedCart = await client.cart.update({\n id: 'cart_id',\n items: [\n {\n partNumber: '123456789012_retailer_id', // Required: {UPC}_{retailerId}\n quantity: 2,\n fulfillmentId: 'fulfillment_id',\n engravingLines: ['Line 1', 'Line 2'], // Optional\n scheduledFor: '2024-12-25', // Optional\n },\n ],\n loc: {\n address: {\n one: '123 Main St',\n city: 'New York',\n state: 'NY',\n zip: '10001',\n },\n },\n promoCode: 'DISCOUNT10', // Optional\n giftCards: ['GC123456'], // Optional\n});\n```\n\n### User\n\nUser profile and preferences management:\n\n```typescript\n// Create/update user session\nconst userSession = await client.user.session({\n email: 'user@example.com',\n firstName: 'John',\n lastName: 'Smith',\n phone: '2125551234',\n company: 'Company Inc',\n profileImage: 'https://...',\n birthDate: '1990-01-01',\n id: 'user_id', // Existing user identifier (for updates only), email becomes optional\n});\n\n// Fetch user by ID or email\nconst userData = await client.user.fetch('user_id_or_email');\n\n// Address management\nconst newAddress = await client.user.addAddress({\n userId: 'user_id',\n placesId: 'google_places_id', // Optional if providing address details\n one: '100 Madison St',\n two: 'Apt 4B',\n city: 'New York',\n state: 'NY',\n zip: '10004',\n country: 'US',\n lat: 40.7128, // Optional\n long: -74.006, // Optional\n type: ENUM_ADDRESS_TYPE.SHIPPING,\n isDefault: true,\n});\n\nconst updatedAddress = await client.user.updateAddress({\n // Same parameters as addAddress\n});\n\n// Payment methods\nconst newPayment = await client.user.addPayment({\n customerId: 'customer_id',\n paymentMethodId: 'payment_method_id',\n isDefault: true,\n});\n\nconst updatedPayment = await client.user.updatePayment({\n customerId: 'customer_id',\n paymentMethodId: 'payment_method_id',\n isDefault: true, // Required for updates\n});\n\n// Data removal\nawait client.user.purge('user_id_or_email');\nawait client.user.purgeAddress('address_id');\nawait client.user.purgePayment('customer_id', 'payment_id');\n```\n\n### Payment Element\n\nThe Payment Element is a secure and modern UI component for collecting payment details. It simplifies PCI compliance by handling all sensitive information within an iframe.\n\n#### Prerequisites\n\nBefore mounting the Payment Element, you must create a payment session. This can be tied to a user, cart, or checkout.\n\n```typescript\n// Create a payment session to get a client secret\nconst paymentSession = await client.user.paymentSession({\n // Optionally link to a cart, checkout, or customer\n // cartId: 'your_cart_id',\n // checkoutToken: 'your_checkout_token',\n // customerId: 'your_customer_id',\n // customerEmail: 'your_customer_id',\n});\n\nconst { key, secret } = paymentSession.data.session;\n```\n\n#### Integration\n\n1. **Initialize and Mount**\n\n The `LiquidCommercePaymentElement` function creates and manages the UI component.\n\n ```typescript\n // Initialize the payment element\n const paymentElement = LiquidCommercePaymentElement({\n session: {\n key, // Public key from payment session\n secret, // Client secret from payment session\n },\n });\n\n // Mount the element to a container in your DOM\n await paymentElement.mount({\n elementId: 'payment-element-container',\n appearance: {\n theme: 'night', // 'stripe' | 'night' | 'flat'\n },\n elementOptions: {\n layout: 'tabs', // 'tabs' | 'accordion' | 'auto'\n },\n });\n ```\n\n2. **Generate a Confirmation Token**\n\n Once the user has filled out the payment form, create a confirmation token. This token securely represents the payment details.\n\n ```typescript\n const result = await paymentElement.createConfirmationToken();\n\n if (result.token) {\n // Token successfully created\n const confirmationToken = result.token;\n // Use this token to complete the checkout or save the payment method\n } else {\n // Handle error\n console.error(result.message);\n }\n ```\n\n3. **Confirm the Payment Session**\n\n Use the confirmation token to finalize the payment and retrieve the payment method details.\n\n ```typescript\n const confirmation = await client.user.confirmPaymentSession(confirmationToken);\n\n if (confirmation.data) {\n const paymentMethod = confirmation.data;\n // Now you have the payment method ID, card details, etc.\n // e.g., paymentMethod.id, paymentMethod.card.brand\n }\n ```\n\n4. **Lifecycle Management**\n\n Properly manage the element's lifecycle to ensure a smooth user experience and resource cleanup.\n\n ```typescript\n // Listen to events\n paymentElement.subscribe('ready', () => {\n console.log('Payment element is ready.');\n });\n\n paymentElement.subscribe('change', (event) => {\n // Handle form state changes (e.g., enable/disable submit button)\n });\n\n // Clean up when the element is no longer needed\n paymentElement.unmount();\n paymentElement.destroy();\n ```\n\n### Legacy Payment\n\nThe legacy payment system uses a previous version of our payment integration. For new integrations, we strongly recommend using the [Payment Element](#payment-element) for a more secure and flexible solution.\n\n#### Prerequisites\n\n1. User Session Creation:\n\n```typescript\n// First create or get a user session\nconst userSession = await client.user.session({\n email: 'user@example.com',\n // ... other user details\n});\n\n// The session response includes necessary payment credentials\nconst { setupIntent, publicKey } = userSession.data.session;\n```\n\n#### Payment Element Integration\n\n```typescript\n// Initialize payment form using session credentials\nawait client.payment.mount({\n clientSecret: userSession.data.session.setupIntent, // Required: from session\n key: userSession.data.session.publicKey, // Required: from session\n elementId: 'payment-element-container', // Your DOM element ID\n appearance: {\n theme: 'night', // 'stripe' | 'night' | 'flat'\n },\n elementOptions: {\n layout: 'tabs', // 'tabs' | 'accordion' | 'auto'\n },\n});\n\n// Monitor payment element state\nclient.payment.subscribe('ready', () => {\n // Element is ready to accept input\n});\n\nclient.payment.subscribe('change', (event) => {\n const { complete, empty, value } = event;\n // Handle validation state changes\n});\n\n// Process payment when ready\nconst tokenResult = await client.payment.generateToken();\n\n// Handle the result\nif ('error' in tokenResult) {\n const { type, message, code } = tokenResult.error;\n // type can be: 'validation_error' | 'api_error' | 'client_error' | 'confirm_error'\n} else {\n // Use tokenResult.id for checkout completion or saving payment method\n const { id, card } = tokenResult;\n}\n\n// Always clean up when done\nclient.payment.unmount();\nclient.payment.destroy();\n```\n\n#### Security Considerations\n\n1. **PCI Compliance**: The payment element handles card data securely within an iframe, ensuring your application never directly touches sensitive payment information.\n\n2. **Token-Based**: All payment data is tokenized - you only receive secure tokens that can't be used to retrieve the original card details.\n\n3. **Single Use**: Payment tokens are single-use and expire after a short time period.\n\n4. **Domain Validation**: Payment elements will only work on domains that have been pre-registered with your account.\n\n#### Best Practices\n\n1. **Error Handling**: Always implement proper error handling:\n\n```typescript\ntry {\n const token = await client.payment.generateToken();\n if ('error' in token) {\n switch (token.error.type) {\n case 'validation_error':\n // Handle invalid card data\n break;\n case 'api_error':\n // Handle API/network issues\n break;\n case 'client_error':\n // Handle setup/configuration issues\n break;\n case 'confirm_error':\n // Handle payment confirmation failures\n break;\n }\n }\n} catch (error) {\n // Handle unexpected errors\n}\n```\n\n2. **Cleanup**: Always clean up payment elements when done:\n\n- When navigation away from payment page\n- After successful payment\n- After failed payment attempt\n- Before unmounting payment component\n\n3. **Event Handling**: Monitor element state for better user experience:\n\n```typescript\nclient.payment.subscribe('change', (event) => {\n // Update UI based on validation state\n const { complete, empty } = event;\n submitButton.disabled = !complete || empty;\n});\n\nclient.payment.subscribe('loaderror', (event) => {\n // Handle element loading failures\n console.error('Payment element failed:', event.error);\n});\n```\n\n#### Responsive Design\n\nThe payment element automatically adapts to:\n\n- Mobile and desktop viewports\n- Right-to-left languages\n- Dark/light themes\n- Different container sizes\n\n#### Testing Cards\n\nWhen testing payments in staging environment, use these test cards:\n\n```\n// Test Visa Card\nCard Number: 4242 4242 4242 4242\nExpiry: Any future date\nCVC: Any 3 digits\nZIP: Any 5 digits\n\n// Test Mastercard\nCard Number: 5555 5555 5555 4444\nExpiry: Any future date\nCVC: Any 3 digits\nZIP: Any 5 digits\n\n// Example test card usage:\n/*\n Card: 4242 4242 4242 4242\n Expiry: 12/29\n CVC: 123\n ZIP: 10001\n*/\n```\n\nThese cards will be accepted in test mode and will simulate successful payments. They should only be used in the staging environment, never in production.\n\n**Important Notes:**\n\n- These cards work only in test/staging environment\n- Real cards will be declined in test mode\n- Test cards will be declined in production\n- All test transactions use simulated funds\n- Use test credentials in staging environment\n- Never use production credentials in development\n- Test all error scenarios\n- Verify proper cleanup implementation\n- Test on multiple devices and browsers\n\n### Checkout\n\nCheckout process management:\n\n```typescript\n// Prepare checkout\nconst preparedCheckout = await client.checkout.prepare({\n cartId: 'cart_id',\n customer: {\n id: 'customer_id', // Optional\n email: 'customer@example.com',\n firstName: 'John',\n lastName: 'Smith',\n phone: '2125551234',\n birthDate: '1990-01-01',\n },\n hasAgeVerify: true,\n billingAddress: {\n firstName: 'John',\n lastName: 'Smith',\n email: 'billing@example.com',\n phone: '2125551234',\n one: '123 Main St',\n two: 'Apt 4B',\n city: 'New York',\n state: 'NY',\n zip: '10001',\n country: 'US',\n },\n hasSubstitutionPolicy: true,\n isGift: true,\n billingSameAsShipping: false,\n giftOptions: {\n message: 'Happy Birthday!',\n recipient: {\n name: 'Jane Smith',\n email: 'jane@example.com',\n phone: '2125555678',\n },\n },\n marketingPreferences: {\n canEmail: true,\n canSms: true,\n },\n deliveryTips: [\n {\n fulfillmentId: 'fulfillment_id',\n tip: 500, // Amount in cents\n },\n ],\n deliveryInstructions: [\n {\n fulfillmentId: 'fulfillment_id',\n instructions: \"\", // 250 Max characters\n },\n ],\n acceptedAccountCreation: true,\n scheduledDelivery: '2024-12-25T14:00:00Z',\n promoCode: 'DISCOUNT10', // Optional\n giftCards: ['GC123456'], // Optional\n});\n\n// Complete checkout\nconst completedCheckout = await client.checkout.complete({\n token: preparedCheckout.token,\n payment: 'payment_id',\n});\n```\n\n#### Checkout Payment\n\nFor direct checkout payments, the flow is similar but uses the checkout session:\n\n```typescript\n// 1. First prepare the checkout\nconst preparedCheckout = await client.checkout.prepare({\n cartId: 'cart_id',\n // ... other checkout details\n});\n\n// 2. Initialize payment element with checkout session\nconst paymentElement = LiquidCommercePaymentElement({\n session: {\n key: preparedCheckout.data.payment.publicKey, // From checkout prepare response\n secret: preparedCheckout.data.payment.clientSecret, // From checkout prepare response\n }\n});\n\n// 3. Mount the element\nawait paymentElement.mount({\n elementId: 'payment-element-container',\n appearance: { theme: 'night' },\n elementOptions: { layout: 'tabs' },\n});\n\n// 4. Handle payment element events and create confirmation token\nconst result = await paymentElement.createConfirmationToken();\n\nif (result.token) {\n // 5. Confirm the payment collected with the confirmation token\n const confirmation = await client.user.confirmPaymentSession(confirmationToken);\n\n if (confirmation?.data?.id) {\n // 6. Complete checkout with the confirmation token\n const completedCheckout = await client.checkout.complete({\n token: preparedCheckout.data.token,\n payment: confirmation?.data?.id,\n });\n }\n}\n\n// 7. Clean up\npaymentElement.unmount();\npaymentElement.destroy();\n```\n\n### Orders\n\nProvides secure access to order data throughout the finalized states of the order lifecycle within the LiquidCommerce ecosystem.\n\n```typescript\nconst orderClient = await LiquidCommerceOrders({\n userID: 'YOUR_ORDER_API_USER_ID',\n password: 'YOUR_ORDER_API_PASSWORD',\n env: LIQUID_COMMERCE_ENV.STAGE, // or PROD\n});\n\n// Fetch order details by ID or number\nconst orderResponse = await orderClient.order.fetch(/* reference id or order number */);\n```\n\n[Click here to access the docs for the order response structure](https://docs.liquidcommerce.cloud/types/order)\n\n### Webhook\n\nWebhook test services:\n\n```typescript\n// Test webhook endpoint\nconst webhookTestResult = await client.webhook.test(/* endpoint */);\n\n// Response is a simple boolean indicating success or failure\n// true = webhook test was successful\n// false = webhook test failed\n```\n\n## Error Handling\n\nThe SDK throws errors for various scenarios. Always wrap SDK calls in try-catch blocks:\n\n```typescript\ntry {\n const result = await client.someMethod();\n} catch (error) {\n console.error('Operation failed:', error.message);\n // Handle specific error cases\n}\n```\n\nCommon error scenarios:\n\n- Authentication failures\n- Invalid parameters\n- Network errors\n- Resource not found\n- Rate limiting\n- Validation errors\n\n## Price Handling\n\nAll monetary values in the SDK are handled in cents (the smallest currency unit). For example:\n\n- $10.00 is represented as 1000\n- $5.99 is represented as 599\n- $0.50 is represented as 50\n\n## Documentation\n\nFor more detailed information about each method and its parameters, please refer to our [official documentation](https://docs.liquidcommerce.cloud).\n","readmeFilename":"README.md"}
![\"LiquidCommerce](\"https://storage.googleapis.com/liquid-platform/repo_lc_dark.webp\")
\n