Copy the full guidance prompt for your AI agent
Core principles
Supercycle is the source of truth
Supercycle manages rental cycles, subscriptions, memberships, resale, inventory, and charges. Do not store or cache Supercycle data locally. Always read from and write to the Supercycle API as your primary interaction model.- Read live data — Query the API for current state rather than relying on previously fetched data
- Write back to Supercycle — When a workflow creates, updates, or acts on Supercycle resources, use the API to make those changes, not a local database or file
- Don’t duplicate state — Avoid building local copies of cycles, inventory, or customer data. Supercycle handles the lifecycle of these resources
Use the right API for the task
Supercycle has two APIs:- Admin API — For server-side operations: reading and managing cycles, inventory, charges, products, and customers. Base URL:
https://app.supercycle.com/api/v1 - Storefront API — For customer-facing experiences: checking availability, creating rental intents, and building custom storefronts. Accessed via Shopify app proxy
Search the docs before guessing
You have access to Supercycle’s documentation through the MCP search tool. Use it. Before making assumptions about how something works, search the docs. This is especially important for:- Understanding which fields are required vs optional
- Learning how rental methods (calendar, subscription, membership, resale) differ
- Understanding Supercycle-specific concepts like cycles, allocation, and intents
Working with the API
Authentication
The Admin API uses Bearer token authentication:Pagination
List endpoints use keyset pagination with anextPage cursor. Always handle pagination when building tools that list resources — don’t assume all results fit in a single response.
Rate limits
The API enforces rate limits. If you receive a429 Too Many Requests response, back off and retry. Build retry logic into any automation or integration.
Common patterns
Building internal tools
When building dashboards or admin tools (e.g. in Retool, Lovable, or custom apps):- Fetch data from the Admin API on each page load — don’t sync to a local database
- Use the API to perform actions (process returns, update cycles) — don’t build a separate action queue
- Display Supercycle data alongside Shopify data where useful, but let Supercycle remain the authority for circular commerce data
Building automations
When building workflows (e.g. in Make, Zapier, or custom scripts):- Trigger automations from Supercycle events where possible
- Read current state from the API before taking action — don’t rely on stale data from a previous step
- Write results back to Supercycle via the API
Building storefronts
When building custom customer-facing experiences:- Use the Storefront API to check product availability and create rental intents
- The intent endpoint returns form attributes needed to add items to the Shopify cart
- Availability timelines return 12 months of day-by-day inventory data for date pickers
What not to do
- Don’t scrape the Supercycle admin UI — Use the API
- Don’t store cycle or inventory data in a local database — Read 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 its own data beyond what’s exposed in Shopify metafields
- Don’t skip error handling — Always handle API errors, rate limits, and authentication failures gracefully