# Shopify App Description of Requirements

[TOC]

## Definitions
**App Managers** means Alessando, Andrea and Viktor.
**App Developers** means Techysolider.
**Customer** means shopper at a Shopify store.
**App Checkbox** means optional checkbox displayed to Customer on cart page and when individual items are added to the cart.
**Merchant** means owner of a Shopify store.
**Shopify App** means application developped by App Developers for App Managers.

## Overview

The App Managers want to create a public, embedded Shopify app. The purpose of the app is to calculate CO2 emissions generated by each sale and offer a method to offset these emissions.

Merchants will install the app from the Shopify store and will be able to see some basic stats about the usage of the app. When customers add items to their cart a checkbox will be displayed allowing customers to offset the CO2 emissions (App Checkbox). If the customer clicks on the App Checkbox the Shopify app will send a POST request to a server maintained by the App Managers. The POST request will contain details of the order. The return payload will contain the amount of CO2 emissions generated by the purchase, the monetary amount requried to offset the emissions and a link to a website maintained by the App Developers where the Customer can see a breakdown of the calculations.

If the Customer decides to proceed with the purchase and pay the required amount for offsetting the CO2 emissions the full amount will be transferred to the Merchant. Subsequently, the Shopify App will bill the Merchant the exact amount that was charged to the Customer for offsetting the CO2 emissions of their purchase. This amount will be paid to the App Managers.

## Main Functionality of Shopify App

* Display check box on cart page.
* Display custom link with url to detailed calculation on cart page if check box ticked.
* Display check box when Customer adds individual items to cart.
* Display basic app usage stats to Merchant in Shopify Merchant admin panel.
* Insert information collected from Merchant and Client into SQL database.
* Get CO2 offset calculations via API maintained by App Managers.
* Add CO2 offset amount to purchase price payable by Customer if App Checkbox ticked.
* Bill Merchant.
* Support different languages (For 2-3 sentances).

## Technical Specifications

### Access Scopes requested by Shopify App

The Shopify App should request the following access scopes:

https://shopify.dev/api/usage/access-scopes#limitations-and-considerations

`read_orders`, `read_products`, `read_product_listings`,`read_checkouts`, `read_customers`, `read_draft_orders`, `read_inventory`, `read_shipping`, `read_order_edits`.

### SQL Database

The following diagram defines the tables and relations in the database.

**Table Merchants**
Entries created when Merchant installs Shopify App.

**Table Products**
Entries downloaded from Merchant stores when Merchant install Shopify App. Periodically (every day) check for updates to products and insert new entries into database.

Field `product_category` will be assigned by App Managers by directly insering values into the database.

**Table Checkbox_Clicks**
Registers click on App Checkbox.
Records the products in the cart at the time of the click.
The column `customer_session_id` identifies customers of the store. In other words, we want to record clicks by Customer.

**Table Customer_Payments**
Inserts entries after Customer selects App Checkbox and pays for order.

### API
App Managers will build a REST API and make it available to App Developers.

App Developers will need to send POST request to url provided by App Managers. API key will be provided by App Managers for accessing the API.

Payload in the form of JSON in the format below. Values taken from SQL database.

{   
    merchant_id : merchants.merchant_id,
    checkbox_click_id : checkboxclicks.click_id,
    order_id : orders.order_id,
    products : [
                    {
                       shopify_id : products.product_id,
                       description : products.product_description,
                       category : products.product_categry (Null if unassigned),
                       product_price : products.product_price 
                    },
                    { ... },

                    .... ,

                    { ... } ]
}

API response:

Note extra field `calculation_url`. This is the link with the calculation results that needs to be displayed.

{
    products : [{
        shopify_id : int/str,
        co2_emissions : float,
        payment : float
        currency : str },
        {...},
        .... ,
        { ... }],
    total : {
        co2_emissions : float,
        payment : float,
        calculation_url : string
    }

}

Example POST request:

QUESTION to App Developers: `merchant_id`, `checkbox_click_id` and `shopify_id` (for products) currently defined as `str`. Please advise whether this should be changed to a different type.

import requests
import json

api_url = "https:<URL>/shopifyapi/estimate_emissions/"

data = {
    "merchant_id" : "test_id", 
    "checkbox_click_id": "checkbox_click_test_id", 
    "order_id": "order_id TEST ME",
    "products": [
    {"shopify_id":"21", "description":"t-shirt", "category":3, "price": 1, "currency":"EUR"},
    {"shopify_id":"22", "description":"t-shirt 22", "category":3, "price": 2, "currency":"EUR"},
]}

headers = {'Authorization': 'Token <TOKEN>'}


response = requests.post(api_url, json=data, headers=headers)
print(response.json())

### App Dashboard

Merchants will have access to the following information via their admin dashboard
1. Amount of CO2 offset
* simple time series chart
`select co2_offset from Customer_Payments where Merchant_ID = <merchant_id> order by Payment_Date`
* running sum chart
`select sum(co2_offset) as Cumulative_CO2 over (ORDER BY Paayment_Date) from Customer_Payments where Merchant_ID = <merchant_id> order by Payment_Date`
2. Total Monetary Amount Contributed by Customers
* simple time series chart
`select Payment_Offset from Customer_Payments where Merchant_ID = <merchant_id> order by Payment_Date`
* running sum chart
`select sum(Payment_Offset) as Cumulative_Payments over (ORDER BY Paayment_Date) from Customer_Payments where Merchant_ID = <merchant_id> order by Payment_Date`

### Shopify App Deployment

Deployed on Microsoft Azure cloud server running Linux. Access to be provided by App Administrators via `ssh`.

### Code Submission

The code will be committed to a private [Bitbucket](https://bitbucket.org) repository access to which will be provided by the App Administrators.