medusa-store/www/apps/api-reference/specs/store/openapi.yaml

openapi: 3.0.0
info:
  version: 2.0.0
  title: Medusa Storefront API
  license:
    name: MIT
    url: https://github.com/medusajs/medusa/blob/master/LICENSE
servers:
  - url: http://localhost:9000
  - url: https://api.medusajs.com
tags:
  - name: Auth
    description: |
      Auth API routes allow you to manage a customer's authentication.
  - name: Carts
    description: >
      A cart is a virtual shopping bag that customers can use to add items they
      want to purchase.


      A cart is then used to checkout and place an order.


      These API routes allow customers to create and manage their cart, and
      place an order.
    externalDocs:
      description: How to implement cart functionality in a storefront.
      url: https://docs.medusajs.com/v2/resources/storefront-development/cart
    x-associatedSchema:
      $ref: ./components/schemas/StoreCart.yaml
  - name: Collections
    description: >
      A product collection organizes products into a collection for marketing
      purposes. For example, a summer collection.


      These API routes allow customers to browse collections and their products.
    externalDocs:
      description: How to list product collections in a storefront.
      url: >-
        https://docs.medusajs.com/v2/resources/storefront-development/products/collections/list
    x-associatedSchema:
      $ref: ./components/schemas/StoreCollection.yaml
  - name: Currencies
    description: >
      A store has multiple currencies, and product prices can be different for
      each currency.


      When retrieving product variant prices, you specify either the ID of a
      region or a currency that the customer selected.


      These API routes allow customers to browse currencies.
    externalDocs:
      description: How to retrieve product variant prices in a storefront.
      url: >-
        https://docs.medusajs.com/v2/resources/storefront-development/products/price
    x-associatedSchema:
      $ref: ./components/schemas/StoreCurrency.yaml
  - name: Customers
    description: >
      Customers can place orders as guest customers or register.


      When a customer registers, they can manage their profile, save addresses
      for later usage, and more.


      These API routes allow customers to create and manage their accounts.
    externalDocs:
      description: How to implement customer account functionalities in a storefront.
      url: https://docs.medusajs.com/v2/resources/storefront-development/customers
    x-associatedSchema:
      $ref: ./components/schemas/StoreCustomer.yaml
  - name: Orders
    description: |
      Guest and registered customers can view orders they placed.

      These API routes allow customers to view their orders.
    x-associatedSchema:
      $ref: ./components/schemas/StoreOrder.yaml
  - name: Payment Collections
    description: >
      A cart must have a payment collection with an authorized payment session.


      Use these API routes during checkout to set the cart's payment provider
      and authorize its payment session.
    externalDocs:
      description: How to implement payment during checkout.
      url: >-
        https://docs.medusajs.com/v2/resources/storefront-development/checkout/payment
    x-associatedSchema:
      $ref: ./components/schemas/StorePaymentCollection.yaml
  - name: Payment Providers
    description: >
      Each region has a set of payment providers enabled.


      During checkout, you retrieve the available payment providers in the
      customer's region to show them to the customer. Customers then choose
      their preferred provider to authorize their payment and place their order.


      These API routes allow customers to view available payment providers in
      their region.
    externalDocs:
      description: How to implement payment during checkout.
      url: >-
        https://docs.medusajs.com/v2/resources/storefront-development/checkout/payment
    x-associatedSchema:
      $ref: ./components/schemas/StorePaymentProvider.yaml
  - name: Product Categories
    description: |
      Products can be categorized into categories.

      These API routes allow customers to browse categories and their products.
    externalDocs:
      description: How to list product categories in a storefront.
      url: >-
        https://docs.medusajs.com/v2/resources/storefront-development/products/categories/list
    x-associatedSchema:
      $ref: ./components/schemas/StoreProductCategory.yaml
  - name: Products
    description: >
      Customers browse products for their purchase.


      A product has variants for different option values. The customer chooses
      from these variants before adding it to the cart.


      These API routes allow customers to browse products.
    externalDocs:
      description: How to list products, get their prices, and more in a storefront.
      url: https://docs.medusajs.com/v2/resources/storefront-development/products
    x-associatedSchema:
      $ref: ./components/schemas/StoreProduct.yaml
  - name: Regions
    description: >
      Regions are different countries or geographical regions that the commerce
      store serves customers in.


      Customers can choose what region they're in to view prices of that
      region's currency.


      Use these API routes to retrieve available regions in the store.
    externalDocs:
      description: How to retrieve and store selected region in a storefront.
      url: https://docs.medusajs.com/v2/resources/storefront-development/regions
    x-associatedSchema:
      $ref: ./components/schemas/StoreRegion.yaml
  - name: Return
    description: >
      Customers can request to return items in their order. The admin user then
      receives and handles the return.


      These API routes allows customers to create a return.
    x-associatedSchema:
      $ref: ./components/schemas/StoreReturn.yaml
  - name: Return Reasons
    description: >
      A return reason is a possible reason a customer wants to return an item.


      Use these API routes when implementing return creation flow in your
      storefront to allow customers to select their return reason.
    x-associatedSchema:
      $ref: ./components/schemas/StoreReturnReason.yaml
  - name: Shipping Options
    description: >
      A shipping option is a way of shipping an item to or from the customer.


      During the checkout flow, the customer selects their preferred shipping
      option to receive their order.


      These API routes allow customers to retrieve available shipping options
      for their context.
    externalDocs:
      description: How to implement shipping during checkout.
      url: >-
        https://docs.medusajs.com/v2/resources/storefront-development/checkout/shipping
    x-associatedSchema:
      $ref: ./components/schemas/StoreShippingOption.yaml
paths:
  /auth/customer/{auth_provider}:
    $ref: paths/auth_customer_{auth_provider}.yaml
  /auth/customer/{auth_provider}/callback:
    $ref: paths/auth_customer_{auth_provider}_callback.yaml
  /auth/customer/{auth_provider}/register:
    $ref: paths/auth_customer_{auth_provider}_register.yaml
  /auth/customer/{auth_provider}/reset-password:
    $ref: paths/auth_customer_{auth_provider}_reset-password.yaml
  /auth/customer/{auth_provider}/update:
    $ref: paths/auth_customer_{auth_provider}_update.yaml
  /auth/session:
    $ref: paths/auth_session.yaml
  /auth/token/refresh:
    $ref: paths/auth_token_refresh.yaml
  /store/carts:
    $ref: paths/store_carts.yaml
  /store/carts/{id}:
    $ref: paths/store_carts_{id}.yaml
  /store/carts/{id}/complete:
    $ref: paths/store_carts_{id}_complete.yaml
  /store/carts/{id}/customer:
    $ref: paths/store_carts_{id}_customer.yaml
  /store/carts/{id}/line-items:
    $ref: paths/store_carts_{id}_line-items.yaml
  /store/carts/{id}/line-items/{line_id}:
    $ref: paths/store_carts_{id}_line-items_{line_id}.yaml
  /store/carts/{id}/promotions:
    $ref: paths/store_carts_{id}_promotions.yaml
  /store/carts/{id}/shipping-methods:
    $ref: paths/store_carts_{id}_shipping-methods.yaml
  /store/carts/{id}/taxes:
    $ref: paths/store_carts_{id}_taxes.yaml
  /store/collections:
    $ref: paths/store_collections.yaml
  /store/collections/{id}:
    $ref: paths/store_collections_{id}.yaml
  /store/currencies:
    $ref: paths/store_currencies.yaml
  /store/currencies/{code}:
    $ref: paths/store_currencies_{code}.yaml
  /store/customers:
    $ref: paths/store_customers.yaml
  /store/customers/me:
    $ref: paths/store_customers_me.yaml
  /store/customers/me/addresses:
    $ref: paths/store_customers_me_addresses.yaml
  /store/customers/me/addresses/{address_id}:
    $ref: paths/store_customers_me_addresses_{address_id}.yaml
  /store/orders:
    $ref: paths/store_orders.yaml
  /store/orders/{id}:
    $ref: paths/store_orders_{id}.yaml
  /store/orders/{id}/transfer/accept:
    $ref: paths/store_orders_{id}_transfer_accept.yaml
  /store/orders/{id}/transfer/cancel:
    $ref: paths/store_orders_{id}_transfer_cancel.yaml
  /store/orders/{id}/transfer/decline:
    $ref: paths/store_orders_{id}_transfer_decline.yaml
  /store/orders/{id}/transfer/request:
    $ref: paths/store_orders_{id}_transfer_request.yaml
  /store/payment-collections:
    $ref: paths/store_payment-collections.yaml
  /store/payment-collections/{id}/payment-sessions:
    $ref: paths/store_payment-collections_{id}_payment-sessions.yaml
  /store/payment-providers:
    $ref: paths/store_payment-providers.yaml
  /store/product-categories:
    $ref: paths/store_product-categories.yaml
  /store/product-categories/{id}:
    $ref: paths/store_product-categories_{id}.yaml
  /store/products:
    $ref: paths/store_products.yaml
  /store/products/{id}:
    $ref: paths/store_products_{id}.yaml
  /store/regions:
    $ref: paths/store_regions.yaml
  /store/regions/{id}:
    $ref: paths/store_regions_{id}.yaml
  /store/return:
    $ref: paths/store_return.yaml
  /store/return-reasons:
    $ref: paths/store_return-reasons.yaml
  /store/return-reasons/{id}:
    $ref: paths/store_return-reasons_{id}.yaml
  /store/shipping-options:
    $ref: paths/store_shipping-options.yaml
  /store/shipping-options/{id}/calculate:
    $ref: paths/store_shipping-options_{id}_calculate.yaml
components:
  securitySchemes:
    jwt_token:
      type: http
      x-displayName: JWT Token
      scheme: bearer
    cookie_auth:
      type: apiKey
      x-displayName: Cookie Session ID
      in: cookie
      name: connect.sid