How to set up Sheetcast integration for your Shopify store

  1.  Before starting: You must already have a Shopify store. You will need to know its name, e.g. "shopify-store-name", which would go with URLs of "https://shopify-store-name.myshopify.com" for the storefront and "https://admin.shopify.com/store/shopify-store-name" for the administration pages.
    1. The Sheetcast web app needs to have ShopifyClientId and ShopifyClientSecret initialized to valid values.
  2. In the Sheetcast web app, open the Admin menu and select Integration -> Setup.
    1. Click on "Add Shopify".
    2. Enter your store name (e.g. shopify-store-name) for Shopify Store Name
    3. Enter a unique identifier for Unique Identifier. This will be how this integration is referred to inside Sheetcast.
    4. Enter a Fulfillment Service Name. This will be how you will see this Shopify integration inside Shopify.
    5. Click Save.
    6. If you have not yet installed the Sheetcast app for your store, you will be taken to a page to verify that you wish to (and are authorized to) install the app.
    7. If you have already installed the Sheetcast app, or after you confirm installation of the app, you will be returned to the Sheetcast Integration Setup page.
    8. Multiple fulfillment services can be added here as required.
  3. In your Shopify store admin, you can now assign products to the location matching your new Fulfillment Service.
    1. When adding or editing a product, under the "Inventory" section, it will say "Inventory will be stocked at" with a dropdown beneath, which will be set to "multiple locations" by default. You can select one of your fulfillment services. (You can probably also turn off "track quantity" and "this is a physical product" for online-fulfilled products.)
    2. For each of the variants you want to sell in your Sheetcast app, you will want to get the Shopify VariantID. You can get this ID from the URL for the variant page as described in https://help.shopify.com/en/manual/products/variants/find-variant-id
  4. To make a purchase link from your Sheetcast app, you will want a URL something like "https://shopify-store-name.myshopify.com/cart/44237383565560:1?attributes[foo]=bar&attributes[baz]=3"
    1. The items to purchase will be specified as "variantid:qty", so the above will create an order with qty 1 for the variant with ID 44237383565560.
    2. Any custom attributes you wish to send to the fulfillment service will need to be added to an "attributes" array as shown above (which would send a value of "bar" for the attribute "foo" and a value of "3" for the attribute "baz").
    3. You can create a link in your Sheetcast app by putting the above URL into the first argument of a "HYPERLINK" formula; the URL string can be built up using CONCAT from sources in other cells.
  5. The link above will go to a checkout page where you can enter payment. Clicking the "Pay now" link will take you to a confirmation page. This page can be customized to add a script redirecting back to the Sheetcast app.
    1. In settings, select "Checkout". Scroll down to "Order Status page", where there should be a box labelled "Additional Scripts". There you can insert something like
      <script>setTimeout(function() { 
              window.location.href = "https://example.com"; 
      }, 2000);</script>
    2. Replace "example.com" with the URL of a page from your Sheetcast application.
    3. For the time being (though this is being phased out) it's possible to access checkout properties using "checkout.liquid", enclosing the desired variable in double curly brackets. This includes being able to access custom attributes e.g. "{{ checkout.attributes.foo }}", or order attributes through "{{ checkout.order.order_number }}".
    4.  So, for instance, you could append these properties to the redirection URL using something like
      <script>setTimeout(function() {
          window.location.href = 
              "https://localhost.sheetcast.com:44304/view/3c0aaf9e-9b13-48f4-9f09-b0df0110ea52/~/560951d4-d9aa-4edb-8357-f7b00e963e21?p=%7B%22~%2F560951d4-d9aa-4edb-8357-f7b00e963e21%22%3A%5B%5B%22order_id%22%2C%20{{ checkout.order_id }}%5D%5D%7D"; 
      }, 2000);</script>
      This includes the URL-encoded value
       {"~/560951d4-d9aa-4edb-8357-f7b00e963e21":[["order_id",order id goes here]]}
      of the parameter "p"; this format is required to properly inject an order_id parameter, which will be associated with the view ID. This URL is somewhat unwieldy, and there should be a way to make the link cleaner in future.
  6. To set up actions to be performed to fulfill an order, you need to create a configuration sheet (in the style of the forthcoming Config V2).

    1. Create a sheet whose name starts with SC.Config. (e.g. SC.Config.Shopify)

    2. In a cell in the first column of the sheet, enter the text [Integration Event] into a cell. (For the purposes of this example, let's assume this goes into the cell A1.)

    3. In A2, enter Integration Id. In B2, enter the unique identifier for the integration you configured in Step 1, matching the desired fulfillment service.

    4. In A3, enter Event Type. In B3, enter "fulfill-single-item" (the only event currently supported, though there may be more in future).

    5. In A4, enter Execute Formula. In B4, enter an action formula that you wish to be executed when an order is fulfilled. This may contain multiple actions using the new DO() UDF. One action should be to add a record in a sheet (using DOSETVALUES or the equivalent) with the order ID; another can be to execute some action or script which actually performs the fulfillment of the purchase. As a "fulfill-single-item" event, this action will be performed once for each individual item--if a quantity of 2 is to be fulfilled, the action will be performed twice.

    6. Note that no fulfillment will occur while the app is checked out. Fulfillment events will not be triggered, but they will remain available to be processed after the app is checked in.

    7. Fulfillment events can be triggered (for publicly accessible Sheetcast servers) when the order is paid, but there will also be a processor that runs every minute that will process any outstanding unfulfilled orders.

    8. Fulfillment events can access properties from the custom attributes with the function CASTPARAM("attributes.foo"), as well as the variant id with CASTPARAM("variant_id") and the order id with CASTPARAM("order_id")

  7. The page where you are redirected from the Shopify checkout can be set up to auto-refresh while waiting for the fulfillment to complete. To do this, you can set the Auto-Refresh Interval for the page (which must be a Report or Container page) to be a formula that looks for the record generated by the fulfillment service event action.