POS SDK Methods Reference

Complete reference for the Commerce Engine POS SDK (@commercengine/pos). This SDK provides specialized functionality for Point of Sale terminals, retail environments, and in-store transactions.

SDK Setup

Installation

npm install @commercengine/pos

Basic Configuration

import { PosSDK, Environment } from "@commercengine/pos";

const pos = new PosSDK({
  storeId: "your-store-id",
  environment: Environment.Production, // or Environment.Staging
  apiKey: "your-api-key", // Required for authentication
});

Recommended Configuration with Token Storage

import { PosSDK, MemoryTokenStorage, Environment } from "@commercengine/pos";

const pos = new PosSDK({
  storeId: "your-store-id",
  environment: Environment.Production,
  apiKey: "your-api-key",

  // Token storage for POS devices (usually memory-based)
  tokenStorage: new MemoryTokenStorage(),
  
  // Optional: Default headers for all requests
  defaultHeaders: {
    customer_group_id: "01JHS28V83KDWTRBXXJQRTEKA0", // For pricing and promotions
  },
  
  // Optional: Debug mode for development
  debug: true,
  logger: console.log,
  
  // Optional: Token lifecycle callbacks
  onTokensUpdated: (accessToken, refreshToken) => {
    console.log("POS device authenticated!");
  },
  onTokensCleared: () => {
    console.log("POS device logged out");
  },
});

POS-Specific Features

• Device Authentication: Specialized login flow for POS terminals
• Device Pairing: Connect terminals using pairing codes
• Multi-Channel OTP: Support for email, SMS, and WhatsApp authentication
• Unified Cart Management: Single API for all cart operations
• Retail-Focused Catalog: Optimized for in-store product browsing
• Offline-Ready: Designed for reliable terminal operations

Total POS SDK Methods: 60

POS SDK Methods

SDK Usage: pos.* (Single unified client)

Authentication

Methods: 7

SDK Method	HTTP Method	API Path
loginWithEmail	POST	/pos/auth/login/email
loginWithPhone	POST	/pos/auth/login/phone
loginWithWhatsapp	POST	/pos/auth/login/whatsapp
logout	POST	/pos/auth/logout
pairDevice	POST	/pos/auth/pair-device
refreshAccessToken	POST	/pos/auth/refresh-token
verifyOtp	POST	/pos/auth/verify-otp

Cart Management

Methods: 11

SDK Method	HTTP Method	API Path
createCart	POST	/pos/carts
listCoupons	GET	/pos/carts/available-coupons
listPromotions	GET	/pos/carts/available-promotions
getUserCart	GET	/pos/carts/users/{user_id}
getCart	GET	/pos/carts/{id}
deleteCart	DELETE	/pos/carts/{id}
createCartAddress	POST	/pos/carts/{id}/address
evaluateCoupons	GET	/pos/carts/{id}/evaluate-coupons
evaluatePromotions	GET	/pos/carts/{id}/evaluate-promotions
updateCart	POST	/pos/carts/{id}/items
updateCartCustomer	POST	/pos/carts/{id}/update-customer

Coupons & Promotions

Methods: 2

SDK Method	HTTP Method	API Path
applyCoupon	POST	/pos/carts/{id}/coupon
removeCoupon	DELETE	/pos/carts/{id}/coupon

Credit & Loyalty

Methods: 4

SDK Method	HTTP Method	API Path
redeemCreditBalance	POST	/pos/carts/{id}/credit-balance
removeCreditBalance	DELETE	/pos/carts/{id}/credit-balance
redeemLoyaltyPoints	POST	/pos/carts/{id}/loyalty-points
removeLoyaltyPoints	DELETE	/pos/carts/{id}/loyalty-points

Fulfillment

Methods: 1

SDK Method	HTTP Method	API Path
updateFulfillmentPreference	POST	/pos/carts/{id}/fulfillment-preference

Orders

Methods: 6

SDK Method	HTTP Method	API Path
getOrderDetail	GET	/pos/orders/{order_number}
listOrderActivity	GET	/pos/orders/{order_number}/activity
getOrderInvoice	GET	/pos/orders/{order_number}/invoice
getPaymentStatus	GET	/pos/orders/{order_number}/payment-status
getOrderReceipt	GET	/pos/orders/{order_number}/receipt
getOrderShipments	GET	/pos/orders/{order_number}/shipments

Catalog

Methods: 14

SDK Method	HTTP Method	API Path
listCategories	GET	/pos/catalog/categories
listInventories	GET	/pos/catalog/inventories
listInventoryActivities	GET	/pos/catalog/inventories/activites
getInventoryDetail	GET	/pos/catalog/inventories/detail
listProducts	GET	/pos/catalog/products
listCrosssellProducts	GET	/pos/catalog/products/cross-sell
searchProducts	POST	/pos/catalog/products/search
listSimilarProducts	GET	/pos/catalog/products/similar
listUpsellProducts	GET	/pos/catalog/products/up-sell
getProductDetail	GET	/pos/catalog/products/{product_id_or_slug}
listProductReviews	GET	/pos/catalog/products/{product_id}/reviews
listProductVariants	GET	/pos/catalog/products/{product_id}/variants
getVariantDetail	GET	/pos/catalog/products/{product_id}/variants/{variant_id}
listSkus	GET	/pos/catalog/skus

Other

Methods: 15

SDK Method	HTTP Method	API Path
getCustomers	GET	/pos/customers
getCustomer	GET	/pos/customers/{id}
listDevices	GET	/pos/devices
claimDevice	POST	/pos/devices/{id}/claim
unclaimDevice	POST	/pos/devices/{id}/unclaim
getFulfillmentOptions	POST	/pos/fulfillment-options
listLocations	GET	/pos/locations
listPaymentOptions	GET	/pos/payments/payment-options
listShipments	GET	/pos/shipping/shipments
checkInventory	GET	/pos/shipping/shipments/{order_number}/check-inventory
refundShortfall	POST	/pos/shipping/shipments/{order_number}/refund-shortfall
getShipment	GET	/pos/shipping/shipments/{reference_number}
getShipmentInvoice	GET	/pos/shipping/shipments/{reference_number}/invoice
updateShipment	PUT	/pos/shipping/shipments/{reference_number}/manual-update
getUser	GET	/pos/users/{id}

---

Auto-generated from SDK source code and OpenAPI specifications