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
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"
  - 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"
  - 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"
  - 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"
  - 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"
  - 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"
  - 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"
  - 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"
  - name: Product Tags
    x-associatedSchema:
      $ref: "#/components/schemas/StoreProductTag"
  - name: Product Types
    x-associatedSchema:
      $ref: "#/components/schemas/StoreProductType"
  - 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"
  - 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"
  - 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"
  - 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"
  - 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"
servers:
  - url: http://localhost:9000
  - url: https://api.medusajs.com
paths: {}
components:
  schemas:
    Error:
      title: Response Error
      type: object
      properties:
        code:
          type: string
          description: A slug code to indicate the type of the error.
          enum:
            - invalid_state_error
            - invalid_request_error
            - api_error
            - unknown_error
        message:
          type: string
          description: Description of the error that occurred.
          example: first_name must be a string
        type:
          type: string
          description: A slug indicating the type of the error.
          enum:
            - QueryRunnerAlreadyReleasedError
            - TransactionAlreadyStartedError
            - TransactionNotStartedError
            - conflict
            - unauthorized
            - payment_authorization_error
            - duplicate_error
            - not_allowed
            - invalid_data
            - not_found
            - database_error
            - unexpected_state
            - invalid_argument
            - unknown_error
  responses:
    default_error:
      description: Default Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            code: unknown_error
            message: An unknown error occurred.
            type: unknown_error
    invalid_state_error:
      description: Invalid State Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            code: unknown_error
            message: The request conflicted with another request. You may retry the request
              with the provided Idempotency-Key.
            type: QueryRunnerAlreadyReleasedError
    invalid_request_error:
      description: Invalid Request Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            code: invalid_request_error
            message: Discount with code TEST already exists.
            type: duplicate_error
    not_found_error:
      description: Not Found Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            message: Entity with id 1 was not found
            type: not_found
    400_error:
      description: Client Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            not_allowed:
              $ref: "#/components/examples/not_allowed_error"
            invalid_data:
              $ref: "#/components/examples/invalid_data_error"
    500_error:
      description: Server Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            database:
              $ref: "#/components/examples/database_error"
            unexpected_state:
              $ref: "#/components/examples/unexpected_state_error"
            invalid_argument:
              $ref: "#/components/examples/invalid_argument_error"
            default_error:
              $ref: "#/components/examples/default_error"
    unauthorized:
      description: User is not authorized. Must log in first
      content:
        text/plain:
          schema:
            type: string
            default: Unauthorized
            example: Unauthorized
    incorrect_credentials:
      description: User does not exist or incorrect credentials
      content:
        text/plain:
          schema:
            type: string
            default: Unauthorized
            example: Unauthorized
  examples:
    not_allowed_error:
      summary: Not Allowed Error
      value:
        message: Discount must be set to dynamic
        type: not_allowed
    invalid_data_error:
      summary: Invalid Data Error
      value:
        message: first_name must be a string
        type: invalid_data
    multiple_errors:
      summary: Multiple Errors
      value:
        message: Provided request body contains errors. Please check the data and retry
          the request
        errors:
          - message: first_name must be a string
            type: invalid_data
          - message: Discount must be set to dynamic
            type: not_allowed
    database_error:
      summary: Database Error
      value:
        code: api_error
        message: An error occured while hashing password
        type: database_error
    unexpected_state_error:
      summary: Unexpected State Error
      value:
        message: cart.total must be defined
        type: unexpected_state
    invalid_argument_error:
      summary: Invalid Argument Error
      value:
        message: cart.total must be defined
        type: unexpected_state
    default_error:
      summary: Default Error
      value:
        code: unknown_error
        message: An unknown error occurred.
        type: unknown_error
  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
    reset_password:
      type: http
      x-displayName: Reset Password Token
      scheme: bearer
      x-is-auth: false