Skip to content

Core SDK: API Reference

Beta SDK

These SDKs are currently in beta. APIs may change before stable release.

Complete API reference for @rebuy/core-sdk.

RebuySDK

Constructor Options

Option Type Required Description
apiKey string Yes Your Rebuy API key
apiHost string No API host URL (defaults to https://rebuyengine.com)
debug boolean No Enable debug logging (defaults to false)

Example:

import { RebuySDK } from '@rebuy/core-sdk';

const sdk = new RebuySDK({
    apiKey: 'your-api-key',
    debug: process.env.NODE_ENV === 'development',
});

Modules

sdk.products

Methods for fetching product recommendations.

Method Signature Description
getRecentlyViewed (options): Promise<Product[]> Get recently viewed products
getRecommended (options): Promise<Product[]> Get recommended products
getTopSellers (options): Promise<Product[]> Get top selling products
getTrending (options): Promise<Product[]> Get trending products
getPurchased (options): Promise<Product[]> Get previously purchased products
getCollections (body): Promise<Product[]> Get products from a list of collections
getStatic (options): Promise<Product[]> Get a static list of products
getSimilar (options): Promise<Product[]> Get similar products
fetchFromDataSource (dataSourceId, context): Promise<Product[]> Fetch products from a custom Data Source

Examples:

// Standard endpoints
const topSellers = await sdk.products.getTopSellers({ limit: 10 });
const trending = await sdk.products.getTrending({ limit: 5 });
const similar = await sdk.products.getSimilar({
    limit: 4,
    shopify_product_ids: ['123']
});

// Custom Data Source
const products = await sdk.products.fetchFromDataSource(1234, {
    cart: cartObject,
    limit: 6,
});

sdk.tracking

Methods for tracking user behavior.

Method Signature Description
productView (productId: string): Promise<void> Track a product view event

Example:

await sdk.tracking.productView('product-123');

sdk.cart

Methods for reading cart state.

Method Signature Description
get (): Promise<ShopifyCart> Get current cart from Shopify
createDataSourceContext (cart): RebuyCartContext Transform a cart object into a context for Data Sources

Read-Only Cart

The cart module is intentionally read-only. Cart mutations should be handled through your existing cart system (e.g., Shopify's Cart API). This design allows the SDK to read cart state for features like recommendations and GWP rules without prescribing how cart operations should be implemented.

Example:

const cart = await sdk.cart.get();
const context = sdk.cart.createDataSourceContext(cart);

RebuyContextBuilder

The RebuyContextBuilder class provides a fluent API for creating context objects.

Constructor

import { RebuyContextBuilder } from '@rebuy/core-sdk';

const builder = new RebuyContextBuilder(sdk);

Methods

Method Signature Description
merge (context: Partial<RebuyCartContext>): this Merge an existing context object
withCart (cart: SupportedCart): this Add cart data using the SDK's internal transformer
withProduct (product: { id: string }): this Add a product's ID (chainable for multiple products)
withCustomer (customer: { id: string \| number; tags?: string[] }): this Add customer data
withUrl (url: string \| URL): this Extract URL path and parameters
withLocation (countryCode: string): this Add country code (ISO 3166-1 alpha-2)
withLanguage (language: string): this Add language code (ISO 639-1)
build (): RebuyCartContext Return the final context object

Example:

const context = new RebuyContextBuilder(sdk)
    .withCart(cartObject)
    .withProduct({ id: 'gid://shopify/Product/123' })
    .withCustomer({ id: 456, tags: ['vip', 'wholesale'] })
    .withUrl('https://shop.com/products?sort=price')
    .withLocation('US')
    .withLanguage('en')
    .build();

const products = await sdk.products.fetchFromDataSource('pdp-recommendations', context);

Configuration

const sdk = new RebuySDK({
    apiKey: 'your-api-key',
    debug: process.env.NODE_ENV === 'development',
});

Error Handling

Wrap SDK calls in try/catch blocks to handle errors:

try {
    const products = await sdk.products.getTopSellers({ limit: 5 });
} catch (error) {
    console.error('SDK Error:', error.message);
}

TypeScript Support

The SDK is built with TypeScript and provides full type safety.

import type { Product } from '@rebuy/core-sdk';

const products: Product[] = await sdk.products.getTopSellers({ limit: 5 });
See something that needs updating? Suggest an edit