Shopify
Connect a Shopify store to Helios with a custom app token or your own OAuth app, and start workflows from store webhooks.
What your agents can do
Helios indexes the GraphQL Admin API 2026-10, including all 835 query and mutation fields in Shopify's public schema. Agents can search that API and make requests using your store's credentials. Shopify controls access through the app's scopes, store plan and feature eligibility.
- Read and update products, variants, inventory and collections.
- Inspect orders, customers, fulfillment, returns and discounts.
- Work with store content, markets and other Admin API resources.
- Start workflows from supported store webhook deliveries.
Storefront, Customer Account, Partner, Payments Apps and legacy REST APIs are outside this integration. For staged file uploads and bulk file downloads, agents use curl with the URLs Shopify returns. The integration does not provide a new dispute-evidence file upload flow.
Connect your store
Enter your store's permanent URL, such as https://your-store.myshopify.com. A storefront custom domain is not an Admin API host.
Custom app Admin API token
This is the default method. Enter the Admin API access token from your installed custom app and its API secret key. The secret key verifies webhook signatures; an API key by itself cannot authenticate Admin requests.
Existing admin-created custom apps continue to work, but Shopify no longer permits creating that app type. Grant the app the scopes your operations and topics need. These tokens do not refresh; replace a revoked token by following Shopify's installation process.
Your own Shopify app
Create a standalone app in Shopify's Dev Dashboard. Add the callback URL shown by Helios to the app's allowed redirect URIs. It ends in /integrations/shopify/oauth_callback. Enter Client ID and API secret key, then authorize the store.
Helios requests expiring offline access for background work, validates the callback's store and HMAC, and stores both tokens and their expiry times. It refreshes after an API request returns 401 and also schedules weekly refreshes to keep idle connections active. A revoked or expired refresh token requires reconnecting.
Helios requests the standard Admin scopes by default. Enable Restricted and legacy scopes only if your app has Shopify's approval and is eligible for those handles. This option also includes additional handles documented outside the central scope table and write_themes, which requires an exemption for public apps. Shopify can still reject scopes that your app cannot request.
The complete inventory includes all 146 scopes in Shopify's authenticated Admin scope table and 17 additional handles.
Default scopes
read_analytics_annotations
read_assigned_fulfillment_orders
read_cart_transforms
read_cash_tracking
read_checkout_and_accounts_configurations
read_checkout_branding_settings
read_companies
read_content
read_customer_data_erasure
read_customer_events
read_customer_merge
read_customers
read_delivery_customizations
read_discounts
read_draft_orders
read_files
read_fulfillment_constraint_rules
read_fulfillments
read_gift_card_transactions
read_gift_cards
read_inventory
read_inventory_shipments
read_inventory_shipments_received_items
read_inventory_transfers
read_legal_policies
read_locales
read_locations
read_marketing_events
read_markets
read_merchant_managed_fulfillment_orders
read_metaobject_definitions
read_metaobjects
read_online_store_navigation
read_online_store_pages
read_order_edits
read_orders
read_payment_customizations
read_payment_terms
read_pixels
read_price_rules
read_privacy_settings
read_product_listings
read_products
read_publications
read_reports
read_resource_feedbacks
read_returns
read_rollouts
read_script_tags
read_shipping
read_shopify_payments_accounts
read_shopify_payments_bank_accounts
read_shopify_payments_disputes
read_shopify_payments_payouts
read_store_credit_account_transactions
read_store_credit_accounts
read_themes
read_third_party_fulfillment_orders
read_translations
read_validations
write_analytics_annotations
write_app_proxy
write_assigned_fulfillment_orders
write_cart_transforms
write_cash_tracking
write_checkout_and_accounts_configurations
write_checkout_branding_settings
write_companies
write_content
write_customer_data_erasure
write_customer_merge
write_customers
write_delivery_customizations
write_discounts
write_draft_orders
write_files
write_fulfillment_constraint_rules
write_fulfillments
write_gift_card_transactions
write_gift_cards
write_inventory
write_inventory_shipments
write_inventory_shipments_received_items
write_inventory_transfers
write_legal_policies
write_locales
write_locations
write_marketing_events
write_markets
write_merchant_managed_fulfillment_orders
write_metaobject_definitions
write_metaobjects
write_online_store_navigation
write_online_store_pages
write_order_edits
write_orders
write_payment_customizations
write_payment_terms
write_pixels
write_price_rules
write_privacy_settings
write_products
write_publications
write_reports
write_resource_feedbacks
write_returns
write_script_tags
write_shipping
write_store_credit_account_transactions
write_third_party_fulfillment_orders
write_translations
write_validationsRestricted and legacy scopes (opt-in)
read_purchase_options
write_purchase_options
read_channels
write_channels
read_server_pixels
write_server_pixels
read_shopify_payments_legal_entities
read_capital
read_audit_events
read_buyer_membership_orders
read_images
read_quick_sale
read_analytics
read_gdpr_data_request
write_product_listings
read_checkouts
write_checkouts
read_all_orders
read_apps
read_checkout_settings
read_customer_payment_methods
read_delivery_promises
read_financial_kyc_information
read_marketplace_fulfillment_orders
read_marketplace_orders
read_marketplace_returns
read_merchant_approval_signals
read_mobile_platform_applications
read_own_subscription_contracts
read_payment_gateways
read_payment_mandate
read_payment_sessions
read_shopify_payments
read_shopify_payments_accounts_sensitive
read_shopify_payments_dispute_evidences
read_shopify_payments_dispute_file_uploads
read_taxes
read_users
write_checkout_settings
write_delivery_promises
write_marketplace_orders
write_marketplace_returns
write_mobile_platform_applications
write_own_subscription_contracts
write_payment_gateways
write_payment_mandate
write_payment_sessions
write_shopify_payments_dispute_evidences
write_shopify_payments_dispute_file_uploads
write_taxes
write_themesAdditional handles come from purchase options, the scope reference, webhook topic requirements, File permissions, admin-created apps and REST scopes.
Some scopes require Shopify approval, B2B, specific plans or a specialized app type. Protected customer data approval is separate from scope grants. read_all_orders supplements the order scopes for orders older than 60 days. Requesting a scope does not guarantee access.
Webhook triggers
Helios attempts to subscribe to all 235 HTTPS-compatible topics in the 2026-10 Admin schema. This includes orders, products, customers, inventory, fulfillment, returns, subscriptions, companies, markets, content and app events. The trigger picker lists every catalog event. The Shopify topic reference describes topic permissions and restrictions, and the payload reference shows event bodies.
Nine schema topics lack rendered documentation: attributed_sessions/first, attributed_sessions/last, checkout_and_accounts_configurations/update, machine_translation_batch/completed, publications/delete, subscription_contract_calculations/succeed, subscription_contract_calculations/fail, tax_partners/update and tax_summaries/create. Helios attempts them without inventing payload filters. Eligibility remains subject to Shopify's response.
The three compliance topics, customers/data_request, customers/redact and shop/redact, are excluded. They must be configured through Shopify's app configuration or dashboard, not the Admin subscription API. Configure compliance handling separately before distributing an app that requires it.
Filters follow the fields each documented payload provides:
| Payload family | Available filters |
|---|---|
| Full orders | Resource ID, email, tags, location, financial status, test order and source |
| Products | Resource ID, tags, vendor and product type |
| Inventory items and levels | Resource ID and SKU, or inventory item and location IDs |
| Customer segments and tags | Customer and segment IDs, or customer ID and tags |
| Fulfillment orders | Nested fulfillment order ID |
| Deletions and other reduced bodies | Only fields present in that topic's payload |
Filters are optional. IDs, tags and SKUs support patterns. Text filters match case-insensitive substrings; tag patterns ignore case. Selected values within a filter are alternatives, and separate filters must all match.
Setup lists existing subscriptions, updates those at this connection's webhook URL, and removes duplicates only after an update succeeds. A refused update keeps the old subscription. A topic appears as unavailable with Shopify's reason only when no subscription at that URL remains for it. Disconnecting removes subscriptions at that URL.
Set your app's webhook serialization version to 2026-10 in its Shopify configuration. The Admin mutation URL does not set the payload version. Avoid duplicate app-level registrations for topics Helios manages. Other topics can require scopes, app ownership or store features. Shopify App Pricing does not emit the classic subscription-change notifications.
Topic mapping
The table lists all 235 selectable events and the four excluded topics. Excluded topics have no Helios trigger.
| Shopify topic | Helios event or exclusion |
|---|---|
app/scopes_update | app.scopes_updated |
app/uninstalled | app.uninstalled |
app_purchases_one_time/update | app_purchase.updated |
app_subscriptions/approaching_capped_amount | app_subscription.capped_amount_approached |
app_subscriptions/update | app_subscription.updated |
attributed_sessions/first | attributed_session.first_attributed |
attributed_sessions/last | attributed_session.last_attributed |
bulk_operations/finish | bulk_operation.finished |
carts/create | cart.created |
carts/update | cart.updated |
channels/delete | channel.deleted |
checkout_and_accounts_configurations/update | checkout_and_accounts_configuration.updated |
checkouts/create | checkout.created |
checkouts/delete | checkout.deleted |
checkouts/update | checkout.updated |
collection_listings/add | collection_listing.added |
collection_listings/remove | collection_listing.removed |
collection_listings/update | collection_listing.updated |
collection_publications/create | collection_publication.created |
collection_publications/delete | collection_publication.deleted |
collection_publications/update | collection_publication.updated |
collections/create | collection.created |
collections/delete | collection.deleted |
collections/update | collection.updated |
companies/create | company.created |
companies/delete | company.deleted |
companies/update | company.updated |
company_contact_roles/assign | company_contact_role.assigned |
company_contact_roles/revoke | company_contact_role.revoked |
company_contacts/create | company_contact.created |
company_contacts/delete | company_contact.deleted |
company_contacts/update | company_contact.updated |
company_locations/create | company_location.created |
company_locations/delete | company_location.deleted |
company_locations/update | company_location.updated |
customer.joined_segment | customer.joined_segment |
customer.left_segment | customer.left_segment |
customer.tags_added | customer.tags_added |
customer.tags_removed | customer.tags_removed |
customer_account_settings/update | customer_account_settings.updated |
customer_groups/create | customer_group.created |
customer_groups/delete | customer_group.deleted |
customer_groups/update | customer_group.updated |
customer_payment_methods/create | customer_payment_method.created |
customer_payment_methods/revoke | customer_payment_method.revoked |
customer_payment_methods/update | customer_payment_method.updated |
customers/create | customer.created |
customers/delete | customer.deleted |
customers/disable | customer.disabled |
customers/enable | customer.enabled |
customers/merge | customer.merged |
customers/purchasing_summary | customer.purchasing_summary_updated |
customers/update | customer.updated |
customers_email_marketing_consent/update | customer_email_marketing_consent.updated |
customers_marketing_consent/update | customer_sms_marketing_consent.updated |
customers_whats_app_marketing_consent/update | customer_whatsapp_marketing_consent.updated |
delivery_promise_settings/update | delivery_promise_settings.updated |
discounts/create | discount.created |
discounts/delete | discount.deleted |
discounts/redeemcode_added | discount.redeemcode_added |
discounts/redeemcode_removed | discount.redeemcode_removed |
discounts/update | discount.updated |
disputes/create | dispute.created |
disputes/update | dispute.updated |
domains/create | domain.created |
domains/destroy | domain.destroyed |
domains/update | domain.updated |
draft_orders/create | draft_order.created |
draft_orders/delete | draft_order.deleted |
draft_orders/update | draft_order.updated |
finance_app_staff_member/delete | finance_app_staff_member.deleted |
finance_app_staff_member/grant | finance_app_staff_member.granted |
finance_app_staff_member/revoke | finance_app_staff_member.revoked |
finance_app_staff_member/update | finance_app_staff_member.updated |
finance_kyc_information/update | finance_kyc_information.updated |
fulfillment_events/create | fulfillment_event.created |
fulfillment_events/delete | fulfillment_event.deleted |
fulfillment_holds/added | fulfillment_hold.added |
fulfillment_holds/released | fulfillment_hold.released |
fulfillment_orders/cancellation_request_accepted | fulfillment_order.cancellation_request_accepted |
fulfillment_orders/cancellation_request_rejected | fulfillment_order.cancellation_request_rejected |
fulfillment_orders/cancellation_request_submitted | fulfillment_order.cancellation_request_submitted |
fulfillment_orders/cancelled | fulfillment_order.cancelled |
fulfillment_orders/fulfillment_request_accepted | fulfillment_order.fulfillment_request_accepted |
fulfillment_orders/fulfillment_request_rejected | fulfillment_order.fulfillment_request_rejected |
fulfillment_orders/fulfillment_request_submitted | fulfillment_order.fulfillment_request_submitted |
fulfillment_orders/fulfillment_service_failed_to_complete | fulfillment_order.fulfillment_service_failed_to_complete |
fulfillment_orders/hold_released | fulfillment_order.hold_released |
fulfillment_orders/line_items_prepared_for_local_delivery | fulfillment_order.line_items_prepared_for_local_delivery |
fulfillment_orders/line_items_prepared_for_pickup | fulfillment_order.line_items_prepared_for_pickup |
fulfillment_orders/manually_reported_progress_stopped | fulfillment_order.manually_reported_progress_stopped |
fulfillment_orders/merged | fulfillment_order.merged |
fulfillment_orders/moved | fulfillment_order.moved |
fulfillment_orders/order_routing_complete | fulfillment_order.order_routing_completed |
fulfillment_orders/placed_on_hold | fulfillment_order.placed_on_hold |
fulfillment_orders/progress_reported | fulfillment_order.progress_reported |
fulfillment_orders/rescheduled | fulfillment_order.rescheduled |
fulfillment_orders/scheduled_fulfillment_order_ready | fulfillment_order.scheduled_fulfillment_became_due |
fulfillment_orders/split | fulfillment_order.split |
fulfillments/create | fulfillment.created |
fulfillments/update | fulfillment.updated |
inventory_items/create | inventory_item.created |
inventory_items/delete | inventory_item.deleted |
inventory_items/update | inventory_item.updated |
inventory_levels/connect | inventory_level.connected |
inventory_levels/disconnect | inventory_level.disconnected |
inventory_levels/update | inventory_level.updated |
inventory_shipments/add_items | inventory_shipment.items_added |
inventory_shipments/create | inventory_shipment.created |
inventory_shipments/delete | inventory_shipment.deleted |
inventory_shipments/mark_in_transit | inventory_shipment.marked_in_transit |
inventory_shipments/receive_items | inventory_shipment.items_received |
inventory_shipments/remove_items | inventory_shipment.items_removed |
inventory_shipments/update_item_quantities | inventory_shipment.item_quantities_updated |
inventory_shipments/update_tracking | inventory_shipment.tracking_updated |
inventory_transfers/add_items | inventory_transfer.items_added |
inventory_transfers/cancel | inventory_transfer.cancelled |
inventory_transfers/complete | inventory_transfer.completed |
inventory_transfers/ready_to_ship | inventory_transfer.marked_ready_to_ship |
inventory_transfers/remove_items | inventory_transfer.items_removed |
inventory_transfers/update_item_quantities | inventory_transfer.item_quantities_updated |
inventory_transfers/updated | inventory_transfer.updated |
locales/create | locale.created |
locales/destroy | locale.destroyed |
locales/update | locale.updated |
locations/activate | location.activated |
locations/create | location.created |
locations/deactivate | location.deactivated |
locations/delete | location.deleted |
locations/update | location.updated |
machine_translation_batch/completed | machine_translation_batch.completed |
markets/create | market.created |
markets/delete | market.deleted |
markets/update | market.updated |
markets_backup_region/update | market_backup_region.updated |
metafield_definitions/create | metafield_definition.created |
metafield_definitions/delete | metafield_definition.deleted |
metafield_definitions/update | metafield_definition.updated |
metaobjects/create | metaobject.created |
metaobjects/delete | metaobject.deleted |
metaobjects/update | metaobject.updated |
order_transactions/create | order_transaction.created |
orders/cancelled | order.cancelled |
orders/create | order.created |
orders/delete | order.deleted |
orders/edited | order.edited |
orders/fulfilled | order.fulfilled |
orders/link_requested | order.link_requested |
orders/paid | order.paid |
orders/partially_fulfilled | order.partially_fulfilled |
orders/risk_assessment_changed | order.risk_assessment_changed |
orders/shopify_protect_eligibility_changed | order.shopify_protect_eligibility_changed |
orders/updated | order.updated |
payment_schedules/due | payment_schedule.became_due |
payment_terms/create | payment_terms.created |
payment_terms/delete | payment_terms.deleted |
payment_terms/update | payment_terms.updated |
product_feeds/create | product_feed.created |
product_feeds/full_sync | product_feed.full_sync_received |
product_feeds/full_sync_finish | product_feed.full_sync_finished |
product_feeds/incremental_sync | product_feed.incremental_sync_received |
product_feeds/update | product_feed.updated |
product_listings/add | product_listing.added |
product_listings/remove | product_listing.removed |
product_listings/update | product_listing.updated |
product_publications/create | product_publication.created |
product_publications/delete | product_publication.deleted |
product_publications/update | product_publication.updated |
products/create | product.created |
products/delete | product.deleted |
products/update | product.updated |
profiles/create | delivery_profile.created |
profiles/delete | delivery_profile.deleted |
profiles/update | delivery_profile.updated |
publications/delete | publication.deleted |
refunds/create | refund.created |
requested_order_edit/created | requested_order_edit.created |
requested_order_edit/declined | requested_order_edit.declined |
requested_order_edit/resolved | requested_order_edit.resolved |
returns/approve | return.approved |
returns/cancel | return.cancelled |
returns/close | return.closed |
returns/decline | return.declined |
returns/process | return.processed |
returns/reopen | return.reopened |
returns/request | return.requested |
returns/update | return.updated |
reverse_deliveries/attach_deliverable | reverse_delivery.deliverable_attached |
reverse_fulfillment_orders/dispose | reverse_fulfillment_order.disposed |
rollouts/create | rollout.created |
rollouts/delete | rollout.deleted |
rollouts/resource_change_added | rollout.resource_change_added |
rollouts/resource_change_removed | rollout.resource_change_removed |
rollouts/resource_change_updated | rollout.resource_change_updated |
rollouts/update | rollout.updated |
scheduled_product_listings/add | scheduled_product_listing.added |
scheduled_product_listings/remove | scheduled_product_listing.removed |
scheduled_product_listings/update | scheduled_product_listing.updated |
segments/create | segment.created |
segments/delete | segment.deleted |
segments/update | segment.updated |
selling_plan_groups/create | selling_plan_group.created |
selling_plan_groups/delete | selling_plan_group.deleted |
selling_plan_groups/update | selling_plan_group.updated |
shipping_addresses/create | shipping_address.created |
shipping_addresses/update | shipping_address.updated |
shop/update | shop.updated |
subscription_billing_attempts/challenged | subscription_billing_attempt.challenged |
subscription_billing_attempts/failure | subscription_billing_attempt.failed |
subscription_billing_attempts/success | subscription_billing_attempt.succeeded |
subscription_billing_cycle_edits/create | subscription_billing_cycle_edit.created |
subscription_billing_cycle_edits/delete | subscription_billing_cycle_edit.deleted |
subscription_billing_cycle_edits/update | subscription_billing_cycle_edit.updated |
subscription_billing_cycles/skip | subscription_billing_cycle.skipped |
subscription_billing_cycles/unskip | subscription_billing_cycle.unskipped |
subscription_contract_calculations/fail | subscription_contract_calculation.failed |
subscription_contract_calculations/succeed | subscription_contract_calculation.succeeded |
subscription_contracts/activate | subscription_contract.activated |
subscription_contracts/cancel | subscription_contract.cancelled |
subscription_contracts/create | subscription_contract.created |
subscription_contracts/expire | subscription_contract.expired |
subscription_contracts/fail | subscription_contract.failed |
subscription_contracts/pause | subscription_contract.paused |
subscription_contracts/update | subscription_contract.updated |
tax_partners/update | tax_partner.updated |
tax_services/create | tax_service.created |
tax_services/update | tax_service.updated |
tax_summaries/create | tax_summary.created |
tender_transactions/create | tender_transaction.created |
themes/create | theme.created |
themes/delete | theme.deleted |
themes/publish | theme.published |
themes/update | theme.updated |
variants/in_stock | variant.stock_replenished |
variants/out_of_stock | variant.stock_depleted |
audit_events/admin_api_activity | Excluded. Requires Google Cloud Pub/Sub or AWS EventBridge, so HTTPS delivery is unavailable. |
customers/data_request | Excluded. Requires separate app-level compliance handling. |
customers/redact | Excluded. Requires separate app-level compliance handling. |
shop/redact | Excluded. Requires separate app-level compliance handling. |
Errors and limits
A connection test reads the shop ID. HTTP errors, GraphQL errors and malformed probe responses fail the test. Shopify mutation userErrors and permission refusals explain unavailable webhook topics; transient failures leave setup eligible for retry.
Classic webhook deliveries contain one event. Helios verifies base64 HMAC-SHA256 over the raw body using the API secret key and deduplicates individual deliveries with X-Shopify-Webhook-Id. Shopify does not sign the timestamp header, so delayed deliveries are accepted. Array batches are rejected. Setup retains earlier app secrets so deliveries signed with the previous secret still verify during secret rotation.
GraphQL calls use Shopify's calculated-cost limits. Paginated requests accept at most 250 items, and ordinary traversal can reach Shopify's 25,000-object limit. Use bulk operations for larger exports. Shopify can limit or refuse operations even when they appear in the indexed schema. See API limits.
Last updated on