> ## 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 building on Supercycle through the Builders MCP and the APIs

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.

<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 with the Builders MCP before making assumptions about how something works.
  4. The Admin API uses Bearer token authentication. Never hardcode API keys. Read them from 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, because Supercycle stores its own data beyond metafields.
</Prompt>

***

## 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](/api-reference/admin/introduction).** 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).** 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:

```text Authorization header theme={null}
Authorization: Bearer [api_token]
```

The merchant creates API keys in the Supercycle admin under <Icon icon="shopify" iconType="solid" /> **[Integrations](https://admin.shopify.com/apps/supercycle/settings/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.