> For the complete documentation index, see [llms.txt](https://doc.wearepatchworks.com/product-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/2-connector-variables.md).
# 2: Connector variables
## Introduction
A variable is a value that can change, depending on conditions or information supplied by the user. Using the Patchworks connector builder, variables can be defined at different levels:
| Level | Summary |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Connector instance (connector variables)](#what-you-need-to-do) | **Connector instance variables** defined here can be used when you [configure authentication methods](/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/authentication-method-options.md). If you're defining multiple authentication methods which share common variables, define them once here and then choose to 'use' them in subsequent authentication methods. |
| [Authentication method (auth variables)](/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/authentication-method-options/auth-variables.md) | **Auth variables** (whether added directly or picked up and 'used' from predefined **connector instance variables**) are displayed as fields for your users to complete whenever the associated authentication method is used to [add a connector instance](/product-documentation/connectors-and-instances/working-with-instances/adding-an-instance.md). |
| [Endpoint variables](/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints/endpoint-options/endpoint-variables.md) | **Endpoint variables** are displayed as fields for your users to complete whenever they configure a process flow connection shape to use an associated endpoint. |
## About connector instance variables
The **variables** tab for a connector is used to define **connector** **instance-level** variables :
Users are prompted to provide values for these variables when they [add and authenticate an instance of this connector](/product-documentation/connectors-and-instances/working-with-instances/adding-an-instance.md). These values are then applied wherever this instance is used in process flows.
## How it works
Any variables defined here are available for use when you move on to define [authentication methods](/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods.md) for your connector.
If you [choose to use one of these variables in an authentication method](/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/authentication-method-options/auth-variables.md#adding-auth-variables), the result will be that your users are asked to provide a value for this field when they [add an instance](/product-documentation/connectors-and-instances/working-with-instances/adding-an-instance.md) of this connector, with the associated authentication method.
**Any value that the user provides during instance creation will be used whenever this instance is selected for use in process flows.**
When a [process flow](/product-documentation/process-flows/about-process-flows.md) runs (i.e. when API calls associated with selected endpoints for this instance are made), Patchworks grabs all defined variables and then injects them where a corresponding `{{variable}}` is found.
{% hint style="info" %}
In the Patchworks connector builder, variables must be defined in double curly brackets.
{% endhint %}
## Example
A great example of where defining an **connector instance-level** variable here is useful, can be found in the Shopify API. For any API request, Shopify requires a given `store_name` - for example:
{% code title="GET" %}
```
https://{{store_name}}.myshopify.com/admin/api/2023-04/customers.json
```
{% endcode %}
All API calls that users might want to use in [process flows](/product-documentation/process-flows/about-process-flows.md) are added to the Shopify connector as [endpoints](/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints.md). So, when a user configures a [connection shape](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape.md) in a process flow and selects a connector **instance** to use, they will have a list of **endpoints** associated with the selected instance to choose from - for example:
Whilst you COULD ask your users to enter the appropriate store name whenever they select an endpoint (via an [endpoint variable](/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints/endpoint-options/endpoint-variables.md)), this would be inefficient, and open to error.
A more efficient, reliable approach is to define a required `{{store_name}}` variable at the instance level. In doing so, the appropriate store name would be entered just once when an instance of this connector is [added](/product-documentation/connectors-and-instances/working-with-instances/adding-an-instance.md) - for example:
The value provided here is injected into any `{{store_name}}` variables found when this instance is used subsequently, in process flows.
### Precedence
If two variables with the same key are defined in two different places, we also prioritise them in `connector` -> `connector instance` -> `endpoint` order.
For example, if you define a `{{store_name}}` variable in an **authentication method** for a connector and then another `{{store_name}}` variable on an [endpoint](/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints/endpoint-options/endpoint-variables.md), the **endpoint** value would take precedence.
## What you need to do
To add new **system variables**, follow the steps below:
**Step 1**\
Click the **add new system variable** button:
**Step 2**\
Complete fields on the **add variable** page - for example:
{% hint style="info" %}
The **add variables** page is the same for all types of variables that you may encounter in the connector builder. For information about these options please see the [Working with variables](/product-documentation/developer-hub/connector-builder/building-your-own-connector/techniques-for-working-with-variables-and-parameters/working-with-variables.md) page.
For guidance on configuring variables for specific **authentication types**, please see our [Supported authentication types](/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/supported-authentication-types.md) section.
{% endhint %}
**Step 3**\
Click **save** to add this variable to the **variables** list - for example:
**Step 4**\
Repeat steps 2 and 3 for all required variables.
**Step 5**\
Click **next** for [authentication methods](/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods.md), where you can choose to use these variables, if needed.