Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The Shopify & Virtualstock Supplier blueprint includes everything you need to sync orders, fulfillments, and inventory between Shopify & Virtualstock Supplier. This section guides you through installing and configuring the blueprint.
In Shopify, you need to create an app/sales channel for Patchworks and then grant access for Patchworks to access your data. This is completed in two parts:
. Create a Patchworks app/sales channel and enable general API scopes for Patchworks to access your data.
. Enable specific scopes for Patchworks to access products associated with the Patchworks app/sales channel.
Admin API scopes must be set to allow the Shopify connector to access your data via the Shopify Admin API. This is a standard requirement for the Shopify connector, irrespective of whether it's been installed as part of an app or as a standalone connector.
Please follow the steps detailed on our page under Obtaining credentials, then go to .
Storefront API scopes are not required for general use but they ARE needed for the Shopify & Virtualstock Supplier blueprint. Please follow the steps below to grant the required access permissions.
Step 1 Still in the Shopify admin portal with your Patchworks app/integration, select the review configuration option from the overview tab:
Step 2 Scroll to the end of the page and select the configure button for Storefront API integration:
Step 3 In the list of scopes, scroll down to the Products section and enable the following three items:
unauthenticated_read_product_listings
unauthenticated_read_product_inventory
unauthenticated_read_product_tags
For example:
Step 4 Save your changes.
Step 5 Go to the .
In this stage you will locate the Shopify & Virtualstock Supplier blueprint in the Patchworks marketplace, then configure instances for required connectors and install the blueprint.
Having completed all the steps detailed below, the Shopify to Virtualstock Supplier blueprint will be installed and all required resources become available in your dashboard. These include:
Step 1 Log in to the Patchworks dashboard and navigate to the public marketplace.
Step 2 Ensure the blueprints tab is selected, then locate the Shopify & Virtualstock Supplier app:
Having purchased a blueprint from the Patchworks website, it will be available in your apps marketplace within 24 hours.
Step 3 Click the Shopify & Virtualstock Supplier blueprint to view details:
Step 4 Scroll down to the Connectors section and select the Add instance option for Shopify:
...then enter details for the Shopify store that you want to use for testing:
Please see our Adding an instance page for general guidance about adding new instances. For Shopify requirements please refer to our Shopify (prebuilt connector) page.
Adding connector instance credentials here saves some time later since this will auto-configure relevant connector shapes in related process flows.
Step 5 Move over to the Virtualstock Supplier connector and select the Add instance option:
...then enter details for Virtualstock Supplier that you want to use for testing:
Please see our Adding an instance page for general guidance about adding new instances. For specific Virtualstock Supplier requirements, please see our Virtualstock (prebuilt connector) page.
Step 6 Click the install button at the top of the page to install the app:
For guidance on blueprint installation please see our Installing a blueprint page.
Step 7 Once the blueprint is installed successfully, go to the next stage.
It is strongly recommended that you provide authentication credentials for Shopify and Virtualstock Supplier connector instances as part of the . This approach means that newly installed process flows are pre-configured with the required instance/endpoint details.
However, if you don't have your credentials but want to install the blueprint anyway (or if you missed this step during installation), you can add instances retrospectively and then update process flows manually.
Step 1 Follow the steps in our guide to add one instance for Shopify and one for Virtualstock Supplier.
Step 2 Access the Orders process flow and edit settings for each connector shape in the flow (there are 4). Ensure that each one is set as per our .
Step 3 Access the Fulfillments process flow and edit settings for each connector shape in the flow (there are 2). Ensure that each one is set as per our .
Step 4 Access the Inventory process flow and edit settings for each connector shape in the flow (there are 3). Ensure that each one is set as per our .
Step 5 Continue with this installation guide.
The Shopify & Virtualstock Supplier blueprint syncs Shopify products associated with your Patchworks sales channel (created in the ). As such, you should ensure that any products you want to sync between Shopify and Virtualstock Supplier are added to this sales channel.
Your Patchworks sales channel should ONLY include products you want to sync between these two systems - adding products that don't need to be synced increases processing time.
Step 1 In Shopify, access your product list and find the first product you want to sync with Virtualstock Supplier.
Step 2 In the Publishing section, select the manage sales channels option:
It doesn't matter if the products you want to sync with Virtualstock Supplier are in other channels too.
Step 4 Repeat steps 1 to 3 for all other products that need to be synced with Virtualstock Supplier.
Step 3 Select your Patchworks app/sales channel (created in the ) and save changes:
Step 5 Go to the .
In this stage you will access the [[Orders]] Virtualstock >> Shopify process flow.
The process flow is pre-configured with all required settings, including any connector instances you defined as part of the installation stage. On this page, we guide you through recommended checks so you can ensure the flow meets your requirements.
Step 1 Select process flows > process from the left-hand navigation menu (or click here). Your process flow list is displayed - for example:
If you've used Patchworks before installing the Shopify & Virtualstock Supplier blueprint, you might see more than the three process flows shown here.
Step 2 Click the [[Orders]] Virtualstock >> Shopify entry to open the process flow in edit mode.
Step 3 Access settings for the trigger shape and edit the default schedule to reflect the frequency you want this process flow to run:
For guidance on defining trigger schedules, please see our Trigger shape page.
Any schedule you define here won't affect the number of new orders received - just how frequently you collect them.
New orders are determined by order status (rather than any time-based conditions). When the process flow runs, any orders with an ORDER status are pulled from Virtualstock Supplier and sent into Shopify - you can see this if you check the settings for the first connector shape in the flow:
When this operation is completed successfully, the order changes to an ORDER_ACK status, so it will never be picked up again in subsequent flow runs.
Step 4 Access settings for the first map shape and scan down the list to ensure the default settings meet your requirements. Here we are mapping FROM Virtualstock Supplier TO Shopify.
Generally, default mappings do not need to be changed however, the following fields should be checked with particular care and changes can be made if necessary:
Order.Inventory_behaviour
part_number > variant_id
The following fields must NOT be changed:
Order Line Properties
Order notes
Order source_name
If you would like to map additional fields (for example, billing address), this is fine. For guidance on defining field mappings, please see our Working with field mappings page.
Step 5 Access settings for the second map shape and scan down the list to ensure the default settings meet your requirements. Here we are mapping FROM Shopify TO Virtualstock Supplier.
Generally, default mappings do not need to be changed however, the following fields should be checked with particular care:
supplier_delivery_date
Fulfillment_route
This attribute is used to send an acknowledgement back to Virtualstock Supplier after an order is created in Shopify.
It should not be necessary to map additional fields here.
Step 6 In Virtualstock Supplier, make sure you have some test orders (with an ORDER status) using part numbers that you added to the SKU lookup table previously.
Step 7 Access settings for every connector shape in the flow (there are four) and double-check that the source instance is for a sandbox environment - for example:
Step 8 When you're satisfied that the flow is ready to test, click the initialise flow button from the actions bar:
The process flow should run and complete successfully. Check that the outcome is as expected in Shopify and Virtualstock Supplier.
Step 9 Go to the next stage.
Cross-reference lookup tables are used to convert given Shopify values to Virtualstock Supplier values. Conversion values are defined here and then called in process flow runs via cross reference lookup transformations applied to field mappings.
The following cross-reference lookup tables are installed as part of the Shopify & Virtualstock Supplier blueprint:
SKU Lookup
Convert Virtualstock Supplier part numbers to Shopify SKUs (and vice versa).
In Shopify, the variantId is used when creating a sales order. Patchworks makes a GraphQL call into Shopify to search for variantId based on the SKU, therefore the SKU must be unique.
Carrier Mapping
Convert your Shopify tracking_company values to Virtualstock Supplier carrier values.
You need to update these with your required values. You can add just a few that you know will cover testing requirements and come back to complete these tables later, or you can add everything now - it's up to you.
The steps below show how to update cross-reference lookup tables manually however, you can also import values (recommended for larger updates).
For more information about cross-reference lookups, please see our cross-reference lookups pages.
Step 1 Select process flows > cross-reference lookups from the left-hand navigation menu (or click here). You will see two installed cross-reference tables: Carrier Mapping and SKU Lookup. For example:
Step 2 Click the Carrier Mapping entry to view existing entries for converting Shopify carrier values (on the left) to Virtualstock Supplier carrier values (on the right):
Step 3 Add/update/remove existing entries as appropriate (placeholder values can be edited or removed).
Your Virtualstock Supplier merchant (e.g. John Lewis) should provide your required values.
When we apply this table to a cross-reference lookup field transformation, we can choose whether the conversion is left-to-right or right-to-left.
Step 4 Check the default value and change it as appropriate (leave blank for no default). If you change the default value, click the update button to confirm.
Step 5 Save changes.
Step 6 Navigate back to the Cross-Reference lookups page and click the SKU Lookup entry to view existing entries for converting Virtualstock Supplier part numbers (on the left) to Shopify SKUs (on the right), and versa:
When we apply this table to a cross-reference lookup field transformation, we can choose whether the conversion is left-to-right or right-to-left.
Step 7 Add/update/remove existing entries as appropriate (placeholder values can be edited or removed).
Step 8
Ensure that the default value is set to n/a. This is important as a subsequent filter will check for this.
Step 9 Save changes.
Step 10 Go to the next stage.
The process flow includes a field mapping which takes Shopify's order.created_at date and (via a script transform function on the mapping row) adds 5 days before sending this to Virtualstock Supplier as the supplier_delivery_date.
The 5 days that gets added here can be changed by amending the script that is used by the script transform function on the mapping row.
The required steps are detailed below:
Step 1 Select process flows > scripts from the left-hand navigation menu (or click ).
Step 2 Click the Calculate dispatch date using orderDate entry:
Step 3
Move down to the code panel and change the existing 5 days to your required number:
Do not make any other changes!
Step 4 Save and deploy the script:
Step 2 Access the Orders process flow.
Step 3 Scroll down the flow and access settings for the LAST map shape:
Step 4
Click the transform icon associated with the order.created_at > supplier_delivery_date row:
Step 5 Click the edit icon associated with the other script function:
Step 6 Select the latest version of the Calculate dispatch date using orderDate script:
Step 7 Accept changes and save the shape.
In this stage you will access the [[Fulfillments]] Virtualstock >> Shopify process flow.
This flow assumes that the sales order is now in Shopify, and has been picked, packed, and shipped by the warehouse (with a tracking number). Now, Patchworks picks up any shipped or partially shipped orders from Shopify, sending tracking IDs and expected delivery dates to Virtualstock Supplier.
The process flow is pre-configured with all required settings, including any connector instances you defined as part of the . On this page, we guide you through recommended checks so you can ensure the flow meets your requirements.
Step 1 Select process flows > process from the left-hand navigation menu (or click ). Your process flow list is displayed - for example:
If you've used Patchworks before installing the Shopify & Virtualstock Supplier blueprint, you might see more process flows than the three shown here.
Step 2 Click the [[Fulfillments]] Virtualstock >> Shopify entry to open the process flow in edit mode.
Step 4 Access settings for the first connector shape (Shopify) and update parameter values:
These are parameters associated with Shopify's Retrieve a list of orders endpoint - they determine which orders are retrieved.
To be retrieved, an order must match ALL defined parameters.
Click the edit icon associated with each parameter and set it as required. Default settings are:
Generally, default mappings do not need to be changed however, the following fields should be checked with particular care:
It should not be necessary to map additional fields here.
Step 6 Access settings for the Virtualstock Supplier connector shape and double-check that the source instance is for a sandbox environment - for example:
Step 7 When you're satisfied that the flow is ready to test, click the initialise flow button from the actions bar:
The process flow should run and complete successfully. Check that the outcome is as expected in Shopify and in Virtualstock Supplier.
This affects your Shopify stock levels, and whether or not you will allow Shopify to receive the order if Shopify is out of stock. The default setting is: decrement_obeying_policy. For more information, please see .
This field mapping uses a cross-reference-lookup transform function to convert Shopify SKUs to Virtualstock Supplier part numbers. Make sure that your has been updated accordingly.
The supplier delivery date is generated using a script transform function on this field. Here, we call the , which calculates the supplier delivery date by adding a given number of days to the order creation date.
By default, 5 days are added. If you want to change this value, see .
By default, a custom string transform sends a text value of: Direct to customer. If necessary, you can change this value by editing the transform function. For guidance, please see our page.
Step 1 Select process flows > process flows from the left-hand navigation menu (or click ).
Step 3 Access settings for the and edit the default schedule to reflect the frequency at which you want this process flow to run:
The default, hourly schedule is recommended but if you change this setting, be sure to check the updated_at_min parameter in the connector shape to align with this (see next step). For guidance on defining trigger schedules, please see our page.
Step 5 Access settings for the and scan down the list to ensure that the default settings meet your requirements. Here we are mapping FROM Shopify TO Virtualstock Supplier.
Step 8 Go to the .
created_at_min
Retrieves any orders created in the last 10 days.
updated_at_min
Retrieves any orders updated in the last 1 hour. So, we are retrieving orders created in the last 10 days (see above) but ONLY if they have been updated in the last hour.
This parameter is set on the basis that the process flow runs every hour - if you changed your schedule frequency in Step 3, you should update this value accordingly.
financial_status
Retrieves any orders with a financial status of paid.
status
Retrieves any orders with a status of any.
fullfillment_status
Retrieves any orders with a fulfillment status of shipped,partial (covering cases where complete orders are shipped and where partial orders have been shipped).
tracking_company > carrier
This field mapping uses a cross-reference-lookup transform function to convert Shopify tracking company values to Virtualstock Supplier carrier values. Make sure that your Carrier Mapping cross-reference lookup table has been updated accordingly.
supplier_dispatch_date
No checks/changes are required but it's worth noting that the Virtualstock Supplier supplier_dispatch_date is set to the Shopify fulfillment created_at date.
supplier_delivery_date
The supplier delivery date is calculated using a custom dynamic date transform function. The default is 3 days on from Shopify's fullfillment created_at date. If required, you can edit this transform function and change the number of days used for this calculation.
For more information please see our Working with field transformations page.
When you're satisfied that your process flows are working as expected with test credentials, you're ready to go live. This is a two-stage process:
Currently, all connector shapes in your three process flows are configured with authentication credentials for access to sandbox/testing systems. These must now be changed to live/production credentials.
To do this, follow the instructions on this page to edit your Shopify and Virtualstock Supplier connector instances and apply new authentication credentials for your live/production environments.
Updating existing Shopify and Virtualstock Supplier connector instances with production credentials means you don't have to amend any process flows - the new credentials are applied automatically. This is the quickest and simplest approach.
However, some people prefer to create NEW connector instances with production credentials, so they can switch between the two - they may even duplicate process flows so a 'test' and 'production' version is always available. If you prefer to do this, the following guides may be useful:
Currently, your three Shopify & Virtualstock Supplier process flows are in a draft state, and disabled. For a process flow to run according to your defined trigger schedule, it must be deployed and enabled.
When you are ready, follow the instructions on the pages linked below for all three of your Shopify & Virtualstock Supplier process flows:
For the first few runs of each process flow, we recommend checking your run logs for warnings and errors - also check Shopify and Virtualstock Supplier to ensure that syncs are being processed as expected.
In this stage you will access the [[Inventory]] Virtualstock >> Shopify process flow.
Here, we pull products from Shopify (via their storefront API) that are assigned to the Patchworks sales channel - i.e. only SKUs associated with Virtualstock Supplier. This data is manipulated before Virtualstock Supplier part numbers are updated with a free stock quantity.
The process flow is pre-configured with all required settings, including any connector instances you defined as part of the installation stage. On this page, we guide you through recommended checks so you can ensure the flow meets your requirements.
Step 1 Select process flows > process from the left-hand navigation menu (or click here). Your process flow list is displayed - for example:
If you've used Patchworks before installing the Shopify & Virtualstock Supplier blueprint, you might see more process flows than the three shown here.
Step 2 Click the [[Inventory]] Virtualstock >> Shopify entry to open the process flow in edit mode.
Step 3 Access settings for the trigger shape and edit the default schedule to reflect the frequency at which you want this process flow to run:
The default setting is to run twice per day at 08:05 a.m. and 06:05 p.m This schedule is recommended to keep the inventory flow away from times when other process flows may be running since an inventory sync can take longer.
When setting your schedule, keep your rate limits in mind - how many calls can you make to Shopify at one time, and how many calls can you make to Virtualstock Supplier?
Step 4 Access settings for the first connector shape (Shopify) and review/update parameter values:
These parameters are associated with Shopify's Retrieve product listings published to your app endpoint - they determine which products are retrieved.
To be retrieved, a product must match ALL defined parameters.
Click the edit icon associated with each parameter and set it as required. Default settings are:
updated_at_min
Retrieves any orders updated in the last 24 hours.
Before saving/exiting these settings, ensure the source instance is for a test/sandbox environment.
Step 5 Access settings for other connector shapes (there are three in all) and double-check that the source instance is for a test/sandbox environment - for example:
Step 6 When you're satisfied that the flow is ready to test, click the initialise flow button from the actions bar:
The process flow should run and complete successfully. Check that the outcome is as expected in Virtualstock Supplier.
Step 7 Go to the next stage.
