medusa-store/www/apps/api-reference/app/_mdx/store.mdx

import { Feedback, CodeTabs, CodeTab } from "docs-ui"
import SectionContainer from "@/components/Section/Container"
import formatReportLink from "@/utils/format-report-link"
import VersionNote from "@/components/VersionNote"

<SectionContainer noTopPadding={true}>

<VersionNote />

This API reference includes Medusa's Store APIs, which are REST APIs exposed by the Medusa backend. They are typically used to create a storefront for your commerce store, such as a webshop or a commerce mobile app.

All API Routes are prefixed with `/store`. So, during development, the API Routes will be available under the path `http://localhost:9000/store`. For production, replace `http://localhost:9000` with your Medusa backend URL.

There are different ways you can send requests to these API Routes, including:

- Using Medusa's [JavaScript Client](https://docs.medusajs.com/js-client/overview)
- Using the [Medusa React](https://docs.medusajs.com/medusa-react/overview) library
- Using cURL

Aside from this API reference, check out the [Commerce Modules](https://docs.medusajs.com/modules/overview) section of the documentation for guides on how to use these APIs in different scenarios.

<Feedback
  event="survey_api-ref"
  extraData={{
    area: "store",
    section: "introduction"
  }}
  reportLink={formatReportLink("store", "Introduction")}
  pathName="/api/store"
/>

</SectionContainer>

<SectionContainer noTopPadding={true}>

## Authentication

There are two ways to send authenticated requests to the Medusa server: Using a JWT token or using a Cookie Session ID.

### JWT Token

Use a JWT token to send authenticated requests. Authentication state is managed by the client, which is ideal for Jamstack applications and mobile applications.

#### How to Obtain the JWT Token

JWT tokens are obtained by sending a request to the [Customer Login (JWT) API Route](#auth_authtoken) passing it the customer's email and password in the request body. For example:

```bash
curl -X POST 'https://medusa-url.com/store/auth/token' \
-H 'Content-Type: application/json' \
--data-raw '{
  "email": "user@example.com",
  "password": "supersecret"
}'

```

If authenticated successfully, an object is returned in the response with the property `access_token` being the JWT token.

#### How to Use the JWT Token

The JWT token can be used for Bearer Authentication. It's passed in the
`Authorization` header as the following:


```bash
Authorization: Bearer {jwt_token}
```

### Cookie Session ID

Use a cookie session to send authenticated requests.

#### How to Obtain the Cookie Session


If you're sending requests through a browser, using Medusa's JS and Medusa React clients, 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 -X POST 'https://medusa-url.com/store/auth' \
-H '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 'https://medusa-url.com/store/customers/me/orders' \
-H 'Cookie: connect.sid={sid}'
```

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

If you're sending requests using JavaScript's Fetch API, you must pass the `credentials` option 
with the value `include` to all the requests you're sending. For example:

```js
fetch(`<BACKEND_URL>/admin/products`, {
  credentials: "include",
})
```

<Feedback
  event="survey_api-ref"
  extraData={{
    area: "store",
    section: "authentication-cookie"
  }}
  reportLink={formatReportLink("store", "Authentication - Cookie Session ID")}
  pathName="/api/store"
/>

</SectionContainer>

<SectionContainer noTopPadding={true}>

## Publishable API Key

Publishable API Keys allow you to send a request with a pre-defined scope. You can associate the
publishable API key with one or more resources, such as sales channels, then include the publishable
API key in the header of your requests.

The Medusa backend will infer the scope of the current
request based on the publishable API key. At the moment, publishable API keys only work with sales channels.

It's highly recommended to create a publishable API key and pass it in the header of all your requests to the 
store APIs.

You can learn more about publishable API keys and how to use them in [this documentation](https://docs.medusajs.com/development/publishable-api-keys/).

### How to Create a Publishable API Key

You can create a publishable API key either using the [admin REST APIs](https://docs.medusajs.com/development/publishable-api-keys/admin/manage-publishable-api-keys),
or using the [Medusa Admin](https://docs.medusajs.com/user-guide/settings/publishable-api-keys).

### How to Use a Publishable API Key

You can pass the publishable API key in the header `x-publishable-api-key` in all your requests to the store APIs:

```bash
x-publishable-api-key: {your_publishable_api_key}
```

If you're using Medusa's JS or Medusa React clients, you can pass the publishable API key when you first
initialize either clients. Then, the publishable API key will be automatically included in all your requests:

<CodeTabs group="clients">
  <CodeTab label="Medusa JS Client" value="js-client">
    
    ```ts
    const medusa = new Medusa({
      maxRetries: 3,
      baseUrl: "https://api.example.com",
      publishableApiKey,
    })
    ```

  </CodeTab>
  <CodeTab label="Medusa React" value="medusa-react">
    
    ```tsx
    import { MedusaProvider } from "medusa-react"

    // define query client...

    const App = () => {
      return (
        <MedusaProvider
          queryClientProviderProps={{ client: queryClient }}
          baseUrl="http://localhost:9000"
          // ...
          publishableApiKey={publishableApiKey}
        >
          <MyStorefront />
        </MedusaProvider>
      )
    }
    ```

  </CodeTab>
</CodeTabs>

<Feedback
  event="survey_api-ref"
  extraData={{
    area: "store",
    section: "publishable-api-key"
  }}
  reportLink={formatReportLink("store", "Publishable API Key")}
  pathName="/api/store"
/>

</SectionContainer>

<SectionContainer noTopPadding={true}>

## HTTP Compression

If you've enabled HTTP Compression in your Medusa configurations, and you 
want to disable it for some requests, you can pass the `x-no-compression`
header in your requests:

```bash
x-no-compression: true
```

If you're using the Medusa JS Client, you can pass custom headers in the 
last parameter of a method. For example:

```ts
medusa.products.list({}, {
  "x-no-compression": true
})
.then(({ products, limit, offset, count }) => {
  console.log(products.length)
})
```

You can also pass the header when you first initialize the Medusa client:

```ts
const medusa = new Medusa({
  maxRetries: 3,
  baseUrl: "https://api.example.com",
  customHeaders: {
    "x-no-compression": true
  }
})
```

For Medusa React, it's not possible to pass custom headers for a query or mutation, but
you can pass the header to the `MedusaProvider` and it will be added to all subsequent requests:

```tsx
import { MedusaProvider } from "medusa-react"

// define query client...

const App = () => {
  return (
    <MedusaProvider
      queryClientProviderProps={{ client: queryClient }}
      baseUrl="http://localhost:9000"
      // ...
      customHeaders={{
        "x-no-compression": true
      }}
    >
      <MyStorefront />
    </MedusaProvider>
  )
}
```

<Feedback
  event="survey_api-ref"
  extraData={{
    area: "store",
    section: "http-compression"
  }}
  reportLink={formatReportLink("store", "HTTP Compression")}
  pathName="/api/store"
/>

</SectionContainer>

<SectionContainer noTopPadding={true}>

## Expanding Fields


In many API Routes you'll find an `expand` query parameter that can be passed
to the API Route. 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 list of products, you can retrieve their collections by
passing to the `expand` query parameter the value `collection`:

<CodeTabs group="clients">
  <CodeTab label="cURL" value="curl">
    
    ```bash
    curl "http://localhost:9000/store/products?expand=collection"
    ```

  </CodeTab>
  <CodeTab label="Medusa JS Client" value="js-client">
    
    ```ts
    import Medusa from "@medusajs/medusa-js"
    const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    medusa.products.list({
      expand: "collection"
    })
    .then(({ products, limit, offset, count }) => {
      console.log(products.length);
    });
    ```

  </CodeTab>
  <CodeTab label="Medusa React" value="medusa-react">
    
    ```tsx
    import { useProducts } from "medusa-react"

    const Products = () => {
      const { products, isLoading } = useProducts({
        expand: "collection"
      })

      return (
        <div>
          {/* ... */}
        </div>
      )
    }

    export default Products
    ```

  </CodeTab>
</CodeTabs>

### 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 the products,
pass to the `expand` query parameter the value `variants,collection`:

<CodeTabs group="clients">
  <CodeTab label="cURL" value="curl">
    
    ```bash
    curl "http://localhost:9000/store/products?expand=variants,collection"
    ```

  </CodeTab>
  <CodeTab label="Medusa JS Client" value="js-client">
    
    ```ts
    import Medusa from "@medusajs/medusa-js"
    const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    medusa.products.list({
      expand: "variants,collection"
    })
    .then(({ products, limit, offset, count }) => {
      console.log(products.length);
    });
    ```

  </CodeTab>
  <CodeTab label="Medusa React" value="medusa-react">
    
    ```tsx
    import { useProducts } from "medusa-react"

    const Products = () => {
      const { products, isLoading } = useProducts({
        expand: "variants,collection"
      })

      return (
        <div>
          {/* ... */}
        </div>
      )
    }

    export default Products
    ```

  </CodeTab>
</CodeTabs>


### 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:

<CodeTabs group="clients">
  <CodeTab label="cURL" value="curl">
    
    ```bash
    curl "http://localhost:9000/store/products?expand"
    ```

  </CodeTab>
  <CodeTab label="Medusa JS Client" value="js-client">
    
    ```ts
    import Medusa from "@medusajs/medusa-js"
    const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    medusa.products.list({
      expand: ""
    })
    .then(({ products, limit, offset, count }) => {
      console.log(products.length);
    });
    ```

  </CodeTab>
  <CodeTab label="Medusa React" value="medusa-react">
    
    ```tsx
    import { useProducts } from "medusa-react"

    const Products = () => {
      const { products, isLoading } = useProducts({
        expand: ""
      })

      return (
        <div>
          {/* ... */}
        </div>
      )
    }

    export default Products
    ```

  </CodeTab>
</CodeTabs>


This would retrieve the products with only their properties, without any
relations like `collection`.

<Feedback
  event="survey_api-ref"
  extraData={{
    area: "store",
    section: "expand"
  }}
  reportLink={formatReportLink("store", "Expanding Fields")}
  pathName="/api/store"
/>

</SectionContainer>

<SectionContainer noTopPadding={true}>

## Selecting Fields


In many API Routes you'll find a `fields` query parameter that can be passed
to the API Route. 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:

<CodeTabs group="clients">
  <CodeTab label="cURL" value="curl">
    
    ```bash
    curl "http://localhost:9000/store/products?fields=title"
    ```

  </CodeTab>
  <CodeTab label="Medusa JS Client" value="js-client">
    
    ```ts
    import Medusa from "@medusajs/medusa-js"
    const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    medusa.products.list({
      fields: "title"
    })
    .then(({ products, limit, offset, count }) => {
      console.log(products.length);
    });
    ```

  </CodeTab>
  <CodeTab label="Medusa React" value="medusa-react">
    
    ```tsx
    import { useProducts } from "medusa-react"

    const Products = () => {
      const { products, isLoading } = useProducts({
        fields: "title"
      })

      return (
        <div>
          {/* ... */}
        </div>
      )
    }

    export default Products
    ```

  </CodeTab>
</CodeTabs>


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:

<CodeTabs group="clients">
  <CodeTab label="cURL" value="curl">
    
    ```bash
    curl "http://localhost:9000/store/products?fields=title&expand"
    ```

  </CodeTab>
  <CodeTab label="Medusa JS Client" value="js-client">
    
    ```ts
    import Medusa from "@medusajs/medusa-js"
    const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    medusa.products.list({
      fields: "title",
      expand: ""
    })
    .then(({ products, limit, offset, count }) => {
      console.log(products.length);
    });
    ```

  </CodeTab>
  <CodeTab label="Medusa React" value="medusa-react">
    
    ```tsx
    import { useProducts } from "medusa-react"

    const Products = () => {
      const { products, isLoading } = useProducts({
        fields: "title",
        expand: ""
      })

      return (
        <div>
          {/* ... */}
        </div>
      )
    }

    export default Products
    ```

  </CodeTab>
</CodeTabs>


### 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 the products:

<CodeTabs group="clients">
  <CodeTab label="cURL" value="curl">
    
    ```bash
    curl "http://localhost:9000/store/products?fields=title,handle"
    ```

  </CodeTab>
  <CodeTab label="Medusa JS Client" value="js-client">
    
    ```ts
    import Medusa from "@medusajs/medusa-js"
    const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    medusa.products.list({
      fields: "title,handle"
    })
    .then(({ products, limit, offset, count }) => {
      console.log(products.length);
    });
    ```

  </CodeTab>
  <CodeTab label="Medusa React" value="medusa-react">
    
    ```tsx
    import { useProducts } from "medusa-react"

    const Products = () => {
      const { products, isLoading } = useProducts({
        fields: "title,handle"
      })

      return (
        <div>
          {/* ... */}
        </div>
      )
    }

    export default Products
    ```

  </CodeTab>
</CodeTabs>


### Retrieve Only the ID


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

<CodeTabs group="clients">
  <CodeTab label="cURL" value="curl">
    
    ```bash
    curl "http://localhost:9000/store/products?fields"
    ```

  </CodeTab>
  <CodeTab label="Medusa JS Client" value="js-client">
    
    ```ts
    import Medusa from "@medusajs/medusa-js"
    const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    medusa.products.list({
      fields: ""
    })
    .then(({ products, limit, offset, count }) => {
      console.log(products.length);
    });
    ```

  </CodeTab>
  <CodeTab label="Medusa React" value="medusa-react">
    
    ```tsx
    import { useProducts } from "medusa-react"

    const Products = () => {
      const { products, isLoading } = useProducts({
        fields: ""
      })

      return (
        <div>
          {/* ... */}
        </div>
      )
    }

    export default Products
    ```

  </CodeTab>
</CodeTabs>


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

<CodeTabs group="clients">
  <CodeTab label="cURL" value="curl">
    
    ```bash
    curl "http://localhost:9000/store/products?fields"
    ```

  </CodeTab>
  <CodeTab label="Medusa JS Client" value="js-client">
    
    ```ts
    import Medusa from "@medusajs/medusa-js"
    const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    medusa.products.list({
      fields: "",
      expand: ""
    })
    .then(({ products, limit, offset, count }) => {
      console.log(products.length);
    });
    ```

  </CodeTab>
  <CodeTab label="Medusa React" value="medusa-react">
    
    ```tsx
    import { useProducts } from "medusa-react"

    const Products = () => {
      const { products, isLoading } = useProducts({
        fields: "",
        expand: ""
      })

      return (
        <div>
          {/* ... */}
        </div>
      )
    }

    export default Products
    ```

  </CodeTab>
</CodeTabs>

<Feedback
  event="survey_api-ref"
  extraData={{
    area: "store",
    section: "select-fields"
  }}
  reportLink={formatReportLink("store", "Selecting Fields")}
  pathName="/api/store"
/>

</SectionContainer>

<SectionContainer noTopPadding={true}>

## 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 Routes 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"
```

<Feedback
  event="survey_api-ref"
  extraData={{
    area: "store",
    section: "query-parameters"
  }}
  reportLink={formatReportLink("store", "Query Parameter Types")}
  pathName="/api/store"
/>

</SectionContainer>

<SectionContainer noTopPadding={true}>

## Pagination


### Query Parameters


In listing API Routes, 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
API Route:

<CodeTabs group="clients">
  <CodeTab label="cURL" value="curl">
    
    ```bash
    curl "http://localhost:9000/store/products?limit=5"
    ```

  </CodeTab>
  <CodeTab label="Medusa JS Client" value="js-client">
    
    ```ts
    import Medusa from "@medusajs/medusa-js"
    const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    medusa.products.list({
      limit: 5
    })
    .then(({ products, limit, offset, count }) => {
      console.log(products.length);
    });
    ```

  </CodeTab>
  <CodeTab label="Medusa React" value="medusa-react">
    
    ```tsx
    import { useProducts } from "medusa-react"

    const Products = () => {
      const { products, isLoading } = useProducts({
        limit: 5
      })

      return (
        <div>
          {/* ... */}
        </div>
      )
    }

    export default Products
    ```

  </CodeTab>
</CodeTabs>


### Response Fields


In the response of listing API Routes, aside from the entities retrieved,
there are three pagination-related fields returned:


- `limit`: the maximum number of items that can be returned in the response.
- `offset`: the number of items that were skipped before the entities in the result.
- `count`: 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 API Routes 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`:

<CodeTabs group="clients">
  <CodeTab label="cURL" value="curl">
    
    ```bash
    curl "http://localhost:9000/store/products?order=created_at"
    ```

  </CodeTab>
  <CodeTab label="Medusa JS Client" value="js-client">
    
    ```ts
    import Medusa from "@medusajs/medusa-js"
    const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    medusa.products.list({
      order: "created_at"
    })
    .then(({ products, limit, offset, count }) => {
      console.log(products.length);
    });
    ```

  </CodeTab>
  <CodeTab label="Medusa React" value="medusa-react">
    
    ```tsx
    import { useProducts } from "medusa-react"

    const Products = () => {
      const { products, isLoading } = useProducts({
        order: "created_at"
      })

      return (
        <div>
          {/* ... */}
        </div>
      )
    }

    export default Products
    ```

  </CodeTab>
</CodeTabs>


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

<CodeTabs group="clients">
  <CodeTab label="cURL" value="curl">
    
    ```bash
    curl "http://localhost:9000/store/products?order=-created_at"
    ```

  </CodeTab>
  <CodeTab label="Medusa JS Client" value="js-client">
    
    ```ts
    import Medusa from "@medusajs/medusa-js"
    const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    medusa.products.list({
      order: "-created_at"
    })
    .then(({ products, limit, offset, count }) => {
      console.log(products.length);
    });
    ```

  </CodeTab>
  <CodeTab label="Medusa React" value="medusa-react">
    
    ```tsx
    import { useProducts } from "medusa-react"

    const Products = () => {
      const { products, isLoading } = useProducts({
        order: "-created_at"
      })

      return (
        <div>
          {/* ... */}
        </div>
      )
    }

    export default Products
    ```

  </CodeTab>
</CodeTabs>


This sorts the products by their `created_at` attribute in the descending
order.

<Feedback
  event="survey_api-ref"
  extraData={{
    area: "store",
    section: "pagination"
  }}
  reportLink={formatReportLink("store", "Pagination")}
  pathName="/api/store"
/>

</SectionContainer>