Requirements

These documents are intended for software developers and engineers who have full access to develop on a web server and want to make a custom website compatible with the Shopworks browser.

If you are a merchant looking for non-technical solutions, go here.

Getting Started

To start selling on Shopworks using your existing web server:

  1. Register for a Shopworks merchant account
  2. Implement the Shopworks Open JSON specification on your server
  3. Receive order notifications
  4. Update tracking information

1: Merchant Registration

If you don't already have a merchant account, you can sign up here.

2: Shopworks Open JSON Specification

Just like a web browser, the Shopwork app makes HTTP requests to your domain.

Request Headers

The Shopworks browser adds several HTTP headers along with its request to your server:

Header Description
User-Agent Shopworks identifies itself as Shopworks/1.0.0 shopworks.io
Accept This value will always be application/json. The Shopworks browser only understands JSON.
Content-Type This value will always be application/json. The Shopworks browser always sends data in JSON format.
X-Shopworks-Shipping-Country If available, the ISO 3166 two-letter country code of the shipping address the customer intends to use. Note that this may change during their cart checkout. This is intended to provide accurate product listings and prices for the customer location. Example values: "US", "CA", "GB"
X-Shopworks-Shipping-AdminAreaLevel1 The state or province of the customer's intended shipping destination. Example values: "CA", "NY", "ON"
X-Shopworks-Shipping-Locality The city of the customer's intended shipping destination. Example values: "San Francisco"
X-Shopworks-Shipping-PostalCode The zip or postal code of the customer's intended shipping destination. Example values: "94105", "M4C 1B5"

The Shopworks app will only send requests to certain paths on your server. Make sure your web server listens for and responds to all of the requests below.

When a user types in your domain name in the URL address bar in the app, the app will first ask for your store configuration. In particular, it looks for the StoreConfiguration.endpoint and uses it to make subsequent requests to render your homepage, product listings, and more.

GET Store Configuration

Retrieves the configuration for your store. When a customer types in your domain into the Shopworks URL address bar, the Shopworks client first makes a request to retrieve your configuration.
GET [YOUR_DOMAIN]/shopworks.conf
Request Fields
Name Description
none -
Response
Example request
GET /shopworks.conf HTTP/1.1
Host: YOUR-DOMAIN.com
Accept: application/json
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 9999

{"name":"My Pirate Shoppe",
 "endpoint":"http://example.com/shopworks-listener/",
 "tagline":"Where you get some booty",
 "description":"...",
 ...
}

GET Storefront

Retrieve the layout for the front page of your store. This is the first screen customers see when they visit your store.
GET [YOUR_ENDPOINT]/index
Request Fields
Name Description
none -
Response
Example request
GET /shopworks.conf HTTP/1.1
Host: YOUR-DOMAIN.com
Accept: application/json
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 9999

{"name":"My Pirate Shoppe",
 "tagline":"Where you get some booty",
 "description":"...",
 ...
}

GET Products List

Retrieve a list of ProductGroups filtered by categories.
GET [YOUR_ENDPOINT]/products
Request Fields
Name Description
primary_category Required. Example values: Hats, Jewelry
secondary_category Optional. Example values: Men's, Kids
tertiary_category Optional. Example values: On Sale, Clearance
Response
List of ProductGroups
Example request
GET /YOUR-ENDPOINT-PATH/products HTTP/1.1
Host: YOUR-ENDPOINT-DOMAIN.com
Accept: application/json
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 9999

[{"uri":"http://YOUR-ENDPOINT-DOMAIN/product/flowered-shirt",
  "sku":"flowered-shirt",
  "name":"My Flowered Shirt",
  "description:"This handcrafted...",
  "avg_price":14.99,
  "avg_ship_cost":2.99,
  ...
  },
 {"uri":"http://YOUR-ENDPOINT-DOMAIN/product/checkered-shirt",
  "sku":"checkered-shirt",
  ...
  },
  ...
]

GET Product Group

GET [YOUR_PRODUCT_GROUP_URI]
Request Fields
Name Description
none -
Response
Example request
GET /product/flowered-shirt HTTP/1.1
Host: YOUR-ENDPOINT-DOMAIN.com
Accept: application/json
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 9999

{"name":"My Flowered Shirt",
 "description":"...",
 "variations":[ ... ],
 ...
}

GET Product Variation

GET [YOUR_PRODUCT_VARIATION_URI]
Request Fields
Name Description
none -
Response
Example request
GET /product/flowered-shirt/variation/womens/small HTTP/1.1
Host: YOUR-ENDPOINT-DOMAIN.com
Accept: application/json
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 9999

{"name":"My Flowered Shirt (Women's Small)",
 "sku":"my-flowered-shirt-w-s",
 "description":"...",
 "price":24.99,
 "ship_cost":2.99,
 ...
}

GET Order Tracking

Retrieve a list of shipment tracking information for specified orders.
GET [YOUR_ENDPOINT]/order-tracking
Request Fields
Name Description
order_id_list Required. A comma-separated list of Shopworks order ids.
Response
Example request
GET /order-tracking?order_id_list=A1001,A1002,foo,not-tracked-order HTTP/1.1
Host: YOUR-ENDPOINT-DOMAIN.com
Accept: application/json
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 9999

[{"order_id":"015339e5b8ca9a0303b0015a4797b320fddb834b2719",
 "tracking":"1Z9999999999999999",
 "carrier":"UPS",
 "status":"shipped"
 },
{"order_id":"015339ffcc711ae1e805758241cbba26234268e0d1be",
 "tracking":"961280407409999",
 "carrier":"FEDEX",
 "status":"shipped"
 },
{"order_id":"01536859d8e6c90d819d839f41d79523c5046f79f538",
 "tracking":"9205590102254122369999",
 "carrier":"USPS",
 "status":"shipped"
 },
{"order_id":"some-not-tracked-order-id",
 "tracking":null,
 "carrier":"USPS",
 "status":"pending"
 },
]

3: Receiving Order Notifications

After a customer completes a purchase, you will receive one or more notifications. You can set up your notification methods from your Merchant Portal.

There are a number of ways to receive orders:

After you receive your order notification, it is your responsibility to pack and ship the item to the customer.

HTTP POST

The Order will be POSTed to a secure URI endpoint you specify. Note the POST body encoding is application/json, not application/x-www-form-urlencoded nor multipart/form-data.

Request

POST /YOUR-LISTENER-ENDPOINT-PATH HTTP/1.1
Host: YOUR-LISTENER-ENDPOINT-DOMAIN.com
Content-Type: application/json; charset=utf-8
Content-Length: 9999

{"id":"01536859d8e6c90d819d839f41d79523c5046f79f538",
 "items":{ ... },
 "shipping_address":{ ... },
 ...
}

Response

HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 9999

Human-readable Email

TODO: Fill this out

Machine-readable Email

TODO: Fill this out

4: Update Order Tracking Information

After you ship your item, please update the order tracking information in your system and make sure your server is listening and responding to GET Order Tracking. Shopworks will periodically query for tracking information to display to the customer.

Objects

StoreConfiguration

A valid store configuration is what enables the Shopworks app client to use your store.
Fields
Name Type Required? Description
name string Yes The name of your store
endpoint string Yes The URL prefix for fetching the Storefront, Products List, Product Group, and Product Variation.
Example
{"name":"Ye Pirate Shoppe",
 "endpoint":"http://example.com/shopworks-server/"}

ProductGroup

A ProductGroup is a logical grouping of similar items. For example, a shirt may have three different sizes (S, M, L) and cut for both genders (Male, Female). These items form a ProductGroup. ProductGroups are only for display purposes -- customers do not buy ProductGroups, they buy ProductVariations.
Fields
Name Type Required? Description
uri string Yes The location of this Product Group
sku string Yes Your internal SKU
name string Yes Product name
description string Yes Product description
avg_price float Yes The average price of the children ProductVariations, for display and search filter purposes.
avg_ship_cost float Yes The average ship_cost of the children ProductVariations, for display and search filter purposes.
avg_msrp float Yes The average msrp of the children ProductVariations, for display and search filter purposes.
total_qty_avail integer Yes The sum of qty_avail of the children ProductVariations, to filter out of stock items from display.
variations list Yes The children ProductVariations. The length must be at least one.
images list Yes There must be at least one image.
status string Yes Possible values: enabled or disabled. If enabled, this Product Group is listed and its Product Variation children can be purchased.
Example
{"uri":"https://www.example.com/product/aaaa",
 "sku":"pika-parent",
 "name":"Lightning Rod",
 "description":"Fire at me",
 "avg_price":14.81,
 "avg_ship_cost":0.5,
 "avg_msrp":0,
 "avg_weight":0,
 "total_qty_avail":1300,
 "variations":[{"variant":[{"value":"Aluminium","label":"Material"}],
                "child_uri":"https://www.example.com/product/aaaa/variation/aaaa"},
               {"variant":[{"value":"Lead","label":"Material"}],
                "child_uri":"https://www.example.com/product/aaaa/variation/bbbb"}],
 "images":[{"url":"http://cdn.example.com/image1.jpg",
            "width":600,
            "height":800},
           {"url":"http://cdn.example.com/image2.jpg",
            "width":300,
            "height":500}],
 "status":"enabled"}

ProductVariation

A ProductVariation is a particular style for a ProductGroup. A ProductGroup must have one or more ProductVariations.
Fields
Name Type Required? Description
uri string Yes The location of this Product Variation
parent_uri string Yes The location of the parent ProductGroup
sku string Yes Your product's SKU
name string Yes Product name
description string Yes Product description
price float Yes The retail price the customer pays, in US dollars
ship_cost float Yes The override shipping price the customer pays, in US dollars. If this is set to a non-null value, it overrides merchant-level shipping zone rules. This allows shipping to be customized per product.
qty_avail integer Yes The amount you have in stock, ie the maximum number of items that can be purchased. You must decrement this number when you receive an order notification
variations list Yes Label-value pairs of the actual variation(s). Can be an empty list ([]).
images list Yes There must be at least one image.
status string Yes Possible values: enabled or disabled. If enabled, this Product Variation can be purchased.
Example
{"uri":"https://www.example.com/product/aaaa/variation/bbbb",
 "parent_uri":"https://www.example.com/product/aaaa",
 "sku":"pika-parent",
 "name":"Lightning Rod",
 "description":"Fire at me",
 "price":14.99,
 "ship_cost":0.99,
 "qty_avail":192,
 "variation":[{"label":"Material",
               "value":"Lead"},
              {"label":"Size",
               "value":"SM"}],
 "images":[{"url":"http://cdn.example.com/i/image1.jpg",
            "width":400,
            "height":500},
           {"url":"http://cdn.example.com/i/image2.jpg",
            "width":400,
            "height":500},
           ],
 "status":"enabled"}

Order

An order is created after a customer checks out his or her shopping cart. It includes all information necessary to ship the items. Orders are sent to you via order notifications.
Fields
Name Type Description
id string The Shopworks order ID. This string can be up to 44 hexadecimal characters.
created int The date/time the order was placed, in seconds since epoch time (Midnight 1970/1/1 UTC)
items OrderItem A list of items the customer ordered
shipping_address ShippingAddress The destination address
currency string The three letter ISO 4217 code of the currency the order was paid in. Example: USD
subtotal float The total of the order minus shipping and taxes
shipping float The amount the customer paid for shipping
tax float The total tax, including sales tax and VAT, the customer paid for this order
total float The total amount the customer paid for this order
pay_status string The payment status of this order. This will always be paid.
fulfillment_service string The type of shipping the customer requested. Example: "USPS Priority", "Next-Day Air"
Example
{"id":"01536859d8e6c90d819d839f41d79523c5046f79f538",
 "created":1456961386884,
 "items":[
    {
      product_group: {
         name:"Acme Boxes"
      },
      product_variation: {
         name:"Acme Boxes (Small)",
         sku:"acme-boxes-small",
         price:34.5
      },
      qty:2
    },
    {
      product_group: {
         name:"Pirate Donuts"
      },
      product_variation: {
         name:"Pirate Donuts",
         sku:"pirate-donuts",
         price:2
      },
      qty:1
    },
 ],
 "shipping_address":{
    "name":"Jane Doe",
    "street_1":"123 Main St.",
    "street_2":null,
    "street_3":null,
    "city":"San Francisco",
    "state":"California",
    "zip":"94105",
    "country":"US",
    "phone":"(415) 555-0199",
    "email":"jane.doe@example.com"
 },
 "currency":"USD",
 "subtotal":71,
 "shipping":1.53,
 "tax":6.5,
 "total":79.03,
 "pay_status":"paid"
}

OrderItem

A line item inside an order.
Fields
Name Type Description
product_group ProductGroup The product group. Note that only certain fields are guaranteed to be sent: name
product_variation ProductVariation The product variant. Note that only certain fields are guaranteed to be sent: name, sku, and price
qty int The quantity of this item that was ordered
Example
{
  product_group: {
     name:"Pirate Donuts"
  },
  product_variation: {
     name:"Pirate Donuts",
     sku:"pirate-donuts",
     price:2
  },
  qty:1
}

OrderTracking

The Shopworks browser queries for order tracking information from your server. It is your responsibility to provide accurate and timely tracking information for your customers.
Fields
Name Type Description
order_id string The Shopworks order ID number, which is 44 hexadecimal characters.
tracking string The tracking number. null if none is provided or the item has not shipped yet.
carrier string The delivery service used. Valid values are FEDEX, UPS, USPS, or null if the item has not shipped yet.
status string The shipping status of the shipment. Valid values are pending, shipped, oos, will_not_ship. Use pending if you are preparing the shipment or waiting for carrier pickup. Use shipped if the item has been delivered to the carrier. Use oos for out of stock items, indicating you will not ship the item and plan to follow up with a refund or wait for it to be restocked. Use will_not_ship for any other reason you plan to not ship the item. The customer will expect a follow up from you.
Example
{"order_id":"015339e5b8ca9a0303b0015a4797b320fddb834b2719",
 "tracking":"1Z9999999999999999",
 "carrier":"UPS",
 "status":"shipped"}

ShippingAddress

The destination address of an order.
Fields
Name Type Description
name string The name of the recipient
street_1 string The first address line. Required.
street_2 string The second address line. Can be null.
street_3 string The third address line. Can be null.
city string The city or locality. Example: "San Francisco"
state string The state, province, or first administrative level Examples: "CA", "ON"
country string The ISO 3166 two-letter country code. Example: "US"
zip string The zip or postal code
phone string The phone number. Example: "(415) 555-0199"
Example
{
  "name":"Jane Doe",
  "street_1":"123 Main St.",
  "street_2":null,
  "street_3":null,
  "city":"San Francisco",
  "state":"California",
  "zip":"94105",
  "country":"US",
  "phone":"(415) 555-0199",
  "email":"jane.doe@example.com"
}