Atlassian uses cookies to improve your browsing experience, perform analytics and research, and conduct advertising. Accept all cookies to indicate that you agree to our use of cookies on your device.
Atlassian uses cookies to improve your browsing experience, perform analytics and research, and conduct advertising. Accept all cookies to indicate that you agree to our use of cookies on your device. Atlassian cookies and tracking notice, (opens new window)
Shopify Public App: OneStock Connector for Shopify
OneStock APIs (products, inventory, orders)
OneStock webhooks
SFTP integration
Shopify webhooks for real-time synchronization
Shipping/BOPIS/PUDO order workflow
A customer places an order on Shopify.
The OneStock Connector transfers the order to OneStock OMS.
OneStock determines the optimal fulfillment location.
The order is fulfilled (shipped or prepared for pickup).
Status updates and tracking are sent back to Shopify.
Shipping order with delivery promise workflow
A customer places an order on Shopify with delivery promise information provided trhough OneStock Connector by OneStock OMS.
The OneStock Connector transfers the order to OneStock OMS.
OneStock determines the optimal fulfillment location.
The order is fulfilled (shipped or prepared for pickup).
Status updates and tracking are sent back to Shopify.
Product synchronization
Product integration overview
OneStock connector only integrates products with an active status in Shopify and with an EAN.
🔍 How it works technically
The product synchronization is only manual. It happens only when you click on the synchronize button in Shopify admin on the products area.
When you press the sync button, the connector performs the following steps:
Fetches a batch of 15 products from Shopify.
Extracts all variants associated with these products.
Sends a PATCH request to OneStock to update or create the corresponding items.
This process is repeated until all selected products and variants have been processed.
Products workflow
Manual trigger
query ($numProducts: Int!, $cursor: String) {
products(first: $numProducts, after: $cursor) {
nodes {
id
title
handle
description
category {
fullName
name
}
tags
media(first: 50) {
edges {
node {
preview {
image {
url
}
}
}
}
}
metafields(first: 50) {
edges {
node {
id
namespace
key
value
}
}
}
variants(first: 100) {
edges {
node {
displayName
id
sku
barcode
inventoryItem {
id
measurement {
weight {
unit
value
}
}
}
selectedOptions {
name
value
}
product {
id
}
barcode
metafields(first: 50) {
edges {
node {
id
namespace
key
value
}
}
}
inventoryItem {
measurement {
weight {
unit
value
}
}
}
price
image {
id
width
url
}
}
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
Please do not use the actual synchronize button on the configuration, it is not working. Analyze by OneStock team in progress.
Currently, when multiple systems import product data, the Onestock connector performs a full overwrite of existing data. As a result, information coming from other systems may be replaced in the OneStock OMS
Stock synchronization
Stock integration overview
OneStock connector requests OneStock to share an image of the stock with it so that it can then be made available for sale on Shopify.
🔍 How it works technically
The OneStock connector sends a POST /stock_export request to OneStock. This export can either be:
Triggered manually from the connector, or
Scheduled to run automatically (full or delta exports) at specific times.
For configuration details, see the internal documentation
When the stock export is ready on the OneStock side, OneStock sends a stock_export_completed webhook to the OneStock connector.
Once the export is ready, the connector reads the generated stock file and processes the first 250 lines. For these lines, the connector calls Shopify’s InventoryItem query to retrieve the corresponding InventoryItems needed to update stock in Shopify.
We expect to receive oneInventoryItemper SKU.
If this is not the case, it means there are duplicate SKUs in Shopify (the same SKU is linked to two different InventoryItem records).
In that scenario, the connector will attempt to perform two stock updates on the same SKU, each targeting a different InventoryItem.
Because we are limited to 250 InventoryItemimports per batch, duplicates can cause an issue: some SKUs present in the first 250 lines of the stock file may not be included in the InventoryItem response from Shopify and will therefore be excluded from the stock import.
Finally, the OneStock connector calls the Shopify inventorySetQuantities mutation (Admin GraphQL API) to import stock levels into Shopify. The connector updates the available type for each InventoryItem quantity at the relevant location.
Stocks workflow
mutation inventorySetOnHandQuantities($input: InventorySetOnHandQuantitiesInput!) {
inventorySetOnHandQuantities(input: $input) {
userErrors {
field
message
code
}
inventoryAdjustmentGroup {
id
changes {
name
delta
quantityAfterChange
}
reason
referenceDocumentUri
}
}
}
We higly recommend to only have one InventoryItem per sku
Order synchronization
Order integration overview
Refer to this page to have more detailed information.
🔍 How it works technically
If order synchronization is activated, OneStock connector create a webhook to listen to 3 topics in OneStock:
order_state_changed
parcel_state_changed
line_item_group_state_changed
We also start listenning ORDERS_CREATE and
ORDERS_UPDATED topics from Shopify.
If synchronise order is disabled, the impacts are:
Stopping the import of orders from Shopify
Stopping the creation of OneStock exports for integration into Shopify
Stopping the update of orders
Activating order synchronization does not result in the import of orders that were created in Shopify prior to activation. Previously triggered events are not replayed or recovered.
When Shopify triggers the webhookORDERS_CREATE. OneStock connector receives it. Please note this means that the order has not yet been paid for.
When Shopify triggers the webhookORDERS_UPDATED. OneStock connector receives it and updates the information field of the order in OneStock
Status synchronization
Status overview
Changes to order and return statuses are retrieved by the OneStock connector and transmitted to Shopify.
🔍 How it works technically
Thanks to information from topics order_state_changed, parcel_state_changed, line_item_group_state_changed, OneStock connector can update orders in Shopify.
Please note OneStock connector create fulfillment by API and Shopify update the Fulfillment Order.
Topic
Description
Topic
Description
order_state_changed
Only removed, fulfilled, collectable states are listened to. If the order is at one of those state, the connector checks if there are items that need to be hold. In case there are items that need to be hold removed, it applies a fulfillment on_hold on the related fulfillment order. In case there are items that need to be pickup prepaped, it applies a fulfillment ready_to_pickupon the related fulfillment order.
parcel_state_changed
Only dispatched and collected states are listened to. If a parcel is at one of those state, the OneStock connector create a fulfillment to fulfill for the related line items.
line_item_group_state_changed
Only removed state is listened to. If the line item group is at this state, it applies a fulfillment on_hold on the related fulfillment order.
The statuses listed above cannot be modified. Your workflow in OneStock must have these statuses in order to update Shopify correctly.
Delivery promise front integration
Delivery promise overview
OneStock connector allows you to use on your website the delivery promise module.
🔍 How it works technically
When we arrive at the checkout page, we retrieve the first delivery group that is offered to us by Shopify.
A DeliveryGroup is a set of cart lines that share the same delivery options.
A DeliveryGroup therefore contains:
targetedCartLines (the cart lines included in the group)
deliveryOptions (the delivery methods available for this group)
the isDeliveryRequiredproperty
Using the information provided intargetedCartLinesand the address entered by the customer at checkout, the OneStock connector calls the OneStockdelivery_promiseendpoint.
The response from thedelivery_promiseAPI is then used to display the availability of the delivery method in the checkout.
Delivery promise workflow
App proxy routes
OneStock Connector has two app proxy routes:
For delivery promises.
For stock export.
App proxies take requests to Shopify links, and redirect them to external links. This allows you to fetch and display data on a merchant's store from an external source. For more information about proxy app, refer to app proxies.
Use delivery_promise when you need delivery estimates. Use stock_export when you need a stock quantity snapshot. Choose based on the data you need to display.
These APIs are designed for use on Product Detail Pages (PDP) or later in the funnel (cart, checkout). They should not be called on Product Listing Pages (PLP) due to the volume of requests it would generate.
Delivery promise
POST /apps/onestock/proxy/delivery_promises
Returns estimates about the delivery of a product or a basket. A list of delivery options may be requested, providing the most detailed information possible about the delivery location. Based on these parameters and configurations, OneStock will estimate the delivery and return this estimate.
