# Skio

> Shopify subscription management platform for searching subscriptions and orders, and cancelling subscriptions by Skio ID.

Source: https://cotera.co/docs/reference/tools/individual-tools/skio

---

**Authentication Type:** API Key
**Description:** Shopify subscription management platform for searching active and historical subscriptions, looking up subscription orders, and cancelling subscriptions.

***

## Authentication

To authenticate, you'll need a Skio API token from your Skio dashboard.

**Note:** Skio runs Hasura under the hood and returns GraphQL errors with HTTP 200. A bad or expired token surfaces as a terminal error (e.g. "Invalid response from authorization hook") rather than an HTTP 401 — if you see this, check that you have copied the correct token from the Skio dashboard.

**Rate limit:** 3 requests/second across all plans (Skio API limits: query depth 4, 100 nodes per request, 2000 requests/minute per token).

***

## Subscriptions

Search and manage Shopify subscription contracts tracked by Skio.

### Search Subscriptions

Search for Skio subscriptions by customer name or email, with optional status filtering and result limit. Returns subscriptions ordered newest first.

**Operation Type:** Query (Read)

**Parameters:**

* **name** `string` (nullable): Customer name to search for (case-insensitive; every word must appear in the customer's first or last name)
* **email** `string` (nullable): Customer email address (case-insensitive exact match)
* **status** `string` (nullable): Subscription status filter (e.g. `ACTIVE`, `PAUSED`, `CANCELLED`; omit to return all statuses)
* **limit** `number` (nullable): Maximum number of results to return (default: 10, max: 20)

At least one of `name` or `email` must be provided; omitting both returns a bad-request error.

**Returns:**

* **subscriptions** `array of objects`: Matching subscriptions, newest first
  * **id** `string`: Skio subscription UUID (use this ID with the Cancel Subscription tool)
  * **platformId** `string`: Shopify SubscriptionContract GID
  * **status** `string`: Subscription status (e.g. `ACTIVE`, `PAUSED`, `CANCELLED`)
  * **statusContext** `string` (nullable): Additional status detail (e.g. `CHURNED`, `PERMANENTLY_CANCELLED`)
  * **createdAt** `string`: Subscription creation timestamp
  * **cancelledAt** `string` (nullable): Cancellation timestamp, if cancelled
  * **nextBillingDate** `string` (nullable): Next scheduled billing date
  * **currencyCode** `string`: ISO 4217 currency code for the subscription
  * **customer** `object` (nullable): Customer linked to this subscription
    * **id** `string`: Skio customer ID
    * **platformId** `string`: Shopify Customer GID
    * **email** `string`: Customer email address
    * **firstName** `string` (nullable): Customer first name
    * **lastName** `string` (nullable): Customer last name
    * **phoneNumber** `string` (nullable): Customer phone number
  * **lines** `array of objects`: Current subscription line items (removed lines are excluded)
    * **id** `string`: Line item ID
    * **quantity** `number` (nullable): Quantity for this line
    * **priceWithoutDiscount** `number` (nullable): Unit price before any discount
    * **productTitle** `string`: Product title
    * **variantTitle** `string` (nullable): Variant title (e.g. size or colour)
    * **sku** `string` (nullable): Product SKU

**Example Usage:**

```json
{
  "name": "Jane Smith",
  "status": "ACTIVE",
  "limit": 10
}
```

### Cancel Subscription

Cancel a Skio subscription by its Skio UUID. Also cancels the linked Shopify SubscriptionContract. Prepaid subscriptions will finish their remaining prepaid shipments before ending.

**Operation Type:** Mutation (Write)

**Parameters:**

* **subscriptionId** `string` (required): Skio subscription UUID as returned by the Search Subscriptions tool. Must be a valid UUID — Shopify GIDs and non-UUID values are rejected before Skio is called.
* **shouldSendNotif** `boolean` (nullable): Whether Skio sends the customer a cancellation notification email. Omit to use the store's default notification setting.
* **permanentlyCancel** `boolean` (nullable): Set to `true` to permanently cancel the subscription so it cannot be reactivated. Omit for a normal cancellation that can be reactivated later.

**Returns:**

* **subscriptionId** `string`: ID of the cancelled subscription
* **cancelled** `boolean`: `true` when Skio confirmed the cancellation

**Behavior Notes:**

* Always use the Skio UUID from Search Subscriptions, not the Shopify SubscriptionContract GID.
* Omitting `shouldSendNotif` or `permanentlyCancel` falls back to the store's configured defaults.
* A permanent cancellation (`permanentlyCancel: true`) cannot be undone.
* Prepaid subscriptions fulfil remaining prepaid shipments before the subscription ends.
* Skio returns `ok: false` on failure; the tool surfaces this as a bad-request error.

**Example Usage:**

```json
{
  "subscriptionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "shouldSendNotif": true,
  "permanentlyCancel": false
}
```

***

## Orders

Search for Shopify orders that originated from or were billed by a Skio subscription.

### Search Orders

Search for orders by Shopify order number, customer email, or Skio subscription ID. Returns orders newest first. Deleted orders are excluded.

**Operation Type:** Query (Read)

**Parameters:**

* **orderNumber** `string` (nullable): Shopify order number or name (e.g. `"#1001"` or `"1001"`; matched with or without the `#` prefix)
* **email** `string` (nullable): Customer email address (case-insensitive exact match)
* **subscriptionId** `string` (nullable): Skio subscription UUID; non-UUID values are rejected with a bad-request error
* **limit** `number` (nullable): Maximum number of results to return (default: 5, max: 20)

At least one filter must be provided; omitting all filters returns a bad-request error.

**Returns:**

* **orders** `array of objects`: Matching orders, newest first
  * **id** `string`: Skio order ID
  * **name** `string`: Shopify order name (e.g. `#1001`)
  * **platformId** `string`: Shopify Order GID
  * **createdAt** `string`: Order creation timestamp
  * **cancelledAt** `string` (nullable): Cancellation timestamp, if the order was cancelled
  * **totalPrice** `number` (nullable): Order total in the store's currency
  * **customer** `object` (nullable): Customer who placed the order (same shape as in subscriptions)
    * **id** `string`: Skio customer ID
    * **platformId** `string`: Shopify Customer GID
    * **email** `string`: Customer email address
    * **firstName** `string` (nullable): Customer first name
    * **lastName** `string` (nullable): Customer last name
    * **phoneNumber** `string` (nullable): Customer phone number
  * **subscriptionIds** `array of strings`: Skio subscription IDs associated with this order (includes checkout-origin subscriptions and renewal line subscription IDs; empty for one-off orders)
  * **lineItems** `array of objects`: Order line items
    * **quantity** `number` (nullable): Quantity ordered
    * **priceWithoutDiscount** `number` (nullable): Unit price before discounts
    * **productTitle** `string`: Product title
    * **variantTitle** `string` (nullable): Variant title
    * **sku** `string` (nullable): Product SKU
    * **subscriptionId** `string` (nullable): Skio subscription ID that billed this line, if it is a subscription line

**Behavior Notes:**

* `subscriptionIds` combines checkout-origin subscriptions with renewal line subscription IDs. An order may be linked to more than one subscription — confirm which subscription an order came from before cancelling.
* Use `subscriptionId` to retrieve all orders billed against a specific subscription.

**Example Usage:**

```json
{
  "orderNumber": "#1042",
  "limit": 5
}
```

***

## Common Use Cases

**Subscription Support:**

* Look up a customer's active subscriptions by email before handling a cancellation request
* Search by customer name to find subscriptions when only partial information is available
* Check `statusContext` to distinguish churned or permanently cancelled subscriptions from standard cancellations

**Order Lookup:**

* Find the subscription that billed a specific order number to understand renewal history
* Retrieve all orders for a subscription ID to audit billing activity
* Look up a customer's recent orders by email to resolve delivery or billing queries

**Subscription Management:**

* Cancel a subscription by Skio UUID after confirming it with Search Subscriptions
* Use `permanentlyCancel: true` for fraud or policy cases where reactivation must be prevented
* Set `shouldSendNotif: false` to suppress the cancellation email when handling a cancellation internally