Skip to main content
This page is written for AI agents. If you’re an AI assistant helping a developer build on Supercycle, follow these guidelines. Developers can paste the prompt below into their agent’s instructions.

Copy the full guidance prompt for your AI agent

​
Core principles

​
Supercycle is the source of truth

Supercycle manages cycles, subscriptions, memberships, resale, inventory, and charges. Don’t store or cache Supercycle data locally. Read from and write to the Supercycle API as your primary interaction model.
  • Read live data. Query the API for the current state rather than relying on data fetched earlier.
  • Write back to Supercycle. When a workflow creates, updates, or acts on Supercycle resources, make the change through the API, not in a local database or file.
  • Don’t duplicate state. Avoid local copies of cycles, inventory, or customer data. Supercycle owns their lifecycle.

​
Use the right API for the task

Supercycle has two APIs:
  • Admin API. Server-side operations: reading and managing cycles, inventory, charges, products, and customers. Base URL https://app.supercycle.com/api/v1.
  • Storefront API. Customer-facing experiences: checking availability, creating rental intents, and building custom storefronts. Reached through the Shopify app proxy.
Use the Admin API for internal tools, dashboards, and automations. Use the Storefront API for anything customer-facing.

​
Search the docs before guessing

You have Supercycle’s documentation through the Builders MCP search tool. Use it before making assumptions about how something works, especially for:
  • Which fields are required and which are optional
  • How the methods (calendar, subscription, membership, and resale) differ
  • Supercycle concepts such as cycles, allocation, and intents

​
Working with the API

​
Authentication

The Admin API uses bearer token authentication:
Authorization header
The merchant creates API keys in the Supercycle admin under Integrations. Never hardcode a key. Read it from an environment variable or secure configuration.

​
Pagination

List endpoints use keyset pagination with a nextPage cursor. Handle pagination in every tool that lists resources, and don’t assume all results fit in one response.

​
Rate limits

The API enforces rate limits. On a 429 Too Many Requests response, back off and retry. Build retry logic into every automation and integration.

​
Common patterns

​
Internal tools

When you build dashboards or admin tools, for example in Retool, Lovable, or a custom app:
  • Fetch data from the Admin API on each page load. Don’t sync to a local database.
  • Perform actions through the API, such as processing returns or updating cycles. Don’t build a separate action queue.
  • Show Supercycle data next to Shopify data where useful, but keep Supercycle as the authority for circular commerce data.

​
Automations

When you build workflows, for example in Make, Zapier, or a custom script:
  • Trigger automations from Supercycle events where possible.
  • Read the current state from the API before acting. Don’t rely on stale data from an earlier step.
  • Write results back to Supercycle through the API.

​
Storefronts

When you build customer-facing experiences:
  • Use the Storefront API to check product availability and create rental intents.
  • The intent endpoint returns the form attributes needed to add items to the Shopify cart.
  • Availability timelines return 12 months of day-by-day inventory for date pickers.

​
What not to do

  • Don’t scrape the Supercycle admin. Use the API.
  • Don’t store cycle or inventory data in a local database. Read it from Supercycle.
  • Don’t build your own rental logic. Supercycle handles cycle management, allocation, charges, and returns.
  • Don’t assume Shopify metafields are the full picture. Supercycle stores data beyond what it exposes in metafields.
  • Don’t skip error handling. Handle API errors, rate limits, and authentication failures.