ITMAROON EC RELATE BLOCKS

ITMAROON EC RELATE BLOCKS provides two Gutenberg blocks to integrate a headless Shopify commerce flow into a WordPress site:

• itmar/product-block

  • Links a WordPress post type to Shopify products.
  • When the linked posts are published/updated, the plugin can create/update the corresponding Shopify product data (depending on your configuration and permissions).
  • Designed for WordPress as the content layer (product pages) while Shopify remains the commerce layer (inventory + checkout).

• itmar/cart-block

  • Provides a cart UI powered by Shopify Storefront API Cart.
  • Sends shoppers to Shopify Checkout to complete payment.

Important concept (recommended operation): * Shopify is the source of truth for inventory and checkout. * WordPress is the source of truth for marketing/product content. * This plugin focuses on a smooth purchase flow from WordPress pages to Shopify Checkout.

Security / Data Handling (Important)

• Admin API Token and Storefront API Token are saved server-side in WordPress options via REST and are NOT embedded into post content or rendered into front-end HTML.
• The editor UI no longer persists secret tokens as block attributes. Tokens should never be stored in post_content.

Block Overview

= itmar/product-block = Use this block in the Site Editor (template) to enable Shopify connection and product linkage for a selected post type.

Main settings (Block Inspector → “EC setting”): * Select Product Post Type * Store Site URL (Shopify domain) * Shop ID (for Customer Account API) * Channel Name (publication / sales channel display name) * Headless Client ID (Customer Account API client_id) * Admin API Token (saved server-side; not stored in post content) * Storefront API Token (saved server-side; not stored in post content) * Optional display controls (fields selector, display count, cart icon media ID, etc.)

itmar/cart-block

Use this block to show the cart UI. It uses Shopify Storefront API Cart endpoints to: * Create/update cart lines * Show totals * Provide a Checkout URL for completing purchase in Shopify Checkout

Shopify Setup (Required)

You need a Shopify store and API credentials.

1) Admin API Access Token (for product/customer management) * Create a Shopify app (Custom app) and generate an Admin API access token. * Grant only the minimum required permissions.

2) Storefront API Access Token (for product/cart/checkout flow) * Create a Storefront access token in Shopify.

3) Customer Accounts (Headless) (optional but recommended if you enable customer login) * Enable the new Customer Accounts / Customer Account API in Shopify. * Install Shopify “Headless” (sales channel) and obtain the “Client ID” used for OAuth (Customer Account API). * You will also need the “Shop ID”. – Tip: You can derive Shop ID from the issuer value in: https://{your-shop-domain}/.well-known/openid-configuration

Quick Start (Recommended Workflow)

1) Configure connection settings * Open the Site Editor. * Add itmar/product-block to a global template (e.g., Header, or a dedicated template used site-wide). * In the block Inspector → “EC setting”, enter: – Shopify domain (Store Site URL) – Channel Name (e.g., “Online Store”) – Headless Client ID / Shop ID (if using customer login) – Admin API Token and Storefront API Token (saved to WordPress options)

2) Choose the linked post type * In itmar/product-block, select your product post type (e.g., “product”).

3) Add the cart * Add itmar/cart-block to a template/page where you want the cart UI to appear.

4) Publish product posts * Create or edit posts in the selected post type. * Publish/update them to trigger Shopify-side creation/update (based on your configuration).

Related Links

• ec-relate-blocks: GitHub https://github.com/itmaroon/itmaroon-ec-relate-blocks
• block-class-package: GitHub https://github.com/itmaroon/block-class-package
• block-class-package: Packagist https://packagist.org/packages/itmar/block-class-package
• itmar-block-packages: npm https://www.npmjs.com/package/itmar-block-packages
• itmar-block-packages: GitHub https://github.com/itmaroon/itmar-block-packages

Developer Notes

1. PHP class management is done using Composer.
2. Shared functions/components are published as an npm package and reused across plugins.

External Services

This plugin connects to external services to provide e-commerce functionality.

Shopify

Service provider: * Shopify

Domains contacted: * The Shopify shop domain configured by the site administrator (e.g. *.myshopify.com or a custom Shopify domain) for Admin API / GraphQL Admin API requests. * shopify.com for authentication / OAuth token exchange (when customer login is enabled). * Shopify-operated domains used for checkout and storefront features (depending on configuration).

APIs used (depending on your configuration/features enabled): * Shopify Admin API (product/customer management) * Shopify GraphQL Admin API (graphql.json) * Shopify Storefront API (product/cart/checkout flow) * Shopify Customer Account API / OAuth endpoints (optional customer login)

Data that may be sent to Shopify: * Store domain, channel name, and API credentials / access tokens (server-side) * Product data required for creating/updating products (title, description, image, sales price, list price, quantity in stock) – The title is the title of the post data sent. – The description is an excerpt of the post data sent. – The image is the featured image, if one is set. Furthermore, if the ACF custom field has a gallery field named « gallery », images in that field will also be added. – The sales price is the price set in the « prces » group set in the ACF custom field if « sales_price » is set as a member. – The list price is the price set in the above group if « list_price » is set. – The stock quantity is set as the default quantity if « quantity » is set in the ACF custom field. However, this does not reflect your sales history in Shopify, so do not use it outside of the initial setup. * Cart line items (variant IDs and quantities) * Customer authentication and identity linkage (OAuth code exchange, customer access tokens when enabled) * When uploading product images via Admin API: image data (or image URLs) and related metadata for Shopify product images. * For authentication / OAuth token exchange (when enabled): OAuth codes and token exchange parameters.

When data is sent: * When saving settings (admin only) * When rendering product/cart features or performing cart actions * When creating/updating Shopify products based on WordPress post changes * When performing customer authentication (if enabled) * When exchanging OAuth tokens (e.g. https://shopify.com/authentication/{shop_id}/oauth/token) if enabled.

Important: * Shopify is responsible for payment processing and checkout. * As with any HTTP request, the WordPress server’s IP address and user agent may be included in requests to Shopify.

Terms / Privacy: * Shopify Terms of Service: https://www.shopify.com/legal/terms * Shopify Privacy Policy: https://www.shopify.com/legal/privacy * Shopify API License and Terms of Use: https://www.shopify.com/legal/api-terms

GitHub (raw.githubusercontent.com) – Shopify Product Taxonomy

This plugin downloads a taxonomy text file hosted on GitHub (raw.githubusercontent.com) to provide a category list used by the plugin.

Domain contacted: * raw.githubusercontent.com

Data that may be sent and when: * When the taxonomy list is fetched/updated, the WordPress server requests a file such as: https://raw.githubusercontent.com/Shopify/product-taxonomy/main/dist/ja/categories.txt * No user/customer data is intentionally sent for this action, but the WordPress server’s IP address and user agent may be included in the request.

Terms / Privacy: * GitHub Terms of Service: https://docs.github.com/site-policy/github-terms/github-terms-of-service * GitHub Privacy Statement: https://docs.github.com/site-policy/privacy-policies/github-privacy-statement