NAV

Introduction

Welcome to the Stratocart documentation.

stratocart.js

<script src="https://js.stratocart.com/latest.js"></script>
<script>
    window.Stratocart && window.Stratocart.init("shop/id");
</script>

stratocart.js is a small Javascript library that will help seamlessly integrate the shopping cart and checkout flow into a website.

Getting started is as easy:

  1. Visit https://stratocart.com to get a shop ID.
  2. Install stratocart.js via script tag.
// opens the cart
Stratocart.open();

// closes the cart
Stratocart.close();

Now, let's use this code to open/close the shopping cart element.

Whoa! That's simple!

Add an item

Stratocart.addItem({
    id: "unique-product-id",
    name: "My nice Product",
    quantity: 1,
    price: 7999,
})
    .then((item) => {
        // successfully added to cart
        console.log(item.name + " was added to cart");
    })
    .catch((err) => {
        // oops something bad happened
        console.error(err);
    });

Add an item to the shopping cart.

Returns a Promise

Property Type Description
id String* The item unique ID
name String* Item name
price Int* Item price in cents (price/100)
quantity Int* Item quantity

See the complete list of CartItem properties

Update an item

Stratocart.updateItem("unique-product-id", {
    quantity: 3,
})
    .then((item) => {
        // successfully updated
        console.log(item.name + " was updated");
    })
    .catch((err) => {
        // oops something bad happened
        console.error(err);
    });

Update properties of a single cart item by ID.

See the complete list of CartItem properties

Returns a Promise

Remove an item

Stratocart.removeItem("unique-product-id")
    .then((item) => {
        // successfully removed
        console.log(item.name + " was removed from the cart");
    })
    .catch((err) => {
        // oops something bad happened
        console.error(err);
    });

Remove a single item from the cart by ID.

Returns a Promise

Fetch Cart

Stratocart.fetch()
    .then((cart) => {
        // successfully returned the updated cart object
        console.log(cart);
    })
    .catch((err) => {
        // oops something bad happened
        console.error(err);
    });

Refresh the cart object from the API.

Returns a Promise with the full Cart object on success

Update Cart

Stratocart.update({
    shipping_method: "express",
})
    .then((cart) => {
        // successfully returned the updated cart object
        console.log(cart);
    })
    .catch((err) => {
        // oops something bad happened
        console.error(err);
    });

Updates the Cart object properties.

Returns a Promise with the full Cart object on success

Delete Cart

Stratocart.delete()
    .then(() => {
        // successfully deleted the cart
        console.log(cart);
    })
    .catch((err) => {
        // oops something bad happened
        console.error(err);
    });

Deletes the cart session from the API.

Returns a Promise

Get cart items

Stratocart.getItems()
    .then((items) => {
        // successfully returned the array of items
        // loop through the array of items
        if (items.length) {
            items.forEach((item) => {
                console.log(item.name);
            });
        }
    })
    .catch((err) => {
        // oops something bad happened
        console.error(err);
    });

Get the list of items from the cart.

Returns a Promise with an array of CartItem on success

Empty the cart

Stratocart.empty()
    .then(() => {
        // successfully emptied the cart
        console.log("The cart was emptied");
    })
    .catch((err) => {
        // oops something bad happened
        console.error(err);
    });

Removes all items from the cart.

Returns a Promise

Set Customer

Stratocart.setCustomer({
    email: "john.doe@stratocart.com",
    name: "John Doe",
})
    .then((cart) => {
        // successfully updated customer info
        console.log("The customer was updated.");
    })
    .catch((err) => {
        // oops something bad happened
        console.error(err);
    });

Update the cart with customer information.

Returns a Promise with the full Cart object on success

Set Shipping Info

// set shipping amount
Stratocart.setShippingAmount(amount)
    .then((cart) => {
        // successfully updated shipping amount
        console.log(cart.shipping_amount);
    })
    .catch((err) => {
        // oops something bad happened
        console.error(err);
    });

// set shipping address
Stratocart.setShippingAddress(address)
    .then((cart) => {
        // successfully updated shipping address
        console.log(cart.shipping_address);
    })
    .catch((err) => {
        // oops something bad happened
        console.error(err);
    });

// set shipping method
Stratocart.setShippingMethod(method)
    .then((cart) => {
        // successfully updated shipping method
        console.log(cart.shipping_method);
    })
    .catch((err) => {
        // oops something bad happened
        console.error(err);
    });

setShippingAmount(amount)

Update the shipping amount. Helpful when you want to set the shipping costs from external source.

Parameter Type Description
amount Int* Shipping price in cents (price/100)

Returns a Promise with the full Cart object on success

setShippingAddress(address)

Update the shipping address.

Parameter Type Description
address Object* Shipping address Address

Returns a Promise with the full Cart object on success

setShippingMethod(method)

Update the shipping method.

Parameter Type Description
method_id String* Shipping method ID

Returns a Promise with the full Cart object on success

Set Billing Info

// set billing address
Stratocart.setBillingAddress(address)
    .then((cart) => {
        // successfully updated billing address
        console.log(cart.billing_address);
    })
    .catch((err) => {
        // oops something bad happened
        console.error(err);
    });

// set billing method
Stratocart.setBillingMethod(method)
    .then((cart) => {
        // successfully updated billing method
        console.log(cart.billing_method);
    })
    .catch((err) => {
        // oops something bad happened
        console.error(err);
    });

setBillingAddress(address)

Update the billing address.

Parameter Type Description
address Object* Billing address Address

Returns a Promise with the full Cart object on success

setBillingMethod(method)

Update the billing method.

Parameter Type Description
method_id String* Billing method ID

Returns a Promise with the full Cart object on success

Events

These events will fire anytime an action happen in the shopping cart or checkout flow. Use listeners to customise the experience.

Stratocart.on("ready", (data) => {
    // GumCart is loaded, do something here
});
Stratocart.on("totals.change", (data) => {
    // GumCart totals change, console log the amounts
    console.log("Shipping: $" + data.shipping_price);
    console.log("Tax: $" + data.tax_amount);
    console.log("Total amount: $" + data.total_amount);
});
Event name Data Description
ready - The cart is loaded & ready
open - The shopping cart opened
close - The shopping cart closed
item.added item Item was added to cart
item.updated item The cart item was updated
item.removed item Item was removed from cart
customer.change customer Customer data was updated
shipping.change shipping Shipping info was updated
billing.change billing Billing info was updated
order.create order The order was created

API Reference

Welcome to the GumCart API. You can use this to access GumCart API endpoints, which can get information about your shop & orders.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "https://api.gumcart.com"
  --header 'X-APIKEY: yourapikey' \
  --header 'Content-Type: application/json' \

Make sure to replace yourapikey with your API key.

GumCart uses API keys to allow access to the API. To obtain an API key please go to https://www.gumcart.com

We expect for the API key to be included for all the private API requests in a header that looks like the following:

X-APIKEY: yourapikey

We expect for the SHOPID to be included for all the public API requests in a header that looks like the following:

X-SHOPID: yourshopid

Cart

We expect for the shop_id to be included for all /cart API requests in a header that looks like the following:

X-SHOPID: yourshopid

The X-APIKEY header will be ignored.

Get Cart

Sample request for retrieving the cart data:

curl -x GET "https://api.gumcart.com/cart/a35a29b5-4a0d-4681-b070-ee19db86ed46" \
  -h 'X-SHOPID: 0a6c50ce-9006-4bda-bea4-2a6832f86684' \

GET /cart or GET /cart/:cart_id

URL Param Description
cart_id The cart unique ID

If cart_id wasn't provided a new cart will be created, the cart_id will be available in the response.

If cart_id was provided but no cart exists, a new cart will be created with a new cart_id.

This method will return the updated Cart object on success or Error on failure.

Update Cart

Sample request for emptying the cart items:

curl -x PATCH "https://api.gumcart.com/cart/a35a29b5-4a0d-4681-b070-ee19db86ed46" \
  -h 'X-SHOPID: 0a6c50ce-9006-4bda-bea4-2a6832f86684' \
  -h 'Content-Type: application/json' \
  -d '{"items": []}'

PATCH /cart/:cart_id

URL Param Description
cart_id The cart unique ID

Pass the Cart object properties to be updated as body.

This method will return the updated Cart object on success or Error on failure.

Delete Cart

Sample request for deleting the cart with all it's data:

curl -x DELETE "https://api.gumcart.com/cart/a35a29b5-4a0d-4681-b070-ee19db86ed46" \
  -h 'X-SHOPID: 0a6c50ce-9006-4bda-bea4-2a6832f86684' \

DELETE /cart/:cart_id

URL Param Description
cart_id The cart unique ID

This method will true on success or Error on failure.

Cart Items

We expect for the shop_id to be included for all /cartitems API requests in a header that looks like the following:

X-SHOPID: yourshopid

The X-APIKEY header will be ignored.

Add Item

Sample request for adding an item to cart:

curl -x POST "https://api.gumcart.com/cartitems/a35a29b5-4a0d-4681-b070-ee19db86ed46" \
  -h 'X-SHOPID: 0a6c50ce-9006-4bda-bea4-2a6832f86684' \
  -h 'Content-Type: application/json' \
  -d '{"id": "HEADPHONES", "name": "Wireless Headphones", "price": 89, "quantity": 1, "description": "Something here to be updated", "images": ["https://www.gumcart.com/assets/images/product-1.jpg"]}'

Sample cart item object:

{
    "id": "HEADPHONES",
    "name": "Wireless Headphones",
    "price": 89,
    "quantity": 1,
    "description": "Something here to be updated",
    "images": ["https://www.gumcart.com/assets/images/product-1.jpg"]
}

Use this method to add new items to cart.

POST /cartitems/:cart_id

URL Param Description
cart_id The cart unique ID

Pass the CartItem object as body.

This method will return the updated Cart object on success or Error on failure.

Update Item

PUT /cartitems/:cart_id/:item_id

URL Param Description
cart_id The cart unique ID
item_id The cart item ID

Pass the CartItem object as body.

This method will return the updated Cart object on success or Error on failure.

Remove Item

DELETE /cartitems/:cart_id/:item_id

URL Param Description
cart_id The cart unique ID
item_id The cart item ID

This method will return the updated Cart object on success or Error on failure.

Orders

In progress.

Shop

Get Shop (public data)

curl -x GET "https://api.gumcart.com/shop" \
  -h 'X-SHOPID: 0a6c50ce-9006-4bda-bea4-2a6832f86684' \

GET https://api.gumcart.com/shop

We expect for the shop_id to be included in the API requests in a header that looks like the following:

X-SHOPID: yourshopid

This method will return the Shop object on success or Error on failure.

Object Definitions

Common object definitions

Cart

{
    "cart_id": "0a6c50ce-9006-4bda-bea4-2a6832f86684",
    "items": [
        // Array of CartItem
    ],
    "created": 1610181890,
    "updated": 1610181900,
    "expires": 1611391500, // updated + 14 days
    "items_amount": 0,
    "customer": {
        // customer info
    },
    "shipping_amount": 0,
    "shipping_address": {
        // shipping address
    },
    "shipping_method": null,
    "billing_method": null,
    "billing_address": {
        // billing address
    },
    "tax_amount": 0,
    "total_amount": 0
}
Property Type Description
cart_id String The cart unique identifier
items Array Items in the cart CartItem
created Int The UNIX timestamp the cart was created
updated Int The UNIX timestamp the cart was updated
expires Int The UNIX timestamp the cart will expire
items_amount Int The total amount of the cart items
customer Object Customer Customer
shipping_amount Int The items shipping amount
shipping_address Object Shipping address Address
shipping_method String The shipping method ID
billing_address Object Billing address Address
billing_method String The shipping method ID
tax_amount Int The items tax amount
total_amount Int The total amount of the cart

CartItem

{
    "id": "SPARKRC900TEAM",
    "name": "Scott Spark RC900 Team Bike",
    "description": "The SCOTT Spark RC is perhaps the most successful full-suspension XC race bike of its time.",
    "price": 359998,
    "quantity": 1,
    "images": ["https://placehold.it/1600x1200"],
    "options": [
        {
            "name": "Color",
            "value": "Orange"
        },
        {
            "name": "Size",
            "value": "M"
        }
        // ...
    ],
    "addons": [
        {
            "name": "Syncros Bottle Cage (Left)",
            "price": 999
        }
        // ...
    ],
    "metadata": {}
}

The cart item object reference. The cart item object is flexible, you can extend it using the meta property.

Property Type Description
id String* The item unique ID
name String* Item name
description String Item description
price Int* Item price in cents (price/100)
quantity Int* Item quantity
images Array Image URLs (must be publicly accessible)
options Array CartItemOption
addons Array CartItemAddon
metadata Object Custom meta object

CartItemOption

{
    "name": "Size",
    "value": "Medium"
}

Use for CartItem that have options (like colors and sizes).

Property Type Description
name String* Option name
value String* Option value

CartItemAddon

{
    "name": "Size",
    "price": 200
}

Use for CartItem that have addons (like extra bacon).

Property Type Description
name String* Option name
price Int* Addon price in cents (price/100)

Checkout

{
    "cart_id": "0a6c50ce-9006-4bda-bea4-2a6832f86684",
    "customer": {},
    "shipping_address": {},
    "billing_address": {}
}
Property Type Description
shop_id String* The shop unique identifier
cart_id String* The cart item unique identifier
customer Object Customer Customer
billing Object Billing address Address
shipping Object Shipping address Address

Customer

The customer object reference.

Address

// example of the address object
{
    "company": "",
    "name": "Marissa Doe",
    "line1": "132 Harvest Way",
    "line2": "",
    "city": "Crandall",
    "state": "TX",
    "postal_code": "75114",
    "country": "US"
}
Field Type Description
company String Company name
name String Recipient name
line1 String Address line 1
line2 String Address line 2
city String The address city
state String The address state/county/provice
postal_code String The address post/zip code
country String The address country (ISO 3166 Alpha-2 code)

Error

{
    "error": "The hepful but dreaded error message"
}

The API uses the following error codes:

Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- You're not allowed to access that listing.
404 Not Found -- The specified listing could not be found.
405 Method Not Allowed -- You tried to access listing with an invalid method.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.