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.medusa-commerce.com
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: Collections
  - name: Currencies
  - name: Customers
  - name: Orders
  - name: Payment Collections
    description: >
      A payment collection is useful for managing additional payments, such as
      for Order Edits, or installment payments.
  - name: Payment Providers
  - name: Product Categories
    x-associatedSchema:
      $ref: ./components/schemas/StoreProductCategory.yaml
  - name: 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, 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: Return
  - name: Return Reasons
  - name: Shipping Options
paths:
  /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}/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/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
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
      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.