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: 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.
    externalDocs:
      description: How to implement cart functionality in your storefront
      url: https://docs.medusajs.com/modules/carts-and-checkout/storefront/implement-cart
  - name: Currencies
  - name: Customers
    description: >
      A customer can register and manage their information such as addresses,
      orders, payment methods, and more.
    externalDocs:
      description: How to implement customer profiles in your storefront
      url: https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles
  - name: Payment Collections
    description: >
      A payment collection is useful for managing additional payments, such as
      for Order Edits, or installment payments.
  - 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, which can be used to change the prices shown based on the region and its currency.
    externalDocs:
      description: How to use regions in a storefront
      url: https://docs.medusajs.com/modules/regions-and-currencies/storefront/use-regions
  - name: Shipping Options
    description: >
      A shipping option is used to define the available shipping methods during
      checkout or when creating a return.
    externalDocs:
      description: Shipping Option architecture
      url: https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-option
servers:
  - url: http://localhost:9000
  - url: https://api.medusa-commerce.com
paths: {}
components:
  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 or Multiple Errors
      content:
        application/json:
          schema:
            oneOf:
              - $ref: "#/components/schemas/Error"
              - $ref: "#/components/schemas/MultipleErrors"
          examples:
            not_allowed:
              $ref: "#/components/examples/not_allowed_error"
            invalid_data:
              $ref: "#/components/examples/invalid_data_error"
            MultipleErrors:
              $ref: "#/components/examples/multiple_errors"
    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
      description: >
        Use a cookie session to send authenticated requests.


        ### How to Obtain the Cookie Session


        If you're sending requests through a browser, using JS Client, or using tools like Postman, the cookie session should be automatically set when the customer is logged in.


        If you're sending requests using cURL, you must set the Session ID in the cookie manually.


        To do that, send a request to [authenticate the customer](#tag/Auth/operation/PostAuth) and pass the cURL option `-v`:


        ```bash

        curl -v --location --request POST 'https://medusa-url.com/store/auth' \

        --header 'Content-Type: application/json' \

        --data-raw '{
          "email": "user@example.com",
          "password": "supersecret"
        }'

        ```


        The headers will be logged in the terminal as well as the response. You should find in the headers a Cookie header similar to this:


        ```bash

        Set-Cookie: connect.sid=s%3A2Bu8BkaP9JUfHu9rG59G16Ma0QZf6Gj1.WT549XqX37PN8n0OecqnMCq798eLjZC5IT7yiDCBHPM;

        ```


        Copy the value after `connect.sid` (without the `;` at the end) and pass it as a cookie in subsequent requests as the following:


        ```bash

        curl --location --request GET 'https://medusa-url.com/store/customers/me/orders' \

        --header 'Cookie: connect.sid={sid}'

        ```


        Where `{sid}` is the value of `connect.sid` that you copied.