Shopify Admin v2 component

Shopify admin Component is designed to connect to Shopify GraphQL Admin API.

Shopify admin Component

Description
Credentials
Actions
Triggers
- Get New and Updated Objects Polling
- Webhook
Known Limitations

Description

Shopify admin Component is designed to connect to Shopify GraphQL Admin API

Tested with API version: 2023-01

Credentials

To use this component you need to create a custom App:

Go to your store Admin panel
Open App and sales channel settings
Select Develop apps for your store
Then Create an app button
Provide any app name and press Create app
Follow to Configure Admin API scopes
Select access scopes - Objects, that component will have access to and press Save
Now you be able to install this app by pressing Install app button in API credentials section or in right upper corner
Finally you can get Admin API access token by selecting Reveal token once. It will be needed in component credentials configuration
In addition, you may need to save API secret key if you going to use webhooks

Screenshot instructions

Component credentials configuration fields:

Store name (string, required) - Provide you store name here, can be found in Admin panel as a part of store url
Admin API access token (string, required) - this token you will get after app creation (look at instructions above)
API version (string, required) - Provide API version you are going to work with. Currently component tested on 2023-01, but should work with any available
API secret key (string, optional) - This field is used and required only for trigger - Webhook to sign the request with an HMAC header.
Notes:
Admin API access token shows only once
To rotate the API credentials for a custom app that was created in the Shopify admin, you need to uninstall and reinstall the app

Actions

Delete Object

Objects in Shopify can be deleted with Execute mutation action

To do that, filter the list of available mutation types in the Mutation type configuration field by Delete or Remove keyword

In most cases you will get one input metadata field with object identifier

Example of input metadata to delete a customer

  {
    "input": {
      "id": "gid://shopify/Customer/6657016299696"
    }
  }

Example of input metadata to delete multiple companies

  {
    "companyIds": ["gid://shopify/Company/68616368"]
  }

Example of input metadata to bulk delete draft orders using search

{
  "search": "query=name:\"#D12\""
}

Create Object

Objects in Shopify can be created with Execute mutation action

To do that, filter the list of available mutation types in the Mutation type configuration field by Create keyword

Input metadata will represent all needed fields to create an object

Example of input metadata to create a customer

  {
    "input": {
      "firstName": "NewUser"
    }
  }

Update Object

Objects in Shopify can be updated with Execute mutation action

To do that, filter the list of available mutation types in the Mutation type configuration field by Update keyword

Input metadata will represent all needed fields to update an object

Example of input metadata to update a customer

  {
    "input": {
      "firstName": "NewUser2",
      "id": "gid://shopify/Customer/6664472461488"
    }
  }

Upsert Object

Updates (of record found) or creates a new object.

Configuration Fields

Object type - (dropdown, required): Currently supported only Customers.
Unique field to upsert - (dropdown, required): This field will be used to search object, if object not found or field is empty, new object will be created.
Select basic fields for resulting object - (dropdown, optional): Here provided only basic fields that can be included in resulting object, it may affect on query cost
You can provide additional fields here - (string, optional): Resulting object can be expanded using GraphQL request, it may affect on query cost Example for customer
```
  customer {
    addresses {
      city
    }
  }
```
❗Note: You need to select basic fields or provide additional fields for resulting object to execute mutation
Input as batch - (checkbox, optional): If checked, the input metadata will be an array instead of a single object

Input Metadata

Dynamically generated fields according to chosen Object type.

Output Metadata

Result object from upsert.

Execute mutation

Execute any mutation available on selected API version. This action can be used to Create, Update or Delete Objects and any other operations that affect on Shopify data

Configuration Fields

Mutation type - (dropdown, required): Mutation type to execute. E.g Customer Create.
Select basic fields for resulting object - (dropdown, optional): Here provided only basic fields that can be included in resulting object, it may affect on query cost

You can provide additional fields here - (string, optional): Resulting object can be expanded using GraphQL request, it may affect on query cost Example for customer

  customer {
    metafields(first: 2) {
      edges {
        node {
          namespace
          key
          value
        }
      }
    }
    addresses {
      address1
      country
    }
  }

❗Note: You need to select basic fields or provide additional fields for resulting object to execute mutation

Input Metadata

Dynamically generated fields according to chosen Mutation type.

Output Metadata

Result object from executed mutation.

Lookup Objects (plural)

Lookup a set of objects by defined criteria list. Can be emitted in different way.

Configuration Fields

Object Type - (dropdown, required): Object-type to lookup on. E.g Customers.
Select basic fields for resulting object - (dropdown, optional): Here provided only basic fields that can be included in resulting object, it may affect on query cost
You can provide additional fields here - (string, optional): Resulting object can be expanded using GraphQL request, it may affect on query cost Example for customer
```
    addresses {
      address1
      country
    }
```
Emit Behavior - (dropdown, required): Defines the way result objects will be emitted, one of Emit page or Emit individually.

Return Full Response - (checkbox): Defines the format of emitted result: with service information or without. Examples for Object type customers are given below: Response with enabled Return Full Response checkbox and Emit Behavior = Emit page

{
    "data": {
      "customers": [
        {
          "id": "gid://shopify/Customer/2444144115794",
          "firstName": "Willy"
        },
        {
          "id": "gid://shopify/Customer/2444144148562",
          "firstName": "Tobi"
        },
        {
          "id": "gid://shopify/Customer/2444144181330",
          "firstName": "Mathilde"
        }
      ]
    },
    "extensions": {
      "cost": {
        "requestedQueryCost": 5,
        "actualQueryCost": 5,
        "throttleStatus": {
          "maximumAvailable": 1000,
          "currentlyAvailable": 40,
          "restoreRate": 50
        }
      }
    }
}

Response with disabled Return Full Response checkbox and Emit Behavior = Emit page

{
  "results": [
    {
      "id": "gid://shopify/Customer/2444144115794",
      "firstName": "Willy"
    },
    {
      "id": "gid://shopify/Customer/2444144148562",
      "firstName": "Tobi"
    },
    {
      "id": "gid://shopify/Customer/2444144181330",
      "firstName": "Mathilde"
    }
  ]
}

Number of search terms - (number, optional): text field to specify the number of search terms (positive integer number [1-99] or 0).
Emit empty object if no entities found - (checkbox): If this checkbox is selected and objects are not found component will emit an empty object instead of skipping execution

Input Metadata

First - (strings, optional): Indicates amount of objects per execution. Default to 250 Input Metadata is depending on the configuration field Number of search terms. If Number of search terms is empty or equal 0, additional fields will not be generated. If Number of search terms = 1, one search term will be added to metadata. If Number of search terms > 1, a number of search term equal Number of search terms and a number of criteria link equal ‘Number of search terms - 1’ will de created in metadata. Each search term has 3 fields:
Field name - chosen entity’s field name. You need to select the one field from Allowed Values section Note Allowed Values section contains fields that are allowed to use in query and fields with - sign, which means NOT modifier (see here)
Condition - You need to select the one condition from Allowed Values section
Field value - the value that the field must match with the specified condition Between search terms, there is Criteria Link. You need to select the one criteria from Allowed Values section

Output Metadata

Dynamically generated fields according to chosen Object type and selected fields. For Emit Page mode: An object, with key results that has an array as its value. For Emit Individually mode: Each object which fill the entire message.

Example

For instance, it is needed to execute following Shopify query:

query{
    customers(first:10 query:"country:Canada AND -state:DISABLED"){
        edges{
            node{
                id
                state
                firstName
                addresses{
                    country
                }
            }
        }
    }
}

Select in Object type option Customers
From dropdown Select basic fields for resulting object select basic fields: id, state and firstName.

Note: Basic fields are fields that can be requested without specifying arguments or adding additional levels: id, email, etc.

Paste additional fields in field You can provide additional fields here:

Note: Additional fields are fields that can’t be selected in Basic fields section. As rule, they are fields with specifying arguments or adding additional levels such as: addresses{country}.

Select Emit Behavior. If it is needed to receive each object individually, use Emit individually, in other case, Emit page option - all objects will be returned in one array result. For example, lets use ‘Emit individually’
Specify Number of search terms: in example query we see 2 conditions, so set it to 2
Push the button Continue and move to fill metadata
Set 10 to field First
To map condition country:Canada:

select in Field name from Allowed Values dropdown option country:
select in Condition from Allowed Values dropdown option :
set in Field value value Canada

Select in Logical operator from Allowed Values dropdown option AND
To map condition -state:DISABLED: set Field name to -state, Condition to : and Field value to DISABLED

Push the button Continue and move to Sample section
Push the button Retrieve new sample from Shopify admin component v2
Step is configured.

Lookup Object By ID

Lookup a single object by its ID - only query with one argument id can be used in this action.

Configuration Fields

Object Type - (dropdown, required): Object-type to lookup on. E.g Customer.
Select basic fields for resulting object - (dropdown, optional): Here provided only basic fields that can be included in resulting object, it may affect on query cost
You can provide additional fields here - (string, optional): Resulting object can be expanded using GraphQL request, it may affect on query cost Example for customer
```
    addresses {
      address1
      country
    }
```

Input Metadata

ID Value - (string, required): Value for ID of the object to lookup.

Output Metadata

Dynamically generated fields according to chosen Object type and selected fields.

Make Raw Request

Executes custom request.

Configuration Fields

none

Input Metadata

Url - (string, required): Path of the resource relative to the base URL (https://{store_name}.myshopify.com/admin/api/{api_version}/) or full url
Method - (string, required): HTTP verb to use in the request, one of GET, POST, PUT, PATCH, DELETE.
Request Body - (object, optional): Body of the request to send.

Output Metadata

Status Code - (number, required): HTTP status code of the response.
HTTP headers - (object, required): HTTP headers of the response.
Response Body - (object, optional): HTTP response body.

Note: GraphQL and REST API endpoints are supported. E.g.

GraphQL

Url - /graphql.json
Method - POST
Request Body - {"query": "query { products(first: 10) { edges { node { id title } } } }"}

Equivalent to this:

REST

Url - /products.json?fields=id,title
Method - POST
Request Body - *empty

Triggers

Get New and Updated Objects Polling

Retrieve all the updated or created objects within a given time range.

Configuration Fields

Object Type - (dropdown, required): Object-type to lookup on. E.g Customers.
Timestamp field to poll on - (dropdown, required): Can be either Last Modified or Created dates (updated or new objects, respectively)
Select basic fields for resulting object - (dropdown, optional): Here provided only basic fields that can be included in resulting object, it may affect on query cost
You can provide additional fields here - (string, optional): Resulting object can be expanded using GraphQL request, this field represent content from each edges.node, it may affect on query cost Example for Customers
```
  metafields(first: 2) {
    edges {
      node {
        namespace
        key
        value
      }
    }
  }
  addresses {
    address1
    country
  }
```
Size of Polling Page - (optional, positive integer, defaults to 250, max 250): Indicates the size of pages to be fetched per request. If you query cost will be over shop limit, you can decrease page size.
Emit behavior - (dropdown, optional): Indicates emit objects behavior - Emit individually (by default) or Emit page
Return Full Response - (checkbox): Defines the format of emitted result: with service information or without. Examples for Object type customers are given below: Response with enabled Return Full Response checkbox and Emit Behavior = Emit page

{
    "data": {
      "customers": [
        {
          "id": "gid://shopify/Customer/2444144115794",
          "firstName": "Willy"
        },
        {
          "id": "gid://shopify/Customer/2444144148562",
          "firstName": "Tobi"
        },
        {
          "id": "gid://shopify/Customer/2444144181330",
          "firstName": "Mathilde"
        }
      ]
    },
    "extensions": {
      "cost": {
        "requestedQueryCost": 5,
        "actualQueryCost": 5,
        "throttleStatus": {
          "maximumAvailable": 1000,
          "currentlyAvailable": 40,
          "restoreRate": 50
        }
      }
    }
}

Response with disabled Return Full Response checkbox and Emit Behavior = Emit page

{
  "results": [
    {
      "id": "gid://shopify/Customer/2444144115794",
      "firstName": "Willy"
    },
    {
      "id": "gid://shopify/Customer/2444144148562",
      "firstName": "Tobi"
    },
    {
      "id": "gid://shopify/Customer/2444144181330",
      "firstName": "Mathilde"
    }
  ]
}

Start Time - (string, optional): The timestamp, in ISO8601 format, to start polling from (inclusive). Default value is the beginning of time (January 1, 1970 at 00:00.000).
End Time - (string, optional): The timestamp, in ISO8601 format, to end at (inclusive). Default value is never.

Input Metadata

None.

Output Metadata

Resulting object will represent content from path “data\{Object Type}\edges\node”

Depends on selected Object Type, selected or provided fields and Emit behavior: For Emit Page mode: An object with key results that has an array as its value (if Page Size > 0) For Emit Individually mode: Each object which fill the entire message.

Webhook

Creates webhook subscription for selected topics on the Shopify side to receive events

Configuration Fields

Select topics - (multi-select dropdown, required): Select available topics to create a subscription
Skip validation - (checkbox, optional): If checked - the component will not validate the incoming message to be sure that it comes from Shopify, use it for test purposes only!

Input Metadata

None.

Output Metadata

Event from the subscription on the selected topic

Limitations

Generate Stub Sample works only for the most used objects
This trigger doesn’t support Retrieve sample functionality
If you use ordinary flow (real-time not enabled) after flow starts you will need to run it once - just follow the webhook URL (to make the first execution) this action will create a subscription, error on this execution may be ignored

Known limitations

Look at Shopify API rate limits, specially GraphQL Admin API rate limits
If the component reaches API rate limit it will retry the request after waiting until the queue is restored up to 10 times: for example - a query costs 500 points, currently available only 100 points, the restore rate 50 points/second, the component will wait 8 seconds until available points will be restored and try again to get data

Be careful with several flows running at the same time, each of them can affect on total available points, if the component won’t be able to get data after 10 retries, then the error "Throttled" will be thrown

Click here to learn more about the elastic.io iPaaS

Shopify Admin v2 component

Shopify admin Component

Table of Contents

Description

Credentials

Notes:

Actions

Delete Object

Create Object

Update Object

Upsert Object

Configuration Fields

Input Metadata

Output Metadata

Execute mutation

Configuration Fields

Input Metadata

Output Metadata

Lookup Objects (plural)

Configuration Fields

Input Metadata

Output Metadata

Example

Lookup Object By ID

Configuration Fields

Input Metadata

Output Metadata

Make Raw Request

Configuration Fields

Input Metadata

Output Metadata

Triggers

Get New and Updated Objects Polling

Configuration Fields

Input Metadata

Output Metadata

Webhook

Configuration Fields

Input Metadata

Output Metadata

Limitations

Known limitations