# Adding a custom (GraphQL) endpoint for Shopify

## Introduction

Shopify is phasing out its REST API capabilities and strongly recommends transitioning to GraphQL. If you've been using the Shopify connector with REST API endpoints, we advise [updating the connector from the Patchworks marketplace](https://doc.wearepatchworks.com/product-documentation/connectors-and-instances/working-with-connectors/updating-a-connector), so GraphQL endpoints are available. 

When browsing endpoints for the latest Shopify connector, you'll find that REST API endpoints are prefixed with the word `LEGACY`, and `GraphQL` endpoints are available:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F5Pr4h0ZT0k6nJTHCdCpa%2Fendpoint%20browse%202.png?alt=media&#x26;token=7b475a94-391c-4299-ada1-b8dfe40f1a0b" alt=""><figcaption></figcaption></figure></div>

A key advantage of GraphQL is that connector endpoints can be configured with queries that request only the data needed, minimising information over and under-fetching.

[Our Shopify connector](https://doc.wearepatchworks.com/product-documentation/connectors-and-instances/patchworks-connectors/shopify-prebuilt-connector) includes a range of predefined GraphQL endpoints with queries for different entity types (products, customers, orders, etc.). However, GraphQL is so flexible that you may want to add custom endpoints to the Shopify connector, with more targeted queries for your needs. This guide walks through the steps needed to achieve this.

## Preparation

Ensure that your Patchworks Shopify connector is up to date. For more information please see [Updating a connector](https://doc.wearepatchworks.com/product-documentation/connectors-and-instances/working-with-connectors/updating-a-connector).

## The steps

Our suggested approach for adding custom GraphQL endpoints is to take a copy of an existing endpoint with similar properties and then edit the copy as needed. These steps are detailed in two stages:

* [Stage 1: Clone an existing endpoint](#stage-1-clone-an-existing-endpoint)
* [Stage 2: Edit your new endpoint](#stage-2-edit-your-new-endpoint)

## Stage 1: Clone an existing endpoint

**Step 1**\
Log in to the [Patchworks dashboard](https://app.wearepatchworks.com/login) and select `process flows` from the left-hand navigation menu:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2Fg9F8ssFShEYDQ08LDnsK%2F1.png?alt=media&#x26;token=9bc33f4b-b069-4dac-bae7-4efd56a814cb" alt="" width="563"><figcaption></figcaption></figure></div>

**Step 2**\
Select `connectors & instances`:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FznMqU8KwgSaZgWNewTpK%2F2.png?alt=media&#x26;token=21f1b4ce-f5a6-4f80-a6fa-9dd40e64fc2f" alt="" width="563"><figcaption></figcaption></figure></div>

**Step 3**\
Click the `settings icon` associated with your Shopify connector:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FpiN8isUY9C7f7Qte2uA4%2F3.png?alt=media&#x26;token=254f961e-1b78-46be-9336-1ec162f62a77" alt=""><figcaption></figcaption></figure></div>

**Step 4**\
You're now in the [connector builder](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder) - click the `endpoints` option:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F5XXLWLH0FDbD8Z1LWzQt%2F4.png?alt=media&#x26;token=f2a756a5-508f-4957-863e-4a04157d0a8d" alt="" width="563"><figcaption></figcaption></figure></div>

**Step 5**\
Find an existing GraphQL query that's similar to the one you want to add. For example, if your new query relates to retrieving customer records, the `GraphQL Retrieve a list of customers` endpoint would be a good option:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2Fnzz2XnqVxL1bKNlLQUfK%2F5.png?alt=media&#x26;token=e65ebe15-a3a4-411f-880d-54ee6e1635ff" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
Endpoints are organised by entity type - you can scroll through this list, or CTRL+F or CMD+F to search on the name.
{% endhint %}

**Step 6**\
Scroll to the right and select the `clone` option:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FIW8YHY5pAG8yS5zWCanu%2F6.png?alt=media&#x26;token=8616c1b5-3155-43e5-8caa-c0afc2b81145" alt=""><figcaption></figcaption></figure></div>

**Step 7**\
You'll see two confirmation messages - the first advising that the clone task is queued and the second confirming when the task is completed (these are typically instant but may take longer in busy times) - for example:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FL3Ngl1az849h4rxr04Fw%2F7a.png?alt=media&#x26;token=9d1d8ef1-709a-4b40-a5da-5e38ed67de48" alt=""><figcaption></figcaption></figure></div>

**Step 8**\
Refresh the page (CTRL+ R or CMD+ R). Now you should see a copy of the endpoint with an incremented number in brackets - for example:

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FoNhAA1YUcTRGW0FVCwka%2F8.png?alt=media&#x26;token=613d6a39-41b8-42dd-9034-148d241a996c" alt=""><figcaption></figcaption></figure>

## Stage 2: Edit your new endpoint

**Step 1**\
Click the name of the newly cloned endpoint:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F8OkXwyfPqluxs44T0the%2Fa1.png?alt=media&#x26;token=a52523cc-cd55-4a54-8601-33dc3075c6b3" alt=""><figcaption></figcaption></figure></div>

You're now viewing the setup for this endpoint, with general details in the upper panel and a series of tabs in the lower panel:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F0Xhlo5yaqkknMLeH2MI3%2Fa1a.png?alt=media&#x26;token=f232872e-05fc-4a3c-89c4-539b40dbfc34" alt=""><figcaption></figcaption></figure></div>

**Step 2**\
Change the name to reflect the purpose of this endpoint (the name entered here is displayed to users when configuring [connector shapes in process flows](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape/using-connector-shape-response-scripts)) - for example:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FGEzYh6QbyY4iBHUMmE0e%2Fa2.png?alt=media&#x26;token=8d1be149-1ec5-443b-a654-6e2868ee5866" alt=""><figcaption></figcaption></figure></div>

**Step 3**\
Update remaining fields in this panel, if necessary:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FmWHiXSeckuzv4dV2UUcA%2Fa3.png?alt=media&#x26;token=6ab3a1ac-3c4f-4f7d-a826-7726773fab11" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
If you started this task by [cloning a similar endpoint](#stage-1-clone-an-existing-endpoint), you may not need to change the entity type or direction. For further information about these options, please see our [connector builder documentation](https://doc.wearepatchworks.com/product-documentation/connectors-and-instances/event-connectors-beta/adding-a-new-event-connector).
{% endhint %}

**Step 4**\
Move down to the lower panel (where the authentication tab is displayed) and toggle `token authentication` to `on`:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FWy070SkFrUOVtFNIfpWb%2Fa4.png?alt=media&#x26;token=da1b78fa-613e-4b1c-b6ba-952e737a069b" alt=""><figcaption></figcaption></figure></div>

...you'll see a confirmation message when this authentication method is added:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FKrxIdbP3ww2wg1clFSBB%2Fa5.png?alt=media&#x26;token=77103247-6db6-493f-8a9a-fce01227fcc6" alt=""><figcaption></figcaption></figure></div>

**Step 5**\
Not all endpoints require variables - check the [Shopify API documentation](https://shopify.dev/docs/api/admin-graphql) and if needed, click the `variables` tab to add them:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FGBPTo7z33Qj3RWEoclSY%2Fa6.png?alt=media&#x26;token=970ac479-b8de-477e-b087-7e223c4ee68c" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
For further information about these options, please see our [connector builder documentation](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints/endpoint-options/endpoint-variables).
{% endhint %}

**Step 6**\
Click the `URL` tab and set the following options:

| Option      | Required setting                                                    |
| ----------- | ------------------------------------------------------------------- |
| HTTP method | PUT                                                                 |
| URL         | https\://{store\_name}.myshopify.com/admin/api/2025-01/graphql.json |

For example:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FGWGig8GnHUGGmlFZZ9K2%2Fa7.png?alt=media&#x26;token=a51f0f1c-58fa-4481-9b86-3cc04a78bfaf" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
Shopify GraphQL queries are executed by sending POST HTTP requests to the following endpoint:

`https://{store_name}.myshopify.com/admin/api/2025-01/graphql.json`.
{% endhint %}

{% hint style="info" %}
This `URL` includes a `{store_name}` variable that is resolved from the Shopify store name that's entered when instances for this connector are added and used in process flows - you don't need to change anything here.
{% endhint %}

**Step 7**\
Click the `header` tab. Unless the [Shopify API documentation](https://shopify.dev/docs/api/admin-graphql) states otherwise, `header` information is always the same, so the details shown for your cloned endpoint don't need to be changed:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FvS29YuAJqYQwYklxBT3Y%2Fa8.png?alt=media&#x26;token=5ae4b924-f038-4305-adb8-21fc83aa2730" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
For reference, the header includes one parameter named `X-Shopify-Access-Token`, with a value set to `{{token}}`.
{% endhint %}

**Step 8**\
Click the `body` tab - here you'll find the GraphQL query for the endpoint you cloned earlier:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FggBaHsrQpjrO2q1fU7JU%2Fa9.png?alt=media&#x26;token=69ef2023-25f7-4192-b58a-393476d0bc69" alt=""><figcaption></figcaption></figure></div>

...from here, you can edit the existing query as needed.

{% hint style="info" %}
Queries for existing GraphQL endpoints (installed with the Shopify connector) include pagination settings - for example:

`{ customers(first: 50 query: $query {{pagination_cursor}}) { pageInfo {startCursor hasPreviousPage hasNextPage endCursor}`

These work in conjunction with our predefined `GraphQL cursor` pagination method, and can be updated as required. You can learn more about GraphQL pagination in [Shopify's API documentation](https://shopify.dev/docs/api/usage/pagination-graphql#how-it-works).
{% endhint %}

**Step 9**\
Schemas aren't required for GraphQL queries. With so much flexibility to control what fields are returned by queries, adding a schema can often become confusing and difficult to maintain - general (though not mandatory) advice is to ignore the `schema` tab for GraphQL endpoints.

**Step 10**\
Click the `pagination` tab and set the following options:

<table><thead><tr><th width="359">Option</th><th>Required setting</th></tr></thead><tbody><tr><td>Pagination method</td><td>GraphQL Cursor</td></tr><tr><td>EndCursor path</td><td>data.<strong>entity</strong>.pageInfo.endCursor/graphql.json<br><br>Replace the <code>entity</code> element with the data element you're querying - for example:<br><br><code>data.customers.pageInfo.endCursor</code></td></tr><tr><td>HasNextPage path</td><td>data.<strong>entity</strong>.pageInfo.hasNextPage<br><br>Replace the <code>entity</code> element with the data element you're querying - for example:<br><br><code>data.customers.pageInfo.hasNextPage</code></td></tr></tbody></table>

For example:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FXDFfZdoueZP8FhPuciHB%2Fa11.png?alt=media&#x26;token=bed0e1f1-25a2-45d7-980a-1678114af778" alt=""><figcaption></figcaption></figure></div>

**Step 11**\
Save changes to return to the list of endpoints:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F6KOGdiGX0OroWFJHAqd4%2Fa12.png?alt=media&#x26;token=a27133d3-795b-42a5-9a40-b4fc26398eb5" alt=""><figcaption></figcaption></figure></div>