> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supercycle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Guidance for AI

> Instructions for AI agents working with the Supercycle Builders MCP

This page is written for AI agents. If you're an AI assistant helping a developer build on Supercycle, follow these guidelines.

<Prompt description="Copy the full guidance prompt for your AI agent">
  You are helping a developer build on the Supercycle platform. Follow these rules:

  1. Supercycle is the source of truth. Do not store or cache Supercycle data locally. Always read from and write to the Supercycle API.
  2. Use the Admin API ([https://app.supercycle.com/api/v1](https://app.supercycle.com/api/v1)) for server-side operations: cycles, inventory, charges, products, customers. Use the Storefront API (via Shopify app proxy) for customer-facing experiences: availability, intents, storefronts.
  3. Search the Supercycle documentation via the MCP before making assumptions about how something works.
  4. The Admin API uses Bearer token authentication. Never hardcode API keys - use environment variables.
  5. List endpoints use keyset pagination with a nextPage cursor. Always handle pagination.
  6. Handle rate limits (429 responses) with backoff and retry logic.
  7. When building internal tools, fetch data from the API on each load - do not sync to a local database.
  8. When building automations, read current state from the API before acting - do not rely on stale data.
  9. When building storefronts, use the Storefront API for availability checks and rental intents.
  10. Do not scrape the Supercycle admin UI. Do not build your own rental logic. Do not assume Shopify metafields are the full picture - Supercycle stores its own data beyond metafields.
</Prompt>

## 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](/api-reference/admin/introduction)** — For server-side operations: reading and managing cycles, inventory, charges, products, and customers. Base URL: `https://app.supercycle.com/api/v1`
* **[Storefront API](/api-reference/storefront/introduction)** — For customer-facing experiences: checking availability, creating rental intents, and building custom storefronts. Accessed via 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 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:

```
Authorization: Bearer [api_token]
```

API keys are generated by the merchant in their Supercycle admin settings. Never hardcode API keys — always use environment variables or secure configuration.

### Pagination

List endpoints use keyset pagination with a `nextPage` 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 a `429 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