Salesive API Axios Client

Typed Axios wrappers for the Salesive Storefront API. Ship authentication, cart, wishlist, orders, banners, blogs, products, and shipping flows with a single lightweight SDK.

For complete endpoint details, visit the Salesive API reference.

Features

• 🛒 Shopper authentication helpers (ghost account, OTP verification, user lookup).
• 📦 Cart and wishlist mutation utilities.
• 🛍️ Order checkout and shipment management.
• 🏷️ Catalog access for products, categories, and blogs.
• 🚚 Shipping rate, shipment, and address management with geocoding support.
• 🔌 Smart environment resolution: works across Vite, Next.js, Nuxt, CRA, and Node.

Installation

npm install salesive-api-axios
# or
yarn add salesive-api-axios
# or
pnpm add salesive-api-axios
# or
bun add salesive-api-axios

Environment Variables

The client auto-detects configuration from the first defined key in each group:

| Purpose | Keys (checked in order) | | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | Shop ID | VITE_SALESIVE_SHOP_ID, NEXT_PUBLIC_SALESIVE_SHOP_ID, REACT_APP_SALESIVE_SHOP_ID, NUXT_PUBLIC_SALESIVE_SHOP_ID, SALESIVE_SHOP_ID | | API Key | VITE_SALESIVE_API_KEY, NEXT_PUBLIC_SALESIVE_API_KEY, REACT_APP_SALESIVE_API_KEY, NUXT_PUBLIC_SALESIVE_API_KEY, SALESIVE_API_KEY |

When running in the browser, the client also falls back to localStorage.SALESIVE_SHOP_ID before sending requests, so the active shop can be swapped at runtime without rebuilding.

The API key is injected as an Authorization bearer token when present. A locally stored SALESIVE_ACCESS_TOKEN automatically overrides the API key.

Local Storage Behavior

| Key | Purpose | | ----------------------- | ------------------------------------------------------------------------------------- | | SALESIVE_ACCESS_TOKEN | Persisted access token returned from either ghost creation or OTP verification. | | SALESIVE_AUTH_MODE | Tracks whether the current token belongs to a GHOST or authenticated USER. | | SALESIVE_SHOP_ID | Optional runtime override for the x-shop-id header when a browser env is available. |

auth.createGhost() stores SALESIVE_AUTH_MODE="GHOST" while auth.verify() stores "USER". The interceptor only clears tokens when auth.logout() is invoked and the mode is USER, allowing guest sessions to survive until an upgrade.

Quick Start

import { auth, cart, wishlist, orders, coupon } from "salesive-api-axios";

async function checkout() {
    // 1. Create a ghost customer and send OTP
    await auth.createGhost();

    // 2. Build the cart for the shopper before authentication
    await cart.addItem({ productId: "prod_123", quantity: 1 });
    await cart.addItem({
        productId: "prod_456",
        variantId: "variant_blue",
        quantity: 2,
    });

    // 3. Add items to wishlist for later
    await wishlist.addItem({ productId: "prod_789" });

    // 4. Authenticate (trigger OTP flow; verify in your UI as needed)
    await auth.checkUser({ email });
    await auth.authenticate({ email, name, phone });
    await auth.verify({ email, otp });

    // 5. Convert the cart into an order once authentication succeeds
    const { data } = await orders.createFromCart();

    // 6. Optionally apply a coupon to the resulting order
    await coupon.apply({ orderId: data?.data?.id, code: "SUMMER20" });
    return data;
}

API Overview

All helpers return an AxiosPromise, allowing standard Axios usage.

auth

| Method | Description | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- | | createGhost() | POST /auth/ghost – provision an anonymous shopper profile and persist a guest token. | | authenticate(payload) | POST /auth/authenticate with { email, name?, phone? } – trigger OTP delivery while optionally seeding profile context. | | resendOtp(payload) | POST /auth/resend-otp with { email } – resend OTP for the same shopper. | | verify(payload) | POST /auth/verify with { email, otp } – confirm the OTP, upgrade the session to USER, and persist the token. | | checkUser(payload) | POST /auth/check-user with { email } – determine whether the shopper already exists. | | isLoggedIn() | Returns true when SALESIVE_ACCESS_TOKEN exists and the auth mode is USER. | | logout() | Removes persisted credentials when the current mode is USER, leaving ghost sessions intact. |

orders

| Method | Description | | -------------------------- | --------------------------------------------------------------------------------------------------------------------- | | createFromCart(payload?) | POST /orders/from-cart – promote cart contents to an order. Supports product IDs, variant tuples, and cart indices. | | list(params?) | GET /orders – fetch orders with filters like status, totals, and date range. | | addShipment(payload) | POST /orders/add-shipment – add shipment details to an order with orderId, shippingAddressId, and shippingOptionId. |

cart

| Method | Description | | ------------------------------------------------------ | ----------------------------------------------------------------------------------- | | get() | GET /cart – retrieve the current cart snapshot. | | addItem(payload) | POST /cart – add a product or variant with productId, variantId?, quantity. | | updateItemQuantity(productId, payload) | PATCH /cart/{productId} – change base item quantity. | | updateVariantQuantity(productId, variantId, payload) | PATCH /cart/{productId}/{variantId} – change variant quantity. | | removeItem(productId) | DELETE /cart/{productId} – remove a base item. | | removeVariant(productId, variantId) | DELETE /cart/{productId}/{variantId} – remove a variant line. | | clear() | DELETE /cart – empty the cart. |

banner

| Method | Description | | ---------------------------- | ------------------------------------------------------------- | | list(params?) | GET /banner – list banners with optional pagination/search. | | getById(bannerId, params?) | GET /banner/{id} – fetch a specific banner. |

blogs

| Method | Description | | -------------------------- | ------------------------------------------------ | | list(params?) | GET /blogs – retrieve blog posts. | | getById(blogId, params?) | GET /blogs/{id} – fetch a single blog article. |

products

| Method | Description | | ------------------------------------- | ------------------------------------------------------------------- | | list(params?) | GET /products – fetch products with pagination/search. | | getById(productId, params?) | GET /products/{id} – retrieve product details. | | listCategories(params?) | GET /products/category – list product categories. | | listByCategory(categoryId, params?) | GET /products/category/{categoryId} – products within a category. |

shipping

| Method | Description | | ---------------------- | ------------------------------------------------------------------------- | | getOptions(params) | GET /shipping/options – retrieve shipping options for an address/order. | | getShipments(params) | GET /shipping/shipments – list generated shipments for an order. |

shippingAddress

| Method | Description | | ------------------------- | --------------------------------------------------------------------------------------------- | | list(params?) | GET /shipping-address – paginate authenticated customer addresses. | | getDefault() | GET /shipping-address/default – retrieve the default address. | | coordsToAddress(params) | GET /shipping-address/coords-to-address – convert lat/lng coordinates to formatted address. | | autocomplete(params) | GET /shipping-address/autocomplete – autocomplete address search with partial text input. | | save(payload) | POST /shipping-address – upsert an address body including name, phone, location, and flags. |

wishlist

| Method | Description | | ------------------------------------- | ---------------------------------------------------------------- | | get() | GET /wishlist – retrieve the current wishlist snapshot. | | addItem(payload) | POST /wishlist – add a product or variant to the wishlist. | | removeItem(productId) | DELETE /wishlist/{productId} – remove a product from wishlist. | | removeVariant(productId, variantId) | DELETE /wishlist/{productId}/{variantId} – remove a variant. | | clear() | DELETE /wishlist – empty the wishlist. |

coupon

| Method | Description | | ----------------- | ---------------------------------------------------------------------------------------------- | | verify(payload) | POST /coupons/verify – validate a coupon code, optionally with { orderId } for auth flows. | | apply(payload) | POST /coupons/apply – apply a coupon to an order with { orderId, code }. |

Low-level Axios Instance

api exposes the configured Axios instance used by all modules. Use it for endpoints not yet wrapped:

import { api } from "salesive-api-axios";

const { data } = await api.get("/custom-endpoint", { params: { foo: "bar" } });

TypeScript Support

The package ships .d.ts definitions through the bundled build, so TypeScript consumers receive strong typing for every helper.

Contributing

1. Clone the repository and install dependencies.
2. Run npm run dev to build in watch mode.
3. Execute npm run lint before submitting pull requests.

License

MIT © Salesive Team