openapi: 3.1.0
info:
  title: Medusa Store API
  version: "2"
  description: |
    Medusa Store API - the public REST surface consumed by storefronts and
    end-customer clients of a Medusa commerce application. Provides carts,
    products, collections, categories, regions, customers, orders, payments,
    shipping, returns, and gift cards. Requests are scoped by sales channel
    using a publishable API key passed in the x-publishable-api-key header.
    Customer-scoped requests use a JWT bearer token or a cookie session.
  contact:
    name: Medusa Docs - Store API
    url: https://docs.medusajs.com/api/store
servers:
  - url: "{medusaApplicationUrl}"
    description: Your Medusa application
    variables:
      medusaApplicationUrl:
        default: http://localhost:9000
        description: Base URL of your Medusa server (no trailing slash)
security:
  - publishableApiKey: []
    bearerAuth: []
  - publishableApiKey: []
    cookieAuth: []
components:
  securitySchemes:
    publishableApiKey:
      type: apiKey
      in: header
      name: x-publishable-api-key
      description: Publishable API key that scopes requests to one or more sales channels.
    bearerAuth:
      type: http
      scheme: bearer
      description: JWT bearer token obtained via /auth/customer/{auth_provider}.
    cookieAuth:
      type: apiKey
      in: cookie
      name: connect.sid
  schemas:
    Product:
      type: object
      properties:
        id: { type: string }
        title: { type: string }
        handle: { type: string }
        description: { type: string }
        status: { type: string }
        thumbnail: { type: string }
        variants:
          type: array
          items: { type: object }
    Cart:
      type: object
      properties:
        id: { type: string }
        currency_code: { type: string }
        email: { type: string }
        region_id: { type: string }
        sales_channel_id: { type: string }
        items:
          type: array
          items: { type: object }
    LineItem:
      type: object
      properties:
        variant_id: { type: string }
        quantity: { type: integer }
        metadata: { type: object }
    Order:
      type: object
      properties:
        id: { type: string }
        display_id: { type: integer }
        status: { type: string }
        email: { type: string }
        total: { type: number }
        currency_code: { type: string }
    Customer:
      type: object
      properties:
        id: { type: string }
        email: { type: string }
        first_name: { type: string }
        last_name: { type: string }
    Region:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        currency_code: { type: string }
        countries:
          type: array
          items: { type: object }
paths:
  /auth/customer/{auth_provider}:
    post:
      tags: [Auth]
      summary: Authenticate as a customer
      security:
        - publishableApiKey: []
      parameters:
        - in: path
          name: auth_provider
          required: true
          schema: { type: string, example: emailpass }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email: { type: string }
                password: { type: string }
      responses:
        "200":
          description: JWT token issued
          content:
            application/json:
              schema:
                type: object
                properties:
                  token: { type: string }
  /auth/session:
    post:
      tags: [Auth]
      summary: Exchange a JWT for a cookie session
      responses:
        "200":
          description: Session established
  /store/products:
    get:
      tags: [Products]
      summary: List products
      parameters:
        - in: query
          name: limit
          schema: { type: integer }
        - in: query
          name: offset
          schema: { type: integer }
        - in: query
          name: fields
          schema: { type: string }
        - in: query
          name: order
          schema: { type: string }
      responses:
        "200":
          description: A page of products
          content:
            application/json:
              schema:
                type: object
                properties:
                  products:
                    type: array
                    items: { $ref: "#/components/schemas/Product" }
                  count: { type: integer }
  /store/products/{id}:
    get:
      tags: [Products]
      summary: Get a product
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Product
          content:
            application/json:
              schema:
                type: object
                properties:
                  product: { $ref: "#/components/schemas/Product" }
  /store/carts:
    post:
      tags: [Carts]
      summary: Create a cart
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                region_id: { type: string }
                sales_channel_id: { type: string }
                currency_code: { type: string }
                email: { type: string }
      responses:
        "200":
          description: Cart created
          content:
            application/json:
              schema:
                type: object
                properties:
                  cart: { $ref: "#/components/schemas/Cart" }
  /store/carts/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema: { type: string }
    get:
      tags: [Carts]
      summary: Retrieve a cart
      responses:
        "200":
          description: Cart
          content:
            application/json:
              schema:
                type: object
                properties:
                  cart: { $ref: "#/components/schemas/Cart" }
    post:
      tags: [Carts]
      summary: Update a cart
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/Cart" }
      responses:
        "200":
          description: Updated cart
  /store/carts/{id}/line-items:
    post:
      tags: [Carts]
      summary: Add a line item to a cart
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/LineItem" }
      responses:
        "200":
          description: Cart with line items
  /store/orders:
    get:
      tags: [Orders]
      summary: List the authenticated customer's orders
      security:
        - publishableApiKey: []
          bearerAuth: []
      responses:
        "200":
          description: Orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    items: { $ref: "#/components/schemas/Order" }
  /store/orders/{id}:
    get:
      tags: [Orders]
      summary: Get an order
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Order
          content:
            application/json:
              schema:
                type: object
                properties:
                  order: { $ref: "#/components/schemas/Order" }
  /store/customers:
    post:
      tags: [Customers]
      summary: Register a customer
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/Customer" }
      responses:
        "200":
          description: Customer created
  /store/customers/me:
    get:
      tags: [Customers]
      summary: Get the authenticated customer
      security:
        - publishableApiKey: []
          bearerAuth: []
      responses:
        "200":
          description: Customer
          content:
            application/json:
              schema:
                type: object
                properties:
                  customer: { $ref: "#/components/schemas/Customer" }
  /store/collections:
    get:
      tags: [Collections]
      summary: List collections
      responses:
        "200":
          description: Collections
  /store/categories:
    get:
      tags: [Categories]
      summary: List product categories
      responses:
        "200":
          description: Categories
  /store/regions:
    get:
      tags: [Regions]
      summary: List regions
      responses:
        "200":
          description: Regions
          content:
            application/json:
              schema:
                type: object
                properties:
                  regions:
                    type: array
                    items: { $ref: "#/components/schemas/Region" }
  /store/regions/{id}:
    get:
      tags: [Regions]
      summary: Get a region
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Region
  /store/shipping-options:
    get:
      tags: [Shipping]
      summary: List available shipping options
      parameters:
        - in: query
          name: cart_id
          schema: { type: string }
      responses:
        "200":
          description: Shipping options
  /store/payment-collections:
    post:
      tags: [Payments]
      summary: Create a payment collection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                cart_id: { type: string }
      responses:
        "200":
          description: Payment collection created