@thread-together/ts-bigcommerce

BigCommerce Integration

A BigCommerce SDK written in typescript.

Documentation

• BigCommerce API Docs - examples on how to use the BigCommerce API
• BigCommerce API Reference - schema definitions for HTTP requests and responses

Other Libraries

Two open source libraries for the BigCommerce API were evaluated.

• https://www.npmjs.com/package/bigcommerce - This library is version 0.0.0 and published 5 years ago.
• https://www.npmjs.com/package/node-bigcommerce - This library is being used by Conversio and is actively maintained. However, it does not have support for Typescript.

Usage

Each API has request types, response types and series of functions to interact with that API. This library makes use of the Either type for API responses. Per convention, Left is an error and Right is success.

Example:

import { BrandRequest, createBrand } from 'ts-bigcommerce';

const brand: BrandRequest = { name: 'Some unique brand name' };
createBrand(brand).then(result => {
   if (result.isLeft()) {
      console.log(result.value);
      throw new Error('Failed to create brand');
   } else {
      console.log(`Brand id is ${result.value.data.id}`);
   }
});

More examples for how to use this library can be found in the tests directory.

API Documentation

Products API

BigCommerce has three main concepts around an item:

• Brand - This is basically the name of the brand. BigCommerce will assign a brand id to the brand.
• Product - A product contains top level information, such as name. Required fields are name, type, weight, categories and price. The type is either physical or digital. We are selling clothes, so the type will always be physical. I will elide this from examples below.
• Variants - A product can contain multiple variants. Variants are things like color, size and inseam.

BigCommerce organizes these concepts in the following way: Brand -> Product -> Variant. Most fashion brands organize items in the following way: Brand -> Style -> Sku. These sort of map 1:1, but BigCommerce gives more flexibility.

Simple vs Complex Products

The SKU can be assigned at the Product level (known as a Simple Product) or at the Variant level (known as Complex Product).

Simple Product Example

Brand { name: Urban Decay } -> Product { name: Eyeshadow Palette, price: 20.00, weight: 1, sku: 1234 }

Notice that the SKU is attached to the Product and the price is specified. Many beauty products have no variants, such as size or color.

Complex Product Example

Brand { name: Theory } -> Product { name: Textured Linen Classic Blazer, price: 0.00, weight: 1 } -> Variant { size: 4, color: Beige Clay Multi, price: 495.00, sku: 5678 }

Notice that the SKU is attached to the Variant. Almost all apparel products have size and color variants. Also notice that the price on the Product is not specified, but the price on the Variant is. I want to establish a convention that the price is always set at the lowest level.

Brand { name: AG Jeans } -> Product { name: The Farrah Skinny Ankle, price: 0.00, weight: 1 } -> Variant { size: 24, color: 4 Years Deep Willows, inseam: 28, price: 215.00, sku: EMP177704YDPW }

Notice that the SKU is attached to the Variant and is alphanumeric. Some apparel products, such as jeans, have unique variants. In this case, inseam is specified on the Variant. Other examples are heel height and shoe width.

Categories

Every Product must specify one or more categories. BigCommerce allows for the creation of a tree of categories and each of those categories is referenced through a category id. Each category can contain a lot of information. In these examples are focused on the category name and category id. When creating an item, the leaf category id is specified.

Single Category Example

Category:

Women { id: 1 } -> Clothing { id: 2 } -> Apparel { id: 3 }.

Product:

Brand { name: Theory } -> Product { name: Textured Linen Classic Blazer, categories: [ 3 ], price: 0.00, weight: 1 } -> Variant { size: 4, color: Beige Clay Multi, price: 495.00, sku: 5678 }

Multiple Category Example

A Product may belong to multiple categories. Consider kids shoes that either boys or girls could wear.

Categories:

Shoes { id: 10 } -> Girls' Shoes { id: 11 } -> Sneakers { id: 12 } Shoes { id: 10 } -> Boys' Shoes { id: 15 } -> Sneakers { id: 16 }

Product:

Brand { name: PUMA } -> Product { name: Smash V2 Sneaker, categories: [ 12, 16 ], price: 0.00, weight: 1 } -> Variant { size: 4, color: Red, price: 35.00, sku: 9012 }

Contributing

Development

• Run the typescript compiler in watch mode: npm run build -- --watch
• Make changes to the code and verify it compiles
• Verify changes work by running the tests

Testing

The tests require a .env environment file to provide required BigCommerce API authentication values. Copy .env.example to .env and fill in the values with real API credentials.

To run the tests, type npm test.

• Note: The tests currently assume category id 32 exists.

Publishing

The ts-bigcommerce package is is a file dependency for other packages. Publish changes by running npm build.