{
  "openapi": "3.1.0",
  "info": {
    "title": "Maggie's Organics Storefront API",
    "version": "1.0.0",
    "summary": "Public APIs on maggiesorganics.com for shopping agents and integrations.",
    "description": "Maggie's Organics (maggiesorganics.com) is an employee-owned organic cotton and fair trade clothing company. This document describes the public, unauthenticated endpoints available on this host: the BigCommerce Storefront Cart API (session-scoped, cookie-based) and the Universal Checkout Protocol (UCP) checkout-session endpoints for AI shopping agents. Product discovery is best done via the XML sitemap and product pages, which carry schema.org Product JSON-LD. Error responses on every API path are JSON (see ErrorResponse).",
    "contact": {
      "name": "Maggie's Organics",
      "email": "maggies@organicclothes.com",
      "url": "https://maggiesorganics.com/developers"
    },
    "license": {
      "name": "Maggie's Organics API usage terms",
      "url": "https://maggiesorganics.com/developers"
    },
    "x-llms-txt": "https://maggiesorganics.com/llms.txt",
    "x-developer-portal": "https://maggiesorganics.com/developers"
  },
  "externalDocs": {
    "description": "Maggie's Organics developer resources",
    "url": "https://maggiesorganics.com/developers"
  },
  "servers": [
    {
      "url": "https://maggiesorganics.com"
    }
  ],
  "security": [
    {}
  ],
  "tags": [
    {
      "name": "Discovery",
      "description": "Machine-readable site resources"
    },
    {
      "name": "Storefront Cart",
      "description": "BigCommerce Storefront Cart API. Cookie-scoped guest carts; no API key required.",
      "externalDocs": {
        "url": "https://developer.bigcommerce.com/docs/rest-storefront/carts"
      }
    },
    {
      "name": "UCP Checkout",
      "description": "Universal Checkout Protocol (spec 2026-01-23) checkout sessions for AI agents.",
      "externalDocs": {
        "url": "https://ucp.dev/specification/checkout/"
      }
    }
  ],
  "paths": {
    "/llms.txt": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getLlmsTxt",
        "summary": "Site overview for LLM agents (llms.txt)",
        "responses": {
          "200": {
            "description": "Markdown overview",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "4XX": {
            "description": "Client error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/ucp": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getUcpManifest",
        "summary": "UCP profile manifest",
        "responses": {
          "200": {
            "description": "UCP manifest",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "4XX": {
            "description": "Client error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/xmlsitemap.php": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "operationId": "getSitemap",
        "summary": "XML sitemap index (products, categories, pages, blog)",
        "responses": {
          "200": {
            "description": "Sitemap index",
            "content": {
              "text/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "4XX": {
            "description": "Client error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/storefront/carts": {
      "get": {
        "tags": [
          "Storefront Cart"
        ],
        "security": [
          {},
          {
            "storefrontSession": []
          }
        ],
        "operationId": "getCarts",
        "summary": "Get the current session's cart(s)",
        "parameters": [
          {
            "name": "include",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated sub-resources, e.g. lineItems.physicalItems.options"
          }
        ],
        "responses": {
          "200": {
            "description": "Array of carts (empty array when no cart exists)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Cart"
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "Client error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Storefront Cart"
        ],
        "security": [
          {},
          {
            "storefrontSession": []
          }
        ],
        "operationId": "createCart",
        "summary": "Create a cart",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CartInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created cart",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Cart"
                }
              }
            }
          },
          "400": {
            "description": "Invalid line items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/storefront/carts/{cartId}/items": {
      "post": {
        "tags": [
          "Storefront Cart"
        ],
        "security": [
          {},
          {
            "storefrontSession": []
          }
        ],
        "operationId": "addCartItems",
        "summary": "Add line items to a cart",
        "parameters": [
          {
            "$ref": "#/components/parameters/CartId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CartInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated cart",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Cart"
                }
              }
            }
          },
          "404": {
            "description": "Cart not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/storefront/carts/{cartId}/items/{itemId}": {
      "delete": {
        "tags": [
          "Storefront Cart"
        ],
        "security": [
          {},
          {
            "storefrontSession": []
          }
        ],
        "operationId": "deleteCartItem",
        "summary": "Remove a line item from a cart",
        "parameters": [
          {
            "$ref": "#/components/parameters/CartId"
          },
          {
            "name": "itemId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Updated cart",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Cart"
                }
              }
            }
          },
          "404": {
            "description": "Cart or item not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/storefront/checkouts/{checkoutId}": {
      "get": {
        "tags": [
          "Storefront Cart"
        ],
        "security": [
          {},
          {
            "storefrontSession": []
          }
        ],
        "operationId": "getCheckout",
        "summary": "Get checkout for a cart (checkoutId equals cartId)",
        "parameters": [
          {
            "name": "checkoutId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Checkout",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Checkout does not belong to this session",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/checkout-sessions": {
      "post": {
        "tags": [
          "UCP Checkout"
        ],
        "operationId": "createCheckoutSession",
        "summary": "Create a UCP checkout session",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          },
          {
            "$ref": "#/components/parameters/UcpAgent"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UcpSessionCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Session created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpSession"
                }
              }
            }
          },
          "400": {
            "description": "Missing headers or line_items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Idempotency-Key reused with a different body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/checkout-sessions/{sessionId}": {
      "get": {
        "tags": [
          "UCP Checkout"
        ],
        "operationId": "getCheckoutSession",
        "summary": "Get a UCP checkout session",
        "parameters": [
          {
            "$ref": "#/components/parameters/SessionId"
          }
        ],
        "responses": {
          "200": {
            "description": "Session",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpSession"
                }
              }
            }
          },
          "404": {
            "description": "Session not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "UCP Checkout"
        ],
        "operationId": "updateCheckoutSession",
        "summary": "Update a UCP checkout session (buyer, fulfillment, line items)",
        "parameters": [
          {
            "$ref": "#/components/parameters/SessionId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated session",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpSession"
                }
              }
            }
          },
          "404": {
            "description": "Session not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/checkout-sessions/{sessionId}/complete": {
      "post": {
        "tags": [
          "UCP Checkout"
        ],
        "operationId": "completeCheckoutSession",
        "summary": "Complete a session (escalates to hosted BigCommerce checkout when payment cannot be taken in-protocol)",
        "parameters": [
          {
            "$ref": "#/components/parameters/SessionId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Completed or escalated session",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpSession"
                }
              }
            }
          },
          "404": {
            "description": "Session not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/checkout-sessions/{sessionId}/cancel": {
      "post": {
        "tags": [
          "UCP Checkout"
        ],
        "operationId": "cancelCheckoutSession",
        "summary": "Cancel a session",
        "parameters": [
          {
            "$ref": "#/components/parameters/SessionId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Cancelled session",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpSession"
                }
              }
            }
          },
          "404": {
            "description": "Session not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "storefrontSession": {
        "type": "apiKey",
        "in": "cookie",
        "name": "SHOP_SESSION_TOKEN",
        "description": "Shopper session cookie issued by the storefront. Optional: omit it and a new guest session is created."
      }
    },
    "parameters": {
      "CartId": {
        "name": "cartId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "SessionId": {
        "name": "sessionId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Unique key per logical request; replays return the cached response."
      },
      "RequestId": {
        "name": "Request-Id",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Echoed back on the response."
      },
      "UcpAgent": {
        "name": "UCP-Agent",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Agent identifier and capabilities."
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "description": "Structured error returned by every API path on this host.",
        "required": [
          "error",
          "messages"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "Alias of error.message (BigCommerce Storefront API compatible)."
          },
          "detail": {
            "type": "string",
            "description": "Alias of error.hint (BigCommerce Storefront API compatible)."
          },
          "status": {
            "type": "integer"
          },
          "error": {
            "type": "object",
            "required": [
              "status",
              "code",
              "message"
            ],
            "properties": {
              "status": {
                "type": "integer",
                "examples": [
                  404
                ]
              },
              "code": {
                "type": "string",
                "examples": [
                  "NOT_FOUND"
                ]
              },
              "message": {
                "type": "string"
              },
              "hint": {
                "type": "string",
                "description": "What to try next."
              },
              "path": {
                "type": "string"
              },
              "resources": {
                "type": "object",
                "additionalProperties": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "messages": {
            "type": "array",
            "description": "UCP-style message list (type/code/content/severity).",
            "items": {
              "type": "object",
              "required": [
                "type",
                "code",
                "content"
              ],
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "error",
                    "warning",
                    "info"
                  ]
                },
                "code": {
                  "type": "string"
                },
                "content": {
                  "type": "string"
                },
                "severity": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "CartLineItem": {
        "type": "object",
        "required": [
          "productId",
          "quantity"
        ],
        "properties": {
          "productId": {
            "type": "integer"
          },
          "variantId": {
            "type": "integer"
          },
          "quantity": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "CartInput": {
        "type": "object",
        "required": [
          "lineItems"
        ],
        "properties": {
          "lineItems": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CartLineItem"
            }
          }
        }
      },
      "Cart": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "currency": {
            "type": "object"
          },
          "cartAmount": {
            "type": "number"
          },
          "baseAmount": {
            "type": "number"
          },
          "lineItems": {
            "type": "object",
            "properties": {
              "physicalItems": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              }
            }
          },
          "createdTime": {
            "type": "string",
            "format": "date-time"
          },
          "updatedTime": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "UcpSessionCreate": {
        "type": "object",
        "required": [
          "line_items"
        ],
        "properties": {
          "line_items": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": [
                "item",
                "quantity"
              ],
              "properties": {
                "item": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    }
                  }
                },
                "quantity": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "buyer": {
            "type": "object"
          },
          "fulfillment": {
            "type": "object"
          }
        }
      },
      "UcpSession": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "incomplete",
              "requires_escalation",
              "ready_for_complete",
              "completed",
              "canceled"
            ]
          },
          "line_items": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "totals": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "continue_url": {
            "type": "string",
            "format": "uri",
            "description": "Hosted checkout URL when escalation is required"
          },
          "messages": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      }
    }
  }
}