Integrating Shopify

How to set up Sheetcast integration for your Shopify store

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.
In the Sheetcast web app, open the Admin menu and select Integration -> Setup.
1. Click on "Add Shopify".
2. Enter a unique identifier for Integration ID. This will be how this integration is referred to inside Sheetcast.
3. Enter your store name (e.g. shopify-store-name) for Shopify Store Name
4. Enter a Fulfillment Service Name. This will the name you will see used for this Shopify integration inside Shopify, as a location for products to be stocked at (see 2.b. below).
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, if you want to have different products fulfilled with different Sheetcast actions.
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 should probably also turn off "track quantity" and "this is a physical product" for online-fulfilled products.) Any products you wish to get fulfilled through Sheetcast integration must be assigned to one of your fulfillment services.
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
3. Automatic fulfillment will need to be enabled for your store; this is available in your store's admin under Settings -> Checkout -> Order processing -> "Automatically fulfill the order‘s line items".
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 quantity 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.
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 Shopify is phasing out this feature) 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.
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 Integration ID you configured in Step 1, matching the desired fulfillment service.
4. In A3, enter Event Type. In B3, enter the event type. Available types are "fulfill-single-item" and "fulfill-qty". The difference between the two is whether the action formula for the next step is executed once for each individual item, or once for the whole quantity on a particular order.
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. For a "fulfill-single-item" event, this action will be performed once for each individual item on a particular line item--if a quantity of 2 is to be fulfilled, the action will be performed twice. For a "fulfill-qty" event, this action will be performed once for each line item on the order, with the quantity as a parameter.
6. Note that no fulfillment will occur while the app is checked out. Fulfillment actions 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 event formulas can access properties from the custom attributes with the function CASTPARAM("attributes.attribute_name"), as well as the variant id with CASTPARAM("variant_id"), the order id with CASTPARAM("order_id"), and the quantity with CASTPARAM("quantity"). (For "fulfill-single-item" events, "quantity" will be present but will always be 1. For "fulfill-qty" events, "quantity" will be the quantity from the order line item.)
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.