medusa-store/docs/api/store/openapi.yaml

openapi: 3.0.0
info:
  version: 1.0.0
  title: Medusa Storefront API
  description: >
    API reference for Medusa's Storefront endpoints. All endpoints are prefixed
    with `/store`.


    ## Authentication


    To send requests as an authenticated customer, you must use the Cookie
    Session ID.


    <!-- ReDoc-Inject: <SecurityDefinitions> -->


    ## Expanding Fields


    In many endpoints you'll find an `expand` query parameter that can be passed
    to the endpoint. You can use the `expand` query parameter to unpack an
    entity's relations and return them in the response.


    Please note that the relations you pass to `expand` replace any relations
    that are expanded by default in the request.


    ### Expanding One Relation


    For example, when you retrieve a product, you can retrieve its collection by
    passing to the `expand` query parameter the value `collection`:


    ```bash

    curl
    "http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand=collection"

    ```


    ### Expanding Multiple Relations


    You can expand more than one relation by separating the relations in the
    `expand` query parameter with a comma.


    For example, to retrieve both the variants and the collection of a product,
    pass to the `expand` query parameter the value `variants,collection`:


    ```bash

    curl
    "http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand=variants,collection"

    ```


    ### Prevent Expanding Relations


    Some requests expand relations by default. You can prevent that by passing
    an empty expand value to retrieve an entity without any extra relations.


    For example:


    ```bash

    curl
    "http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand"

    ```


    This would retrieve the product with only its properties, without any
    relations like `collection`.


    ## Selecting Fields


    In many endpoints you'll find a `fields` query parameter that can be passed
    to the endpoint. You can use the `fields` query parameter to specify which
    fields in the entity should be returned in the response.


    Please note that if you pass a `fields` query parameter, only the fields you
    pass in the value along with the `id` of the entity will be returned in the
    response.


    Also, the `fields` query parameter does not affect the expanded relations.
    You'll have to use the `expand` parameter instead.


    ### Selecting One Field


    For example, when you retrieve a list of products, you can retrieve only the
    titles of the products by passing `title` as a value to the `fields` query
    parameter:


    ```bash

    curl "http://localhost:9000/store/products?fields=title"

    ```


    As mentioned above, the expanded relations such as `variants` will still be
    returned as they're not affected by the `fields` parameter.


    You can ensure that only the `title` field is returned by passing an empty
    value to the `expand` query parameter. For example:


    ```bash

    curl "http://localhost:9000/store/products?fields=title&expand"

    ```


    ### Selecting Multiple Fields


    You can pass more than one field by seperating the field names in the
    `fields` query parameter with a comma.


    For example, to select the `title` and `handle` of a product:


    ```bash

    curl "http://localhost:9000/store/products?fields=title,handle"

    ```


    ### Retrieve Only the ID


    You can pass an empty `fields` query parameter to return only the ID of an
    entity. For example:


    ```bash

    curl "http://localhost:9000/store/products?fields"

    ```


    You can also pair with an empty `expand` query parameter to ensure that the
    relations aren't retrieved as well. For example:


    ```bash

    curl "http://localhost:9000/store/products?fields&expand"

    ```


    ## Query Parameter Types


    This section covers how to pass some common data types as query parameters.
    This is useful if you're sending requests to the API endpoints and not using
    our JS Client. For example, when using cURL or Postman.


    ### Strings


    You can pass a string value in the form of `<parameter_name>=<value>`.


    For example:


    ```bash

    curl "http://localhost:9000/store/products?title=Shirt"

    ```


    If the string has any characters other than letters and numbers, you must
    encode them.


    For example, if the string has spaces, you can encode the space with `+` or
    `%20`:


    ```bash

    curl "http://localhost:9000/store/products?title=Blue%20Shirt"

    ```


    You can use tools like [this one](https://www.urlencoder.org/) to learn how
    a value can be encoded.


    ### Integers


    You can pass an integer value in the form of `<parameter_name>=<value>`.


    For example:


    ```bash

    curl "http://localhost:9000/store/products?offset=1"

    ```


    ### Boolean


    You can pass a boolean value in the form of `<parameter_name>=<value>`.


    For example:


    ```bash

    curl "http://localhost:9000/store/products?is_giftcard=true"

    ```


    ### Date and DateTime


    You can pass a date value in the form `<parameter_name>=<value>`. The date
    must be in the format `YYYY-MM-DD`.


    For example:


    ```bash

    curl -g "http://localhost:9000/store/products?created_at[lt]=2023-02-17"

    ```


    You can also pass the time using the format `YYYY-MM-DDTHH:MM:SSZ`. Please
    note that the `T` and `Z` here are fixed.


    For example:


    ```bash

    curl -g
    "http://localhost:9000/store/products?created_at[lt]=2023-02-17T07:22:30Z"

    ```


    ### Array


    Each array value must be passed as a separate query parameter in the form
    `<parameter_name>[]=<value>`. You can also specify the index of each
    parameter in the brackets `<parameter_name>[0]=<value>`.


    For example:


    ```bash

    curl -g
    "http://localhost:9000/store/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7"

    ```


    Note that the `-g` parameter passed to `curl` disables errors being thrown
    for using the brackets. Read more
    [here](https://curl.se/docs/manpage.html#-g).


    ### Object


    Object parameters must be passed as separate query parameters in the form
    `<parameter_name>[<key>]=<value>`.


    For example:


    ```bash

    curl -g
    "http://localhost:9000/store/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17"

    ```


    ## Pagination


    ### Query Parameters


    In listing endpoints, such as list customers or list products, you can
    control the pagination using the query parameters `limit` and `offset`.


    `limit` is used to specify the maximum number of items that can be return in
    the response. `offset` is used to specify how many items to skip before
    returning the resulting entities.


    You can use the `offset` query parameter to change between pages. For
    example, if the limit is 50, at page 1 the offset should be 0; at page 2 the
    offset should be 50, and so on.


    For example, to limit the number of products returned in the List Products
    endpoint:


    ```bash

    curl "http://localhost:9000/store/products?limit=5"

    ```


    ### Response Fields


    In the response of listing endpoints, aside from the entities retrieved,
    there are three pagination-related fields returned: `count`, `limit`, and
    `offset`.


    Similar to the query parameters, `limit` is the maximum number of items that
    can be returned in the response, and `field` is the number of items that
    were skipped before the entities in the result.


    `count` is the total number of available items of this entity. It can be
    used to determine how many pages are there.


    For example, if the `count` is 100 and the `limit` is 50, you can divide the
    `count` by the `limit` to get the number of pages: `100/50 = 2 pages`.


    ### Sort Order


    The `order` field available on endpoints supporting pagination allows you to
    sort the retrieved items by an attribute of that item. For example, you can
    sort products by their `created_at` attribute by setting `order` to
    `created_at`:


    ```bash

    curl "http://localhost:9000/list/products?order=created_at"

    ```


    By default, the sort direction will be ascending. To change it to
    descending, pass a dash (`-`) before the attribute name. For example:


    ```bash

    curl "http://localhost:9000/list/products?order=-created_at"

    ```


    This sorts the products by their `created_at` attribute in the descending
    order.
  license:
    name: MIT
    url: https://github.com/medusajs/medusa/blob/master/LICENSE
tags:
  - name: Auth
    description: >
      Authentication endpoints allow customers to manage their session, such as
      login or log out.

      When a customer is logged in, the cookie header is set indicating the
      customer's login session.
    externalDocs:
      description: How to implement customer profiles in your storefront
      url: >-
        https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles
  - 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: 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: Gift Cards
    description: >
      Customers can use gift cards during checkout to deduct the gift card's
      balance from the checkout total.

      The Gift Card endpoints allow retrieving a gift card's details by its
      code. A gift card can be applied to a cart using the Carts endpoints.
    externalDocs:
      description: How to use gift cards in a storefront
      url: https://docs.medusajs.com/modules/gift-cards/storefront/use-gift-cards
  - name: Orders
    description: >
      Orders are purchases made by customers, typically through a storefront.

      Orders are placed and created using the Carts endpoints. The Orders
      endpoints allow retrieving and claiming orders.
    externalDocs:
      description: How to retrieve order details in a storefront
      url: >-
        https://docs.medusajs.com/modules/orders/storefront/retrieve-order-details
  - name: Order Edits
    description: >
      Order edits are changes made to items in an order such as adding, updating
      their quantity, or deleting them. Order edits are created by the admin.

      A customer can review order edit requests created by an admin and confirm
      or decline them.
    externalDocs:
      description: How to handle order edits in a storefront
      url: https://docs.medusajs.com/modules/orders/storefront/handle-order-edits
  - name: Payment Collections
    description: >
      A payment collection is useful for managing additional payments, such as
      for Order Edits, or installment payments.
  - name: Products
    description: >
      Products are saleable items in a store. This also includes [saleable gift
      cards](https://docs.medusajs.com/modules/gift-cards/storefront/use-gift-cards)
      in a store.

      Using these endpoints, you can filter products by categories, collections,
      sales channels, and more.
    externalDocs:
      description: How to show products in a storefront
      url: https://docs.medusajs.com/modules/products/storefront/show-products
  - name: Product Variants
    description: >
      Product variants are the actual salable item in your store. Each variant
      is a combination of the different option values available on the product.
  - name: Product Categories
    description: >
      Products can be categoriezed into categories. A product can be associated
      more than one category.

      Using these endpoints, you can list or retrieve a category's details and
      products.
    externalDocs:
      description: How to use product categories in a storefront
      url: https://docs.medusajs.com/modules/products/storefront/use-categories
  - name: Product Collections
    description: >
      A product collection is used to organize products for different purposes
      such as marketing or discount purposes. For example, you can create a
      Summer Collection.

      Using these endpoints, you can list or retrieve a collection's details and
      products.
  - name: Product Tags
    description: |
      Product tags are string values that can be used to filter products by.
      Products can have more than one tag, and products can share tags.
  - name: Product Types
    description: |
      Product types are string values that can be used to filter products by.
      Products can have more than one tag, and products can share types.
  - 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: Returns
    description: |
      A return can be created by a customer to return items in an order.
    externalDocs:
      description: How to create a return in a storefront
      url: https://docs.medusajs.com/modules/orders/storefront/create-return
  - name: Return Reasons
    description: >
      Return reasons are key-value pairs that are used to specify why an order
      return is being created.
  - 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
  - name: Swaps
    description: >
      A swap is created by a customer or an admin to exchange an item with a new
      one.

      Creating a swap implicitely includes creating a return for the item being
      exchanged.
    externalDocs:
      description: How to create a swap in a storefront
      url: https://docs.medusajs.com/modules/orders/storefront/create-swap
servers:
  - url: https://api.medusa-commerce.com
paths:
  /store/auth:
    $ref: paths/store_auth.yaml
  /store/auth/{email}:
    $ref: paths/store_auth_{email}.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}/discounts/{code}:
    $ref: paths/store_carts_{id}_discounts_{code}.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}/payment-session:
    $ref: paths/store_carts_{id}_payment-session.yaml
  /store/carts/{id}/payment-sessions:
    $ref: paths/store_carts_{id}_payment-sessions.yaml
  /store/carts/{id}/payment-sessions/{provider_id}:
    $ref: paths/store_carts_{id}_payment-sessions_{provider_id}.yaml
  /store/carts/{id}/payment-sessions/{provider_id}/refresh:
    $ref: paths/store_carts_{id}_payment-sessions_{provider_id}_refresh.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/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/customers/me/orders:
    $ref: paths/store_customers_me_orders.yaml
  /store/customers/me/payment-methods:
    $ref: paths/store_customers_me_payment-methods.yaml
  /store/customers/password-reset:
    $ref: paths/store_customers_password-reset.yaml
  /store/customers/password-token:
    $ref: paths/store_customers_password-token.yaml
  /store/gift-cards/{code}:
    $ref: paths/store_gift-cards_{code}.yaml
  /store/order-edits/{id}:
    $ref: paths/store_order-edits_{id}.yaml
  /store/order-edits/{id}/complete:
    $ref: paths/store_order-edits_{id}_complete.yaml
  /store/order-edits/{id}/decline:
    $ref: paths/store_order-edits_{id}_decline.yaml
  /store/orders:
    $ref: paths/store_orders.yaml
  /store/orders/batch/customer/token:
    $ref: paths/store_orders_batch_customer_token.yaml
  /store/orders/cart/{cart_id}:
    $ref: paths/store_orders_cart_{cart_id}.yaml
  /store/orders/customer/confirm:
    $ref: paths/store_orders_customer_confirm.yaml
  /store/orders/{id}:
    $ref: paths/store_orders_{id}.yaml
  /store/payment-collections/{id}:
    $ref: paths/store_payment-collections_{id}.yaml
  /store/payment-collections/{id}/sessions:
    $ref: paths/store_payment-collections_{id}_sessions.yaml
  /store/payment-collections/{id}/sessions/batch:
    $ref: paths/store_payment-collections_{id}_sessions_batch.yaml
  /store/payment-collections/{id}/sessions/batch/authorize:
    $ref: paths/store_payment-collections_{id}_sessions_batch_authorize.yaml
  /store/payment-collections/{id}/sessions/{session_id}:
    $ref: paths/store_payment-collections_{id}_sessions_{session_id}.yaml
  /store/payment-collections/{id}/sessions/{session_id}/authorize:
    $ref: paths/store_payment-collections_{id}_sessions_{session_id}_authorize.yaml
  /store/product-categories:
    $ref: paths/store_product-categories.yaml
  /store/product-categories/{id}:
    $ref: paths/store_product-categories_{id}.yaml
  /store/product-tags:
    $ref: paths/store_product-tags.yaml
  /store/product-types:
    $ref: paths/store_product-types.yaml
  /store/products:
    $ref: paths/store_products.yaml
  /store/products/search:
    $ref: paths/store_products_search.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-reasons:
    $ref: paths/store_return-reasons.yaml
  /store/return-reasons/{id}:
    $ref: paths/store_return-reasons_{id}.yaml
  /store/returns:
    $ref: paths/store_returns.yaml
  /store/shipping-options:
    $ref: paths/store_shipping-options.yaml
  /store/shipping-options/{cart_id}:
    $ref: paths/store_shipping-options_{cart_id}.yaml
  /store/swaps:
    $ref: paths/store_swaps.yaml
  /store/swaps/{cart_id}:
    $ref: paths/store_swaps_{cart_id}.yaml
  /store/variants:
    $ref: paths/store_variants.yaml
  /store/variants/{id}:
    $ref: paths/store_variants_{id}.yaml
components:
  securitySchemes:
    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.