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:
- Visit https://stratocart.com to get a shop ID.
- 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. |