# Shopify

The Shopify connector enables Zuar Runner to pipe data from a Shopify account/store
and store the data in a database. The Zuar Runner Shopify Connector can be
configured to use any version of the Shopify REST API. If unspecified in the
job configuration, it will default to v2020-01 (see information below about
specifying the version).

There are a variety of endpoints that are available via GET requests and these
endpoints are well documented by Shopify here: [Shopify API reference
docs](https://shopify.dev/docs/api/liquid/objects).

## Authentication/Credentials

The Zuar Runner Shopify connector will require a credential set that includes an API
access token and the shop name. It is recommended that you create an encrypted
[Generic Saved Credential](/user-interface/index.html#credentials) to be used
in the Zuar Runner job configuration. It should be configured like:

```json
{
  api_key: shpat_########################
  shop: nameofmyshop
}
```
- **api_key:** access token generated in shopify to access the API.
- **store:** name of the store that you are attempting to access via the API.

## Anatomy of a Zuar Runner Shopify Job
Zuar Runner Job Configuration for Shopify:

### Input

The input section within a Shopify job configuration should
consist at minimum of `credentials`, `endpoint`, `api_version`, and
`use`. It also accepts additional parameters. Parameters may be specific to
the endpoint that you are retrieving. Best practice is to reference the
[Shopify API documentation](https://shopify.dev/docs/api/liquid/objects),
find the endpoint you are retrieving, and add any desired parameters to the
`parameter:{ parameter: here}` key in the Zuar Runner job configuration.

Consider this example:
```json
input: {
	credentials: MY-SHOPIFY-CREDS
	endpoint: orders
	api_version: 2023-01
	parameters: {
	  status: any
	  created_at_min: 2022-01-01T16:15:47-04:00
	}
	use: shopify.iov2#ShopifyPaginatedInput
  }
```

- **Credentials**: The name of the encrypted _Generic Saved Credential_
  created in Zuar Runner’s credential store. Again, this consists of the API access
  token (`api_key`) , and the name of the shop (`shop`) (see above reference
  for creating the saved credential).
- **Endpoint**: The corresponding [Shopify
  endpoint/object](https://shopify.dev/docs/api/liquid/objects) to be used
  when retrieving data. 
- **API Version**: Allows specification of the version of Shopify API to be
  used when making a request with `YYYY-MM` format
- **Parameters**: Array of parameters for filtering or influencing the call
  being made to a specific endpoint. Multiple parameters can be leveraged by
  placing each on it’s own line. Parameters may be specific to the endpoint.
- **USE**: The use section specifies the use of the input for using jobs to
  call Jira’s REST API. The generic input for most Jira jobs will be
  `shopify.iov2#ShopifyPaginatedInput`.
  

### Output

This is the standard output configuration section used to specify the location
of where Zuar Runner should pipe the data retrieved from the GET request. The
minimum configuration for the output section requires `dbo`, `schema`,
`tablename`, `use`.

**NOTE:** There may be slight variation to this section depending on your output destination database. 
Please consult documentation for your specific database from the [Database URLs Zuar Runner help docs](/databases/database-urls/).

```json
 output: {
    dbo: postgresql://db/analytics
    schema: shopify
    tablename: orders_storename
    use: call:mitto.iov2.db#todb
  }
```
- **DBO**: This is the database string used to connect to the destination database for outputting data.
- **Schema**: The schema under which the table will be created. If a schema does not already exist, Zuar Runner will create a new one.
- **Tablename**: The name of the table for the data that will be outputted.
- **Use**: Zuar Runner function to specify how to output the data.
  
### Example Job Configurations
Depending on your use case, you may consider configuring your Jira Zuar Runner job
to [create a store](/jobs/io/store) and leverage
[upsert](/jobs/io/upsert/). Creating a store will enable the
creation of [additional jobs](/jobs/store-input/) to un-nest the
nodes within the JSON blob that is retrieved from the GET request. For
example, to get order line items, a store will need to be added to the orders
job followed by a secondary job that uses the store as an input:

**Get all orders created on or after 1-1-2022, create a store, and add upsert
so that only new records are added and old records are updated based on the
updated_at field after the first run.**

```json
{
  input: {
    credentials: MY-SHOPIFY-CREDS
    endpoint: orders
    api_version: 2023-01
    parameters: {
      status: any
      created_at_min: 2022-01-01T16:15:47-04:00
    }
    use: shopify.iov2#ShopifyPaginatedInput
  }
  output: {
    dbo: postgresql://db/analytics
    schema: shopify
    tablename: orders_makeuperaserofficial
    use: call:mitto.iov2.db#todb
  }
  steps: [
    {
      column: updated_at
      use: mitto.iov2.steps#MaxTimestamp
    }
    {
      use: mitto.iov2.steps.upsert#SetUpdatedAt
    }
    {
      transforms: [
        {
          use: mitto.iov2.transform#ExtraColumnsTransform
        }
        {
          use: mitto.iov2.transform#ColumnsTransform
        }
      ]
      use: mitto.iov2.steps#Input
    }
    {
      use: mitto.iov2.steps#CreateTable
    }
    {
      use: mitto.iov2.steps.upsert#CreateTempTable
    }
    {
      transforms: [
        {
          use: mitto.iov2.transform#FlattenTransform
        }
      ]
      use: mitto.iov2.steps#Output
    }
    {
      key: id
      use: mitto.iov2.steps.upsert#SyncTempTable
    }
    {
      use: mitto.iov2.steps#CollectMeta
    }
  ]
  store: {
    key: [
      $.id
    ]
    updated_at: $.updated_at
  }
}
```

**Create a table using a Store job that references the store created above
(orders) and extract an array of data stored within the line_items node of the
JSON retrieved by the Issues GET request:**

```json
{
  input: {
    name: shopify_orders
    use: mitto.iov2.input#StoreInput
    jpath: $.line_items[*]
    members: [
      {
        name: order_id
        value: $.id
      }
    ]
  }
  output: {
    tablename: order_line_items__makeuperaserofficial
    use: call:mitto.iov2.db#todb
    schema: shopify
    dbo: postgresql://db/analytics
  }
  steps: [
    {
      use: mitto.iov2.steps#Input
      transforms: [
        {
          use: mitto.iov2.transform#ExtraColumnsTransform
        }
        {
          use: mitto.iov2.transform#ColumnsTransform
        }
      ]
    }
    {
      use: mitto.iov2.steps#CreateTable
    }
    {
      use: mitto.iov2.steps#Output
      transforms: [
        {
          use: mitto.iov2.transform#FlattenTransform
        }
      ]
    }
    {
      use: mitto.iov2.steps#CollectMeta
    }
  ]
}
```

## Rate Limits
According to Shopify API documentation, the REST Admin API supports a limit of
40 requests per app per store per minute. This allotment replenishes at a rate
of 2 requests per second. The rate limit is increased by a factor of 10 for
Shopify Plus stores. [Click here to learn more!](https://shopify.dev/docs/api/admin-rest#rate_limits)


## Status and Error Codes
All API queries return HTTP status codes that can tell you more about the
response. [Learn More
Here!](https://shopify.dev/docs/api/admin-rest#status_and_error_codes)