Shops

The Shops resource allows a user to manage their BoxC shop, or connect and manage their third party shops. Fulfilled orders will have their tracking information sent back to their shop when orders are linked to a third party shop (e.g. Shopify) if possible. A shop with orders or SKUs cannot be deleted.

Shop Connector

The BoxC API has a separate shop connector that handles the authorization paradigm for third party shops. The process may be different depending on the type of shop. For instance, the authorization process for Shopify works as follows.

  1. The user creates a new shop in their account by using POST /shops and taking note of their shop's id.
  2. They visit https://api.boxc.com/v1/shops/{id}/connect where {id} is the id from above, and follow the instructions there. It will tell them to follow a link to authorize BoxC's Shopify application for their Shopify account.
  3. Once they grant permission to BoxC they will be redirected back to a success page where it completes the authorization flow and saves the new access token for their Shopify shop.
  4. The user can now manully create orders for their shop or wait for the system to import orders.
Note: If a shop's orders can't be imported due to an expired access token it will be deactivated and disconnected by the system. The user must reconnect the shop.

Shop Types

Below is a table of third party shops supported by the system, along with the rules used to choose which orders are imported automatically. Orders that don't match the criteria will need to be created manually.

Type Rules
Shopify
Fulfillment Status
Unshipped
Payment Status
Paid
Status
Open
Updated
At most 15 days ago

Actions

GET /shops Retrieves a paginated list of shops
GET /shops/{id} Retrieves a shop
GET /shops/{id}/connect Initializes the shop authorization process
POST /shops Creates a shop
PUT /shops/{id} Updates a shop
DELETE /shops/{id} Deletes a shop

Properties

active

{"active": true}

Boolean - Whether or not the shop is active. This only applies to third party shops. An inactive third party shop will no longer have its orders imported into the system. Required.
connected

{"connected": true}

Boolean - Whether or not the third party shop is connected to its external API. The system will set this to false if there are connection issues. Set by the system.
created

{"created": "2016-02-29 15:12:33"}

String - The date and time the shop was created. Set by the system.
expires

{"expires": "2016-09-02 12:10:54"}

String - The date and/or time the access token expires in UTC. If the token never expires or is not relevant to the type of shop then the value will be Null. If the token does expire the user must reauthorize the BoxC API. Set by the system.
id

{"id": "my-shop"}

String - The user defined shop ID. It can contain the following characters only: "A-Za-z0-9-_". Required. Min length: 3. Max length: 32. This property is immutable. Shop IDs are unique across all accounts.
name

{"name": "Appleseeds"}

String - A user defined shop name. Max length: 32. Required.
settings 

{
    "settings": {
        "delay_processing": 24,
        "partial_fulfillment": true
    }
}

Array - Default settings for the shop. Not all settings apply for every shop type. Required.

delay_processing: Integer - The number of hours an order should remain unprocessed in the system before packing. Orders will be processed if their created value plus the shop's delay_processing value is greater than the current time. Max: 240. Required.
partial_fulfillment: Boolean - Whether or not orders imported from an external shop (e.g. a Shopify store) should be partially fulfilled by default. Default: false. Required.
type

{"type": "BoxC"}

String - The type of shop. Two types are supported. Required. This property is immutable.
  • BoxC
  • Shopify
GET
/shops/{id}
Retrieves a shop
request
GET /shops/my-shop
response

HTTP/1.1 200 OK

{
    "shop": {
        "active": true,
        "connected": true,
        "created": "2016-03-01 22:15:35",
        "expires": null,
        "id": "my-shop",
        "name": "Appleseeds",
        "settings": {
            "delay_processing": 48,
            "partial_fulfillment": false
        },
        "type": "BoxC"
    }
}
GET
/shops/{id}/connect
Initializes the shop authorization process
request
GET /shops/my-shop/connect
response

HTTP/1.1 200 OK

This action returns a web page.
POST
/shops
Creates a shop
request
POST /shops 
{
    "shop": {
        "active": true,
        "id": "my-shop",
        "name": "Appleseeds",
        "settings": {
            "delay_processing": 48,
            "partial_fulfillment": false
        },
        "type": "BoxC"
    }
}
response

HTTP/1.1 201 Created

{
    "shop": {
        "active": true,
        "connected": true,
        "created": "2016-03-01 22:15:35",
        "expires": null,
        "id": "my-shop",
        "name": "Appleseeds",
        "settings": {
            "delay_processing": 48,
            "partial_fulfillment": false
        },
        "type": "BoxC"
    }
}
PUT
/shops/{id}
Updates a shop
request
PUT /shops/my-shop 
{
    "shop": {
        "active": false,
        "name": "Appleseeds - Inactive",
        "settings": {
            "delay_processing": 0,
            "partial_fulfillment": false
        }
    }
}
response

HTTP/1.1 200 OK

{
    "shop": {
        "active": false,
        "connected": true,
        "created": "2016-03-01 22:15:35",
        "expires": null,
        "id": "my-shop",
        "name": "Appleseeds - Inactive",
        "settings": {
            "delay_processing": 0,
            "partial_fulfillment": false
        },
        "type": "BoxC"
    }
}
DELETE
/shops/{id}
Deletes a shop
request
DELETE /shops/my-shop
response

HTTP/1.1 200 OK