cotera
Logo

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:

{
  "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:

{
  "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:

{
  "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