Building on Skio: Integration guide for Technical Partners

This guide helps technical partners decide how to integrate with Skio, what to build for their product category, and how to prepare for launch. Many compatible apps already work with Skio through their Shopify integration. Products that need subscription data, lifecycle events, or management actions connect through Skio's APIs and webhooks.

Before you start

• Developer access: Building an integration requires engineering resources familiar with GraphQL, webhooks, and Shopify's APIs.

• A test store: You'll need a Shopify development store with Skio installed. See the test account section below.

• A merchant API key: Skio uses store-specific API keys, so each merchant generates a key for your integration.

How do Skio integrations work?

Shopify creates the subscription contract at checkout and generates renewal orders when billing succeeds. Skio manages everything around that: scheduling, the subscriber experience, retention workflows, and operational tooling.

That gives you two integration surfaces:

• Shopify: Orders, customers, fulfillment, and other commerce data your app already handles. Apps that consume Shopify orders can often process Skio renewals with no extra work.

• Skio: Subscription data, lifecycle events, and management actions, such as reading subscription state or changing a future renewal.

Which integration path should I use?

Pick the path that matches what your product needs to do. You can combine paths. For example, a helpdesk might use GraphQL for agent actions and webhooks for ticket creation.

An existing Recharge integration doesn't carry over. You'll need a separate Skio implementation that maps your authentication, objects, queries, and mutations to Skio's schema. Skio's data model mirrors Shopify subscription objects and exposes Shopify identifiers for supported records.

How do I authenticate with the Skio API?

Skio uses store-specific API keys sent in the request header. You don't need to build an OAuth flow.

Step 1: Generate an API key

1. In the left-hand menu of the Skio Dashboard, go to API & Integrations > API Keys.

2. Enter a name for the key, then click Generate API key.

3. Copy the key and store it securely.

The key is only shown once. If it's lost, delete it and generate a new one.

Step 2: Send the key with your requests

Include the key in the authorization header with the API prefix:

authorization: API <key>

Send requests to https://graphql.skio.com/v1/graphql.

Store credentials per merchant store, encrypt them at rest, keep them server-side, and support key rotation.

What are the GraphQL API limits?

The GraphQL API supports filtering, ordering, and nested selection for targeted subscription reads and management actions. The platformId field maps Skio records to their Shopify global IDs.

Select only the fields you need, paginate results, and handle throttling with bounded retries and backoff.

How do I set up a test account?

Install Skio on a Shopify development store, then send the shop URL to the Skio team to convert it into a test account.

Create test subscriptions through a supported subscription checkout or creation flow. Then test the full lifecycle: renewal, cancellation, and every management action your product supports.

Creating an order through the Shopify Admin API or a bulk import doesn't create a subscription contract.

Which webhook interface should I use?

Use the Custom Webhook Integration for marketing automation and profile sync. Use native webhooks for basic subscription change notifications. The two interfaces have different schemas and event catalogs, so they aren't interchangeable.

The Custom Webhook Integration retries failed deliveries with exponential backoff, limits concurrent deliveries, and supports per-event test sends.

Acknowledge requests quickly, persist accepted work, and process downstream updates asynchronously. Add duplicate detection before triggering side effects. If you can't find a delivery identifier in live requests, work out a deduplication strategy with the Skio team.

What should I build for my product category?

Each partner category has a recommended integration path and a set of things to validate. Find your category below.

Email, SMS, and marketing automation

Use the Custom Webhook Integration to map Skio events to triggers in your platform. It follows the same event model as Skio's Klaviyo integration. Turn on profile sync if your segmentation or personalization needs customer-level subscription properties.

Map event properties and customer fields explicitly, preserve data types, and handle missing values. Query GraphQL when a workflow needs data that isn't in the payload.

Your merchant setup instructions should cover how to:

1. Request activation of the Custom Webhook Integration.

2. Configure your endpoint.

3. Turn on profile sync, if required.

4. Select events and send test payloads.

5. Run a profile backfill.

Size your ingestion to handle a backfill of all existing customers, and define how email changes reconcile with existing profiles.

Helpdesk and CX platforms

Build a subscription view in the agent workspace, backed by the GraphQL API. Show the customer's subscriptions, available actions, and a link to the subscription in Skio.

When a ticket opens, pull the subscription status, next billing date, frequency, products, quantities, and recent billing history. Use on-demand reads to keep the view current, and refresh state before executing any change. Look up customers by email first, then store their Skio and Shopify identifiers.

For your first release, scope agent actions to supported operations like:

• Skip: Skip the next order.

• Reschedule: Change the next billing date or frequency.

• Swap: Swap a product.

• Status changes: Pause, resume, or cancel a subscription, capturing cancellation reasons where supported.

Show the confirmed result after each action, and log the agent, change, and outcome in the ticket history. If one helpdesk account serves multiple stores, verify store routing before running any mutation.

Loyalty and referral platforms

Your existing Shopify integration likely covers points on renewal orders, referral attribution, and tier progression. A direct Skio integration adds subscription-specific rewards.

Validate eligibility rules against duplicate deliveries, cancellations, and refunds. Customer-facing actions must confirm the authenticated customer owns the subscription being changed. Store stable identifiers alongside email so account changes don't create duplicate members.

Data analytics and attribution

Use BigQuery for recurring warehouse ingestion and historical analysis. Reserve GraphQL for targeted lookups, not as your main ingestion pipeline.

1. The merchant turns on BigQuery in API & Integrations > Integrations and grants your user, group, or service account read access.

2. Inspect the available tables and schema before defining your data model.

3. Join Skio records to Shopify data using platformId.

4. Check update timestamps and deletion behavior before building incremental processing.

5. Reconcile source totals and account for late-arriving changes.

Publish your definitions of active subscribers, churn, LTV, and cohort retention so merchants understand why your numbers may differ from the Skio Dashboard. Validate against a real pilot merchant's data, since a new test store won't reflect a mature subscription program.

Storefront, mobile, and post-purchase

Use Shopify selling plans and storefront APIs for subscription selection and checkout. For mobile apps, custom carts, and product page experiments, confirm that:

• Selling plans persist: The selected plan carries through the cart.

• Subscriptions are created: Checkout completes and creates the subscription.

• Customers can manage it: The subscriber can access and manage the subscription afterward.

Adding a product to the current Shopify order doesn't update the subscription. Offers that change future products, quantities, or frequency need the matching subscription operation.

Payments, fraud, and order services

Order-based services often work through the existing Shopify integration. Test initial purchases and renewals separately.

Order access doesn't mean you can retry failed billing. Scope failed-payment recovery with the Skio team before building it. For notifications, the Custom Webhook Integration sends a billingAttemptFailed event with failure details.

Production best practices

Apply these controls across your integration before you go live.

Launch checklist

Complete the checks that apply to your integration, then share your pilot results and setup guide with the Skio team. They'll coordinate your listing, launch, and Merchant Success enablement.

• Lifecycle testing: Validate initial purchase, renewal, cancellation, and every subscription action your product exposes on a test store.

• Webhook resilience: Test authentication failures, duplicate deliveries, downstream outages, and profile backfills.

• Shopify sync: Confirm API changes in Skio produce the expected Shopify order, and that your app detects subscription orders correctly.

• Merchant docs: Publish setup instructions, supported features, known limitations, and a support contact.

• Pilot: Run a pilot with a merchant whose workflows match your intended use case.

FAQ

Related articles

• Using the Skio API

• Webhooks

• Custom webhook integration for Email/SMS Platforms

• All Skio Event Metrics

• Skio event and profile properties for integrations

• BigQuery Integration

• Understanding custom extensions

• Static Box API guide for developers

• Dynamic Box API guide for developers

• Compatible apps and integrations