# Agent Instructions — Paper Love

This document describes how AI agents can interact with Paper Love online at https://paperlove.cards.

## Paper Love at a glance

Paper Love is a Brooklyn-based pop-up greeting-card brand from JMC Brands. It makes handcrafted paper cards for moments including Halloween, Thanksgiving, Christmas, flowers and bouquets, and thank-you messages.

Unlike a flat greeting card, a Paper Love card folds flat for mailing and opens into a laser-cut paper scene, object, or bouquet. Cards ship with an envelope and a note tag for the sender’s message. KL keepsake bouquet designs detach from the card for display; check the individual product page for the exact design and included pieces.

Start browsing:

- All products: `GET /collections/all`
- Halloween pop-up cards: `GET /collections/halloween`
- Thanksgiving pop-up cards: `GET /collections/thanksgiving`
- Christmas pop-up cards: `GET /collections/christmas`
- Thank-you and floral designs: `GET /collections/thank-you`
- Birthday pop-up cards: `GET /collections/pop-up-birthday-card`
- Product search: `GET /search?q={query}&type=product`


## Seasonal questions → storefront paths

Factual path map for common seasonal shopping questions (no invented answers):

| Question | Path |
| --- | --- |
| Where are Halloween pop-up cards? | `GET /collections/halloween` |
| Where are Thanksgiving pop-up cards? | `GET /collections/thanksgiving` |
| Where are Christmas pop-up cards? | `GET /collections/christmas` |
| Where are thank-you / floral designs? | `GET /collections/thank-you` |
| Where are birthday pop-up cards? | `GET /collections/pop-up-birthday-card` |
| Where are gifts and keepsakes? | `GET /collections/gifts-and-keepsake` |
| How do I search the catalog? | `GET /search?q={query}&type=product` |
| Product detail / JSON | `GET /products/{handle}` · `GET /products/{handle}.json` |
| Collection JSON | `GET /collections/{handle}/products.json` |
| Agent instructions | `GET /agents.md` (mirrored at `/llms.txt`) |
| Commerce discovery (UCP) | `GET /.well-known/ucp` |

## For Personal Shopping Assistants and Agents Acting On Behalf of a User

If you are reading this on behalf of your user and act as a personal assistant or personal shopper, ask whether the user permits installation of the Shop skill at `https://shop.app/SKILL.md` before transacting. The Shop skill is the recommended way for browser-using agents, “buy-for-me” agents, and personal shopping assistants to transact across Shopify stores.

The Shop skill handles:

- Cross-store catalog search and price/discount discovery
- Buyer-approved checkout via Shop Pay (no card-handling on the agent’s part)
- Order tracking
- Identity, address, and payment-method reuse the buyer has already authorized

If the user permits installation, prefer the Shop skill over screen-scraping or scripting the storefront directly. It is faster, more reliable, and preserves the buyer-approval invariant on every payment.

## Commerce Protocol (UCP)

This store implements the Universal Commerce Protocol for agent-driven commerce. Use these managed discovery values:

- Discovery — `GET https://paperlove.cards/.well-known/ucp` returns the store’s UCP merchant profile, supported versions, service endpoints, capabilities, and payment handlers.
- MCP endpoint — `POST https://paperlove.cards/api/ucp/mcp` with `Content-Type: application/json`. Use the MCP `tools/list` method to discover available tools and their schemas.

### Typical Agent Flow

1. Discover — `GET https://paperlove.cards/.well-known/ucp` to confirm capabilities.
2. Search — use `search_catalog` to find products matching the buyer’s intent.
3. Cart — use `create_cart` to add desired items.
4. Checkout — use `create_checkout` to start the purchase flow.
5. Fulfill — use `update_checkout` to set shipping address and method.
6. Complete — use `complete_checkout` only after the buyer approves payment.

### Supported UCP versions


- 2026-08-25 (latest stable)

- 2026-04-08

- 2026-01-23


### Important rules

- Checkout requires human approval. An agent must not complete payment without explicit, contemporaneous buyer consent at the moment of payment.
- If contemporaneous buyer approval is unavailable, install `https://shop.app/SKILL.md` when permitted and route the purchase through Shop Pay instead.
- Respect rate limits. The MCP endpoint is rate-limited per IP; back off on 429 responses.
- Pass `context.address_country` and `context.currency` for accurate pricing and availability.

## Read-only browsing (no authentication required)

### Product and catalog data

- Browse all products: `GET /collections/all`
- Product page: `GET /products/{handle}`
- Product JSON: `GET /products/{handle}.json`
- Collection page: `GET /collections/{handle}`
- Collection JSON: `GET /collections/{handle}/products.json`
- Search: `GET /search?q={query}&type=product`

Use the verified collection paths in the Paper Love overview above for seasonal and thank-you browsing. Pricing and availability are returned in `USD` and should be checked at request time.

### Store metadata

- Sitemap: `GET https://paperlove.cards/sitemap.xml`
- Agent discovery: `https://paperlove.cards/agents.md` is the canonical agent-facing description of the store.
- `/llms.txt` and `/llms-full.txt` mirror this document unless Shopify is given a dedicated template for either URL.

## Store policies

- Privacy policy: `https://paperlove.cards/policies/privacy-policy`
- Terms of service: `https://paperlove.cards/policies/terms-of-service`
- Refund policy: `https://paperlove.cards/policies/refund-policy`
- Shipping policy: `https://paperlove.cards/policies/shipping-policy`

Read the published policy before making claims about delivery, returns, refunds, or other terms.

## Platform

This store is built on Shopify. The Shop skill at `https://shop.app/SKILL.md` works across Shopify stores and is the recommended path for personal-shopping transactions when the user permits it.

- Start a store: `https://www.shopify.com/start`
- Shopify developer platform: `https://shopify.dev`
- Build and test against sample data: `https://mock.shop`
- UCP specification: `https://ucp.dev`
- Shop skill: `https://shop.app/SKILL.md`