fa7c94b4cc
* docs: migrate ui docs to docs universe * created yarn workspace * added eslint and tsconfig configurations * fix eslint configurations * fixed eslint configurations * shared tailwind configurations * added shared ui package * added more shared components * migrating more components * made details components shared * move InlineCode component * moved InputText * moved Loading component * Moved Modal component * moved Select components * Moved Tooltip component * moved Search components * moved ColorMode provider * Moved Notification components and providers * used icons package * use UI colors in api-reference * moved Navbar component * used Navbar and Search in UI docs * added Feedback to UI docs * general enhancements * fix color mode * added copy colors file from ui-preset * added features and enhancements to UI docs * move Sidebar component and provider * general fixes and preparations for deployment * update docusaurus version * adjusted versions * fix output directory * remove rootDirectory property * fix yarn.lock * moved code component * added vale for all docs MD and MDX * fix tests * fix vale error * fix deployment errors * change ignore commands * add output directory * fix docs test * general fixes * content fixes * fix announcement script * added changeset * fix vale checks * added nofilter option * fix vale error
1218 lines
26 KiB
Plaintext
1218 lines
26 KiB
Plaintext
import { Feedback, CodeTabs } from "docs-ui"
|
|
import SectionContainer from "@/components/Section/Container"
|
|
import formatReportLink from "@/utils/format-report-link"
|
|
|
|
<SectionContainer noTopPadding={true}>
|
|
|
|
This API reference includes Medusa's Admin APIs, which are REST APIs exposed by the Medusa backend. They are typically used to perform admin functionalities or create an admin dashboard to access and manipulate your commerce store's data.
|
|
|
|
All endpoints are prefixed with `/admin`. So, during development, the endpoints will be available under the path `http://localhost:9000/admin`. For production, replace `http://localhost:9000` with your Medusa backend URL.
|
|
|
|
There are different ways you can send requests to these endpoints, 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: "admin",
|
|
section: "introduction"
|
|
}}
|
|
reportLink={formatReportLink("admin", "Introduction")}
|
|
pathName="/api/admin"
|
|
/>
|
|
|
|
</SectionContainer>
|
|
|
|
<SectionContainer noTopPadding={true}>
|
|
|
|
## Authentication
|
|
|
|
There are two ways to send authenticated requests to the Medusa server: Using a user's API token, or using a Cookie Session ID.
|
|
|
|
### API Token
|
|
|
|
Use a user's API Token to send authenticated requests.
|
|
|
|
#### How to Add API Token to a User
|
|
|
|
You can use the Update User endpoint to add or update the user's API token:
|
|
|
|
<CodeTabs
|
|
tabs={[
|
|
{
|
|
label: 'Medusa JS Client',
|
|
value: 'js-client',
|
|
code: {
|
|
source: `import Medusa from "@medusajs/medusa-js"
|
|
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
|
|
// must be previously logged in or use api token
|
|
medusa.admin.users.update(userId, {
|
|
api_token
|
|
})
|
|
.then(({ user }) => {
|
|
console.log(user.api_token)
|
|
})`,
|
|
lang: `ts`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa React',
|
|
value: 'medusa-react',
|
|
code: {
|
|
source: `import { useAdminUpdateUser } from "medusa-react"
|
|
|
|
const UpdateUser = () => {
|
|
const updateUser = useAdminUpdateUser(userId)
|
|
// ...
|
|
|
|
const handleUpdateUser = () => {
|
|
updateUser.mutate({
|
|
api_token
|
|
})
|
|
}
|
|
|
|
// ...
|
|
}
|
|
|
|
export default UpdateUser`,
|
|
lang: `tsx`,
|
|
}
|
|
},
|
|
{
|
|
label: 'cURL',
|
|
value: 'curl',
|
|
code: {
|
|
source: `curl -L -X POST '<BACKEND_URL>/admin/users/<USER_ID>' \\
|
|
-H 'Cookie: connect.sid={sid}' \\
|
|
-H 'Content-Type: application/json' \\
|
|
--data-raw '{
|
|
"api_token": "{api_token}"
|
|
}'`,
|
|
lang: `bash`,
|
|
}
|
|
}
|
|
]}
|
|
/>
|
|
|
|
|
|
#### How to Use the API Token
|
|
|
|
|
|
The API token can be used for Bearer Authentication. It's passed in the
|
|
`Authorization` header as the following:
|
|
|
|
|
|
```bash
|
|
Authorization: Bearer {api_token}
|
|
```
|
|
|
|
You can also pass it to client libraries:
|
|
|
|
<CodeTabs
|
|
tabs={[
|
|
{
|
|
label: 'Medusa JS Client',
|
|
value: 'js-client',
|
|
code: {
|
|
source: `const medusa = new Medusa({
|
|
baseUrl: MEDUSA_BACKEND_URL,
|
|
maxRetries: 3,
|
|
apiKey: '{api_token}'
|
|
})`,
|
|
lang: `ts`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa React',
|
|
value: 'medusa-react',
|
|
code: {
|
|
source: `<MedusaProvider
|
|
apiKey='{api_token}'
|
|
//...
|
|
>
|
|
{/* ... */}
|
|
</MedusaProvider>`,
|
|
lang: `tsx`,
|
|
}
|
|
}
|
|
]}
|
|
/>
|
|
|
|
<Feedback
|
|
event="survey_api-ref"
|
|
extraData={{
|
|
area: "admin",
|
|
section: "authentication-api-key"
|
|
}}
|
|
className="mb-3"
|
|
reportLink={formatReportLink("admin", "Authentication - API Token")}
|
|
pathName="/api/admin"
|
|
/>
|
|
|
|
### 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 admin user 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
|
|
user](#tag/Auth/operation/PostAuth) and pass the cURL option `-v`:
|
|
|
|
|
|
```bash
|
|
curl -v -X POST 'https://medusa-url.com/admin/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/admin/products' \
|
|
-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: "admin",
|
|
section: "authentication-cookie"
|
|
}}
|
|
reportLink={formatReportLink("admin", "Authentication - Cookie Session ID")}
|
|
pathName="/api/admin"
|
|
/>
|
|
|
|
</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: "admin",
|
|
section: "http-compression"
|
|
}}
|
|
reportLink={formatReportLink("admin", "Authentication - Cookie Session ID")}
|
|
pathName="/api/admin"
|
|
/>
|
|
|
|
</SectionContainer>
|
|
|
|
<SectionContainer noTopPadding={true}>
|
|
|
|
## 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 products, you can retrieve their collection
|
|
by passing to the `expand` query parameter the value `collection`:
|
|
|
|
<CodeTabs
|
|
tabs={[
|
|
{
|
|
label: 'cURL',
|
|
value: 'curl',
|
|
code: {
|
|
source: `curl "http://localhost:9000/admin/products?expand=collection" \
|
|
-H 'Authorization: Bearer {api_token}'`,
|
|
lang: `bash`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa JS Client',
|
|
value: 'js-client',
|
|
code: {
|
|
source: `import Medusa from "@medusajs/medusa-js"
|
|
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
|
|
// must be previously logged in or use api token
|
|
medusa.admin.products.list({
|
|
expand: "collection"
|
|
})
|
|
.then(({ products, limit, offset, count }) => {
|
|
console.log(products.length);
|
|
});`,
|
|
lang: `ts`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa React',
|
|
value: 'medusa-react',
|
|
code: {
|
|
source: `import { useAdminProducts } from "medusa-react"
|
|
|
|
const Products = () => {
|
|
const { products, isLoading } = useAdminProducts({
|
|
expand: "collection"
|
|
})
|
|
|
|
return (
|
|
<div>
|
|
{/** ... **/}
|
|
</div>
|
|
)
|
|
}
|
|
|
|
export default Products`,
|
|
lang: `tsx`,
|
|
}
|
|
}
|
|
]}
|
|
/>
|
|
|
|
|
|
### 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 products,
|
|
pass to the `expand` query parameter the value `variants,collection`:
|
|
|
|
<CodeTabs
|
|
tabs={[
|
|
{
|
|
label: 'cURL',
|
|
value: 'curl',
|
|
code: {
|
|
source: `curl "http://localhost:9000/admin/products?expand=variants,collection" \
|
|
-H 'Authorization: Bearer {api_token}'`,
|
|
lang: `bash`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa JS Client',
|
|
value: 'js-client',
|
|
code: {
|
|
source: `import Medusa from "@medusajs/medusa-js"
|
|
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
|
|
// must be previously logged in or use api token
|
|
medusa.admin.products.list({
|
|
expand: "variants,collection"
|
|
})
|
|
.then(({ products, limit, offset, count }) => {
|
|
console.log(products.length);
|
|
});`,
|
|
lang: `ts`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa React',
|
|
value: 'medusa-react',
|
|
code: {
|
|
source: `import { useAdminProducts } from "medusa-react"
|
|
|
|
const Products = () => {
|
|
const { products, isLoading } = useAdminProducts({
|
|
expand: "variants,collection"
|
|
})
|
|
|
|
return (
|
|
<div>
|
|
{/** ... **/}
|
|
</div>
|
|
)
|
|
}
|
|
|
|
export default Products`,
|
|
lang: `tsx`,
|
|
}
|
|
}
|
|
]}
|
|
/>
|
|
|
|
|
|
### 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
|
|
tabs={[
|
|
{
|
|
label: 'cURL',
|
|
value: 'curl',
|
|
code: {
|
|
source: `curl "http://localhost:9000/admin/products?expand" \
|
|
-H 'Authorization: Bearer {api_token}'`,
|
|
lang: `bash`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa JS Client',
|
|
value: 'js-client',
|
|
code: {
|
|
source: `import Medusa from "@medusajs/medusa-js"
|
|
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
|
|
// must be previously logged in or use api token
|
|
medusa.admin.products.list({
|
|
expand: ""
|
|
})
|
|
.then(({ products, limit, offset, count }) => {
|
|
console.log(products.length);
|
|
});`,
|
|
lang: `ts`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa React',
|
|
value: 'medusa-react',
|
|
code: {
|
|
source: `import { useAdminProducts } from "medusa-react"
|
|
|
|
const Products = () => {
|
|
const { products, isLoading } = useAdminProducts({
|
|
expand: ""
|
|
})
|
|
|
|
return (
|
|
<div>
|
|
{/** ... **/}
|
|
</div>
|
|
)
|
|
}
|
|
|
|
export default Products`,
|
|
lang: `tsx`,
|
|
}
|
|
}
|
|
]}
|
|
/>
|
|
|
|
|
|
This would retrieve each product with only its properties, without any
|
|
relations like `collection`.
|
|
|
|
<Feedback
|
|
event="survey_api-ref"
|
|
extraData={{
|
|
area: "admin",
|
|
section: "expand"
|
|
}}
|
|
reportLink={formatReportLink("admin", "Expanding Fields")}
|
|
pathName="/api/admin"
|
|
/>
|
|
|
|
</SectionContainer>
|
|
|
|
<SectionContainer noTopPadding={true}>
|
|
|
|
## 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:
|
|
|
|
<CodeTabs
|
|
tabs={[
|
|
{
|
|
label: 'cURL',
|
|
value: 'curl',
|
|
code: {
|
|
source: `curl "http://localhost:9000/admin/products?fields=title" \
|
|
-H 'Authorization: Bearer {api_token}'`,
|
|
lang: `bash`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa JS Client',
|
|
value: 'js-client',
|
|
code: {
|
|
source: `import Medusa from "@medusajs/medusa-js"
|
|
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
|
|
// must be previously logged in or use api token
|
|
medusa.admin.products.list({
|
|
fields: "title"
|
|
})
|
|
.then(({ products, limit, offset, count }) => {
|
|
console.log(products.length);
|
|
});`,
|
|
lang: `ts`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa React',
|
|
value: 'medusa-react',
|
|
code: {
|
|
source: `import { useAdminProducts } from "medusa-react"
|
|
|
|
const Products = () => {
|
|
const { products, isLoading } = useAdminProducts({
|
|
fields: "title"
|
|
})
|
|
|
|
return (
|
|
<div>
|
|
{/** ... **/}
|
|
</div>
|
|
)
|
|
}
|
|
|
|
export default Products`,
|
|
lang: `tsx`,
|
|
}
|
|
}
|
|
]}
|
|
/>
|
|
|
|
|
|
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
|
|
tabs={[
|
|
{
|
|
label: 'cURL',
|
|
value: 'curl',
|
|
code: {
|
|
source: `curl "http://localhost:9000/admin/products?fields=title&expand" \
|
|
-H 'Authorization: Bearer {api_token}'`,
|
|
lang: `bash`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa JS Client',
|
|
value: 'js-client',
|
|
code: {
|
|
source: `import Medusa from "@medusajs/medusa-js"
|
|
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
|
|
// must be previously logged in or use api token
|
|
medusa.admin.products.list({
|
|
fields: "title",
|
|
expand: ""
|
|
})
|
|
.then(({ products, limit, offset, count }) => {
|
|
console.log(products.length);
|
|
});`,
|
|
lang: `ts`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa React',
|
|
value: 'medusa-react',
|
|
code: {
|
|
source: `import { useAdminProducts } from "medusa-react"
|
|
|
|
const Products = () => {
|
|
const { products, isLoading } = useAdminProducts({
|
|
fields: "title",
|
|
expand: ""
|
|
})
|
|
|
|
return (
|
|
<div>
|
|
{/** ... **/}
|
|
</div>
|
|
)
|
|
}
|
|
|
|
export default Products`,
|
|
lang: `tsx`,
|
|
}
|
|
}
|
|
]}
|
|
/>
|
|
|
|
|
|
### 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 products:
|
|
|
|
<CodeTabs
|
|
tabs={[
|
|
{
|
|
label: 'cURL',
|
|
value: 'curl',
|
|
code: {
|
|
source: `curl "http://localhost:9000/admin/products?fields=title,handle" \
|
|
-H 'Authorization: Bearer {api_token}'`,
|
|
lang: `bash`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa JS Client',
|
|
value: 'js-client',
|
|
code: {
|
|
source: `import Medusa from "@medusajs/medusa-js"
|
|
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
|
|
// must be previously logged in or use api token
|
|
medusa.admin.products.list({
|
|
fields: "title,handle"
|
|
})
|
|
.then(({ products, limit, offset, count }) => {
|
|
console.log(products.length);
|
|
});`,
|
|
lang: `ts`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa React',
|
|
value: 'medusa-react',
|
|
code: {
|
|
source: `import { useAdminProducts } from "medusa-react"
|
|
|
|
const Products = () => {
|
|
const { products, isLoading } = useAdminProducts({
|
|
fields: "title,handle"
|
|
})
|
|
|
|
return (
|
|
<div>
|
|
{/** ... **/}
|
|
</div>
|
|
)
|
|
}
|
|
|
|
export default Products`,
|
|
lang: `tsx`,
|
|
}
|
|
}
|
|
]}
|
|
/>
|
|
|
|
|
|
### Retrieve Only the ID
|
|
|
|
|
|
You can pass an empty `fields` query parameter to return only the ID of an
|
|
entity. For example:
|
|
|
|
<CodeTabs
|
|
tabs={[
|
|
{
|
|
label: 'cURL',
|
|
value: 'curl',
|
|
code: {
|
|
source: `curl "http://localhost:9000/admin/products?fields" \
|
|
-H 'Authorization: Bearer {api_token}'`,
|
|
lang: `bash`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa JS Client',
|
|
value: 'js-client',
|
|
code: {
|
|
source: `import Medusa from "@medusajs/medusa-js"
|
|
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
|
|
// must be previously logged in or use api token
|
|
medusa.admin.products.list({
|
|
fields: ""
|
|
})
|
|
.then(({ products, limit, offset, count }) => {
|
|
console.log(products.length);
|
|
});`,
|
|
lang: `ts`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa React',
|
|
value: 'medusa-react',
|
|
code: {
|
|
source: `import { useAdminProducts } from "medusa-react"
|
|
|
|
const Products = () => {
|
|
const { products, isLoading } = useAdminProducts({
|
|
fields: ""
|
|
})
|
|
|
|
return (
|
|
<div>
|
|
{/** ... **/}
|
|
</div>
|
|
)
|
|
}
|
|
|
|
export default Products`,
|
|
lang: `tsx`,
|
|
}
|
|
}
|
|
]}
|
|
/>
|
|
|
|
|
|
You can also pair with an empty `expand` query parameter to ensure that the
|
|
relations aren't retrieved as well. For example:
|
|
|
|
<CodeTabs
|
|
tabs={[
|
|
{
|
|
label: 'cURL',
|
|
value: 'curl',
|
|
code: {
|
|
source: `curl "http://localhost:9000/admin/products?fields&expand" \
|
|
-H 'Authorization: Bearer {api_token}'`,
|
|
lang: `bash`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa JS Client',
|
|
value: 'js-client',
|
|
code: {
|
|
source: `import Medusa from "@medusajs/medusa-js"
|
|
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
|
|
// must be previously logged in or use api token
|
|
medusa.admin.products.list({
|
|
fields: "",
|
|
expand: ""
|
|
})
|
|
.then(({ products, limit, offset, count }) => {
|
|
console.log(products.length);
|
|
});`,
|
|
lang: `ts`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa React',
|
|
value: 'medusa-react',
|
|
code: {
|
|
source: `import { useAdminProducts } from "medusa-react"
|
|
|
|
const Products = () => {
|
|
const { products, isLoading } = useAdminProducts({
|
|
fields: "",
|
|
expand: ""
|
|
})
|
|
|
|
return (
|
|
<div>
|
|
{/** ... **/}
|
|
</div>
|
|
)
|
|
}
|
|
|
|
export default Products`,
|
|
lang: `tsx`,
|
|
}
|
|
}
|
|
]}
|
|
/>
|
|
|
|
<Feedback
|
|
event="survey_api-ref"
|
|
extraData={{
|
|
area: "admin",
|
|
section: "select-fields"
|
|
}}
|
|
reportLink={formatReportLink("admin", "Selecting Fields")}
|
|
pathName="/api/admin"
|
|
/>
|
|
|
|
</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 endpoints and not using
|
|
the 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/admin/products?title=Shirt" \
|
|
-H 'Authorization: Bearer {api_token}'
|
|
```
|
|
|
|
|
|
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/admin/products?title=Blue%20Shirt" \
|
|
-H 'Authorization: Bearer {api_token}'
|
|
```
|
|
|
|
|
|
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/admin/products?offset=1" \
|
|
-H 'Authorization: Bearer {api_token}'
|
|
```
|
|
|
|
|
|
### Boolean
|
|
|
|
|
|
You can pass a boolean value in the form of `<parameter_name>=<value>`.
|
|
|
|
|
|
For example:
|
|
|
|
|
|
```bash
|
|
curl "http://localhost:9000/admin/products?is_giftcard=true" \
|
|
-H 'Authorization: Bearer {api_token}'
|
|
```
|
|
|
|
|
|
### 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/admin/products?created_at[lt]=2023-02-17" \
|
|
-H 'Authorization: Bearer {api_token}'
|
|
```
|
|
|
|
|
|
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/admin/products?created_at[lt]=2023-02-17T07:22:30Z" \
|
|
-H 'Authorization: Bearer {api_token}'
|
|
```
|
|
|
|
|
|
### 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/admin/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7" \
|
|
-H 'Authorization: Bearer {api_token}'
|
|
```
|
|
|
|
|
|
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/admin/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17" \
|
|
-H 'Authorization: Bearer {api_token}'
|
|
```
|
|
|
|
<Feedback
|
|
event="survey_api-ref"
|
|
extraData={{
|
|
area: "admin",
|
|
section: "query-parameters"
|
|
}}
|
|
reportLink={formatReportLink("admin", "Query Parameter Types")}
|
|
pathName="/api/admin"
|
|
/>
|
|
|
|
</SectionContainer>
|
|
|
|
<SectionContainer noTopPadding={true}>
|
|
|
|
## 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:
|
|
|
|
<CodeTabs
|
|
tabs={[
|
|
{
|
|
label: 'cURL',
|
|
value: 'curl',
|
|
code: {
|
|
source: `curl "http://localhost:9000/admin/products?limit=5" \
|
|
-H 'Authorization: Bearer {api_token}'`,
|
|
lang: `bash`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa JS Client',
|
|
value: 'js-client',
|
|
code: {
|
|
source: `import Medusa from "@medusajs/medusa-js"
|
|
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
|
|
// must be previously logged in or use api token
|
|
medusa.admin.products.list({
|
|
limit: 5
|
|
})
|
|
.then(({ products, limit, offset, count }) => {
|
|
console.log(products.length);
|
|
});`,
|
|
lang: `ts`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa React',
|
|
value: 'medusa-react',
|
|
code: {
|
|
source: `import { useAdminProducts } from "medusa-react"
|
|
|
|
const Products = () => {
|
|
const { products, isLoading } = useAdminProducts({
|
|
limit: 5
|
|
})
|
|
|
|
return (
|
|
<div>
|
|
{/** ... **/}
|
|
</div>
|
|
)
|
|
}
|
|
|
|
export default Products`,
|
|
lang: `tsx`,
|
|
}
|
|
}
|
|
]}
|
|
/>
|
|
|
|
|
|
### 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`:
|
|
|
|
<CodeTabs
|
|
tabs={[
|
|
{
|
|
label: 'cURL',
|
|
value: 'curl',
|
|
code: {
|
|
source: `curl "http://localhost:9000/admin/products?order=created_at" \
|
|
-H 'Authorization: Bearer {api_token}'`,
|
|
lang: `bash`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa JS Client',
|
|
value: 'js-client',
|
|
code: {
|
|
source: `import Medusa from "@medusajs/medusa-js"
|
|
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
|
|
// must be previously logged in or use api token
|
|
medusa.admin.products.list({
|
|
order: "created_at"
|
|
})
|
|
.then(({ products, limit, offset, count }) => {
|
|
console.log(products.length);
|
|
});`,
|
|
lang: `ts`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa React',
|
|
value: 'medusa-react',
|
|
code: {
|
|
source: `import { useAdminProducts } from "medusa-react"
|
|
|
|
const Products = () => {
|
|
const { products, isLoading } = useAdminProducts({
|
|
order: "created_at"
|
|
})
|
|
|
|
return (
|
|
<div>
|
|
{/** ... **/}
|
|
</div>
|
|
)
|
|
}
|
|
|
|
export default Products`,
|
|
lang: `tsx`,
|
|
}
|
|
}
|
|
]}
|
|
/>
|
|
|
|
|
|
By default, the sort direction will be ascending. To change it to
|
|
descending, pass a dash (`-`) before the attribute name. For example:
|
|
|
|
<CodeTabs
|
|
tabs={[
|
|
{
|
|
label: 'cURL',
|
|
value: 'curl',
|
|
code: {
|
|
source: `curl "http://localhost:9000/admin/products?order=-created_at" \
|
|
-H 'Authorization: Bearer {api_token}'`,
|
|
lang: `bash`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa JS Client',
|
|
value: 'js-client',
|
|
code: {
|
|
source: `import Medusa from "@medusajs/medusa-js"
|
|
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
|
|
// must be previously logged in or use api token
|
|
medusa.admin.products.list({
|
|
order: "-created_at"
|
|
})
|
|
.then(({ products, limit, offset, count }) => {
|
|
console.log(products.length);
|
|
});`,
|
|
lang: `ts`,
|
|
}
|
|
},
|
|
{
|
|
label: 'Medusa React',
|
|
value: 'medusa-react',
|
|
code: {
|
|
source: `import { useAdminProducts } from "medusa-react"
|
|
|
|
const Products = () => {
|
|
const { products, isLoading } = useAdminProducts({
|
|
order: "-created_at"
|
|
})
|
|
|
|
return (
|
|
<div>
|
|
{/** ... **/}
|
|
</div>
|
|
)
|
|
}
|
|
|
|
export default Products`,
|
|
lang: `tsx`,
|
|
}
|
|
}
|
|
]}
|
|
/>
|
|
|
|
|
|
This sorts the products by their `created_at` attribute in the descending
|
|
order.
|
|
|
|
<Feedback
|
|
event="survey_api-ref"
|
|
extraData={{
|
|
area: "admin",
|
|
section: "pagination"
|
|
}}
|
|
reportLink={formatReportLink("admin", "Pagination")}
|
|
pathName="/api/admin"
|
|
/>
|
|
|
|
</SectionContainer> |