Appstle Shopify

Appstle Subscription Management

You have access to the appstle_api MCP tool for authenticated Appstle Subscription API requests. This skill teaches you the endpoints, workflows, and safety rules.

Quick Reference

• Base path: All endpoints start with /api/external/v2/
• Auth: Handled automatically by the MCP tool (X-API-Key header + api_key query param)
• Pagination: Spring Pageable — page (0-based), size (default 20, max 50), sort (e.g. created_at,desc)
• Customer IDs: Always numeric — strip gid://shopify/Customer/ prefix if present
• Contract IDs: Always numeric int64
• Dates: ISO 8601 with timezone: 2024-03-15T00:00:00Z
• Status values: Send lowercase to API (active, paused, cancelled) even though they display as uppercase
• Bulk operations: See Workflow 11 for pagination-then-act pattern, rate limiting, and error handling

Troubleshooting Setup

If the appstle_api tool is not available, check:

1. Run /mcp — is appstle-shopify listed? If not, restart Claude Code.
2. Is APPSTLE_API_KEY set? Check your project .env or run echo $APPSTLE_API_KEY in your shell.
3. The plugin loads .env automatically from your project directory.

Tool Invocation

Call the appstle_api MCP tool with these parameters:

// GET with query params
appstle_api({ method: "GET", path: "/api/external/v2/subscription-contract-details", params: { customerName: "user@example.com", size: 5 } })

// PUT with query params (most PUT endpoints)
appstle_api({ method: "PUT", path: "/api/external/v2/subscription-contracts-update-status", params: { contractId: 123456, status: "PAUSED" } })

// PUT with body (exceptions: add-line-items, remove-line-items, update-shipping-address)
appstle_api({ method: "PUT", path: "/api/external/v2/subscription-contracts-update-shipping-address", params: { contractId: 123456 }, body: { firstName: "Max", lastName: "Mustermann", address1: "Bahnhofstrasse 1", city: "Zürich", country: "CH", zip: "8001" } })

// POST with body (variant swap)
appstle_api({ method: "POST", path: "/api/external/v2/subscription-contract-details/replace-variants-v3", body: { contractId: 123456, lineId: "gid://shopify/SubscriptionLine/789", newVariantId: "44681299468571" } })

Critical API Quirks

1. Response formats vary: Some endpoints return arrays directly, others return { content: [], totalElements, ... }. Always check with Array.isArray() logic when processing responses.

2. PUT endpoints use query params, NOT body: Almost all PUT endpoints pass data as query parameters. Exceptions that use request body:

   • add-line-items (body for items array)
   • remove-line-items (body for lineIds array)
   • update-shipping-address (body for address fields)

3. Customer endpoint gaps: GET /subscription-customers/{id} does NOT return email, firstName, or lastName at the top level. Enrich from the nested contract's customer field via contract-external.

4. Activity log field naming: Uses createAt (not createdAt) and JHipster filter syntax: entityId.equals=value, createAt.greaterThanOrEqual=value.

5. Portal link response field: The field is manageSubscriptionLink (not portalLink or link).

6. Contract search by email: Use customerName query param (not email) on /subscription-contract-details.

7. WARNING — customerId filter overrides all others: When customerId is provided to the contract-details endpoint, all other filters (email, status, dates, product) are SILENTLY IGNORED. Always use separate calls if you need both customer lookup and filtered results.

8. fromNextDate/toNextDate must be paired: Providing only one may return unexpected results.

9. Rate limiting: ~2 req/sec max. Bursting triggers 429s with long cooldown (minutes). For bulk operations use sequential requests with ≥1s delay. Exponential backoff on 429s (start 3s, double each retry).

10. Cancel is DELETE for feedback: Cancel with feedback uses DELETE /subscription-contracts/{contractId}. Simple cancel via PUT .../update-status?status=CANCELLED also works but cannot attach a reason.

11. Sort field names are snake_case: created_at,desc, billingDate,desc, createAt,desc (activity logs).

12. Auto-dump for large responses: Responses >4KB are automatically saved to /tmp/appstle_*.json and a compact summary is returned instead. The summary includes field names, a sample record, and ready-to-use query.js commands for SQL filtering. Use size up to 50 for efficient bulk fetches — the dump keeps Claude's context lean while preserving all data in the temp file.

Working with Large Responses

Responses larger than 4KB are automatically dumped to /tmp/appstle_*.json files. Instead of the full JSON, you receive a compact summary with:

• Item count, pagination info, and file path
• Field names and a sample record
• Ready-to-use query.js commands

Querying dump files with SQL

Use the bundled query.js script via Bash to filter, aggregate, or search dump files:

# Basic filtering
node <path-from-summary>/query.js "<file>" "SELECT id, customerEmail, status FROM ? WHERE status = 'ACTIVE'"

# Aggregation
node <path-from-summary>/query.js "<file>" "SELECT status, COUNT(*) as n FROM ? GROUP BY status"

# Search by email pattern
node <path-from-summary>/query.js "<file>" "SELECT * FROM ? WHERE customerEmail LIKE '%@example.com'"

# Date filtering (string comparison works for ISO dates)
node <path-from-summary>/query.js "<file>" "SELECT * FROM ? WHERE nextBillingDate > '2026-03-01'"

# Top N by value
node <path-from-summary>/query.js "<file>" "SELECT * FROM ? ORDER BY orderAmount DESC" --limit 10

# Compact output (single line)
node <path-from-summary>/query.js "<file>" "SELECT COUNT(*) as cnt FROM ?" --compact

The exact node command path is included in every dump summary — copy-paste it directly.

Row limit: Results are capped at 100 rows by default. Use --limit N to change, or --limit 0 for unlimited output.

Reserved words: alasql treats common words as keywords. Do NOT use these as column aliases: total, count, name, order, key, value, number, status, type, table, select

Use short aliases instead: as n, as cnt, as s, as v, as t

Common SQL patterns by endpoint

Cleanup

Dump files older than 2 hours are automatically deleted when the MCP server starts. To clean up manually:

rm /tmp/appstle_*.json

Safety Rules

Destructive Operations — ALWAYS confirm with user first:

Before any modification:

1. Always fetch the subscription first to confirm current state
2. Confirm the action and its consequences with the user
3. After modification, fetch again to verify the change took effect

Endpoint Quick Map

For full endpoint details with all parameters, read references/endpoints.md. For example JSON response structures, read references/response-shapes.md. For step-by-step workflow playbooks, read examples/workflows.md.

Customer Lookup

Subscriptions

Billing & Orders

Line Items & Products

Pricing & Discounts

Shipping

Payment Methods

Notes

Activity Logs & Analytics

Selling Plans & Groups

Variant Swaps