Shopify Integration – Feature & Process Guide

Shopify is different in kind from the other channels Pentagon Connect connects to: it isn't a third-party marketplace with its own buyer traffic, category taxonomy or listing review process — it's a merchant's own storefront. Pentagon Connect connects to a seller's Shopify store much like it connects to BigCommerce or WooCommerce, and the seller's Shopify store is the single source of truth for its own products and orders rather than a shared marketplace catalogue. Because of that, there's no operator/seller/customer permission matrix to document here — the seller, via Pentagon Connect, has full control over their own store's listings, orders and refunds at every stage.

The connection is authorised once, via Shopify's standard app-install (OAuth) flow, and from then on Pentagon Connect reads and writes products, stock, orders, shipments and refunds directly against that store. Shopify stores track inventory by Location (a warehouse, physical store or pickup point); Pentagon Connect discovers a store's Locations and lets the seller choose a single default Location that all stock updates and shipments are pushed to. It does not currently split stock across multiple Locations — see Known Limitations.

Quick Reference

Product Management

Pricing & Stock

Orders & Fulfilment

Refunds, Returns, Cancellations & Claims

Product Management

Creating products

A product, its variants and its images are created in a single step. There's no separate marketplace-style category/attribute taxonomy to satisfy and no listing review process — once the product data is ready, it goes live on the store directly.

• Variants: every Shopify variant (e.g. each size/colour combination) is created as its own product record in Pentagon Connect and grouped together, the same way size/colour groups are handled on other channels. A product with only one variant is treated as a simple, non-variant product.
• Weight is mandatory on every product pushed to Shopify.
• Brand is sent as free text — Shopify has no brand taxonomy to validate against.
• Other item specifics (beyond weight and brand) are sent through as tags on the product rather than as structured attributes, since Shopify doesn't have a category-specific attribute system the way marketplaces do.
• Images can be set at both product and variant level — a shared image across all variants only needs to be set once and the rest inherit it; a distinct image per variant is also supported. Whether images are refreshed on an update is controlled by a per-listing setting, so images can be locked from being overwritten.
• New products are always pushed as active/live — there's no draft or staged state.

Updating products

Full content updates (title, description, images, attributes) run separately from price and stock updates, so any of the three can be refreshed independently without needing to resend the others.

• Metafields — Shopify's mechanism for custom/extra product attributes — are supported for simple text values, but each metafield has to be created or updated one at a time (no bulk write), and only the plain single-line-text type is supported out of the many types Shopify offers. When Pentagon Connect re-reads a product's metafields, it reconciles its own records against what Shopify currently has: existing ones are updated and anything that no longer exists on Shopify's side is removed locally.
• Updating an existing product's images can be switched off per listing, so a listing's photos on Shopify are left untouched even while other content keeps updating.

Deactivating / removing products

Shopify supports permanently deleting a product, and Pentagon Connect uses that hard delete rather than a pause/deactivate state. This is different from most marketplace integrations: once a product is removed this way, it can't be recovered simply by pushing it again — it has to be created from scratch.

Pricing & Stock Sync

• Price updates are sent product by product, with all of that product's variants included in the same update.
• RRP / strike-through pricing is only sent to Shopify when an RRP is set and is actually higher than the sale price; otherwise it's left out rather than sent as an invalid value.
• Stock updates are also sent product by product, though (unlike price) they aren't batched together with other variants in a way that survives a partial failure — if part of an update fails, Pentagon Connect can't always tell which specific variant caused it, so stock is pushed more conservatively than price.
• Multi-location stock is not split across a store's Locations. A Shopify store's Locations are discovered and made available so the seller can choose a single default Location; all stock updates and shipments go to that one Location rather than being allocated across several warehouses or pickup points.
• Shopify has no product-condition concept, so every product is treated as New — there's no equivalent of a "condition" field to sync.

Order Management

Getting orders

Orders are pulled in automatically and continuously. On first connection, the last 90 days of order history is backfilled; after that, orders and status changes are kept in sync on an ongoing basis.

One thing worth knowing: orders placed for local pickup or in-store (POS) delivery don't come through with a shipping address at all. Pentagon Connect fills the address in using the address configured on the store's relevant Location; if that Location also has no address on file, the order is still imported, but flagged as Incomplete with a note that the address is missing, rather than silently dropped.

Order information we store

For every order, Pentagon Connect stores:

• Order ID, order status, currency, order total and subtotal
• Buyer's billing and shipping address (name, company, address lines, city, state, postal code, country)
• Carrier, tracking number/URL and shipped date once shipped
• Per line item: SKU, product title, price, quantity, and that line's own shipped/unshipped/cancelled status

An order's overall status is worked out from its individual lines: if every line has shipped it's marked Shipped, if none have it's Unshipped, if every line is cancelled it's Cancelled, and any mix of shipped, unshipped and cancelled lines is marked Partially Shipped.

Shipping orders

Once an order (or part of an order) is ready, Pentagon Connect sends the carrier and tracking details to Shopify and marks it shipped.

• Partial shipment is supported — an order can be fulfilled and shipped in more than one package or batch, unlike some marketplace integrations that require a single full shipment.
• Carrier name is sent as free text; when it matches a carrier Shopify recognises (major couriers such as Royal Mail, UPS, DHL, FedEx, etc.), Shopify automatically generates a tracking link. An unrecognised carrier name is still accepted and stored, just without an automatic tracking link.
• Tracking can be updated later — if a tracking number is issued or changed after the fact, it can be pushed as an update to the existing shipment rather than needing a new one.

Cancellations

A full cancellation — covering every line of an order at full quantity, before anything has shipped — is handled as a single clean cancel-and-refund action. Any other cancellation scenario (part of an order, or an order that's already shipped) is handled through the refund flow instead, described below, rather than as a true cancellation.

Cancellation reasons available are: Customer Request, Fraud, Out of Stock, Payment Declined, Staff Error, and Other.

Refunds & returns

Refunds can be issued regardless of whether an order has shipped yet, which is a meaningful difference from marketplace channels where refund rights before shipment are often restricted to the marketplace operator. A refund can be:

• Full or partial, by quantity or amount, on the product lines
• Shipping-only, either a specific amount or a full shipping refund
• Product and shipping combined

There's no separate "return" object on Shopify — a customer return is processed as a refund, the same as any other refund scenario. Because it's the seller's own store, there's no operator/seller permission table to apply here: the seller has refund authority on their own orders at every stage, from before shipment through to after delivery.

Claims / incidents

Not applicable. Shopify, as a storefront rather than a marketplace, has no separate claims/incident mechanism the way marketplace operators (who mediate disputes between buyer and seller) do — refunds and returns cover this ground directly.

Known Limitations

• Stock is not split across multiple Locations. A store's Locations are discovered so a single default can be chosen, but stock updates and shipments all go to that one Location rather than being allocated across several warehouses or pickup points.
• Metafields are limited to plain text values, one at a time — no bulk writes and no support for Shopify's other metafield types (numbers, dates, references, etc.).
• Store collections (categories) can't be created or renamed from Pentagon Connect — only adding products to an existing collection and downloading the collection list are supported. Shopify offers no rename operation, and a delete-and-recreate approach would break every product already linked to the old collection.
• Collections can't be tied to the storefront's navigation menu.
• Pickup and in-store orders can arrive without a shipping address and depend on the store's Location having one configured, or the order is imported as Incomplete.
• Very large variant catalogues (stores using Shopify's extended variant model, with very high variant counts on a single product) may take multiple additional calls to fully download.
• Product/order syncing is additive — items removed on the Shopify side are not automatically detected or cleaned up on the Pentagon Connect side.
• No product-condition field — every product is treated as New, since Shopify has no condition concept.

Source Materials

This guide was built from Pentagon Connect's Shopify integration specifications covering authentication, product and catalogue management, pricing and stock sync, order retrieval, shipping, cancellations and refunds.