openapi: 3.0.0
info:
version: 1.0.0
title: Medusa Admin 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: Apps Oauth
description: |
Some plugins may require to authenticate with third-party services and store authentication details, such as the authentication token. To do that, they can create an Oauth provider within the plugin that handles the authentication.
The Apps Oauth API Routes allows admins to manage and generate token for an app using its oauth provider.
- name: Auth
description: |
Authentication API Routes allow admin users to manage their session, such as login or log out.
When an admin user is logged in, the cookie header is set indicating the admin's login session.
externalDocs:
description: How to implement user profiles
url: https://docs.medusajs.com/modules/users/admin/manage-profile
- name: Batch Jobs
description: |
A batch job is a task that is performed by the Medusa backend asynchronusly. For example, the Import Product feature is implemented using batch jobs.
Batch Job API Routes allow admins to manage the batch jobs and their state.
externalDocs:
description: How to import products
url: https://docs.medusajs.com/modules/products/admin/import-products
- name: Currencies
description: |
A store can use unlimited currencies, and each region must be associated with at least one currency.
Currencies are defined within the Medusa backend. Currency API Routes allow admins to list and update currencies.
externalDocs:
description: How to manage currencies
url: https://docs.medusajs.com/modules/regions-and-currencies/admin/manage-currencies
- name: Customer Groups
description: |
Customer Groups can be used to organize customers that share similar data or attributes into dedicated groups.
This can be useful for different purposes such as setting a different price for a specific customer group.
externalDocs:
description: How to manage customer groups
url: https://docs.medusajs.com/modules/customers/admin/manage-customer-groups
- name: Customers
description: |
Customers can either be created when they register through the Store APIs, or created by the admin using the Admin APIs.
externalDocs:
description: How to manage customers
url: https://docs.medusajs.com/modules/customers/admin/manage-customers
- name: Discounts
description: |
Admins can create discounts with conditions and rules, providing them with advanced settings for variety of cases.
The Discount API Routes can be used to manage discounts, their conditions, resources, and more.
externalDocs:
description: How to manage discounts
url: https://docs.medusajs.com/modules/discounts/admin/manage-discounts
- name: Draft Orders
description: |
A draft order is an order created manually by the admin. It allows admins to create orders without direct involvement from the customer.
externalDocs:
description: How to manage draft orders
url: https://docs.medusajs.com/modules/orders/admin/manage-draft-orders
- name: Gift Cards
description: |
Admins can create gift cards and send them directly to customers, specifying options like their balance, region, and more.
These gift cards are different than the saleable gift cards in a store, which are created and managed through Product API Routes.
externalDocs:
description: How to manage gift cards
url: https://docs.medusajs.com/modules/gift-cards/admin/manage-gift-cards#manage-custom-gift-cards
- name: Inventory Items
description: |
Inventory items, provided by the [Inventory Module](https://docs.medusajs.com/modules/multiwarehouse/inventory-module), can be used to manage the inventory of saleable items in your store.
externalDocs:
description: How to manage inventory items
url: https://docs.medusajs.com/modules/multiwarehouse/admin/manage-inventory-items
- name: Invites
description: |
An admin can invite new users to manage their team. This would allow new users to authenticate as admins and perform admin functionalities.
externalDocs:
description: How to manage invites
url: https://docs.medusajs.com/modules/users/admin/manage-invites
- name: Notes
description: |
Notes are created by admins and can be associated with any resource. For example, an admin can add a note to an order for additional details or remarks.
- name: Notifications
description: |
Notifications are sent to customers to inform them of new updates. For example, a notification can be sent to the customer when their order is place or its state is updated.
The notification's type, such as an email or SMS, is determined by the notification provider installed on the Medusa backend.
- name: Order Edits
description: |
An admin can edit an order to remove, add, or update an item's quantity. When an admin edits an order, they're stored as an `OrderEdit`.
externalDocs:
description: How to edit an order
url: https://docs.medusajs.com/modules/orders/admin/edit-order
- name: Orders
description: |
Orders are purchases made by customers, typically through a storefront using the Store API. Draft orders created by the admin are also transformed to an Order once the payment is captured.
Managing orders include managing fulfillment, payment, claims, reservations, and more.
externalDocs:
description: How to manage orders
url: https://docs.medusajs.com/modules/orders/admin/manage-orders
- name: Payment Collections
description: |
A payment collection is useful for managing additional payments, such as for Order Edits, or installment payments.
- name: Payments
description: |
A payment can be related to an order, swap, return, or more. It can be captured or refunded.
- name: Price Lists
description: |
A price list are special prices applied to products based on a set of conditions, such as customer group.
externalDocs:
description: How to manage price lists
url: https://docs.medusajs.com/modules/price-lists/admin/manage-price-lists
- name: Product Categories
description: |
Products can be categoriezed into categories. A product can be added into more than one category.
externalDocs:
description: How to manage product categories
url: https://docs.medusajs.com/modules/products/admin/manage-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.
- name: Product Tags
description: |
Product tags are string values created when you create or update a product with a new tag.
Products can have more than one tag, and products can share tags. This allows admins to associate products to similar tags that can be used to filter products.
- name: Product Types
description: |
Product types are string values created when you create or update a product with a new type.
Products can have one type, and products can share types. This allows admins to associate products with a type that can be used to filter 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.
Product variants can be managed through the Products API Routes.
externalDocs:
description: How to manage product variants
url: https://docs.medusajs.com/modules/products/admin/manage-products#manage-product-variants
- name: Products
description: |
Products are saleable items in a store. This also includes [saleable gift cards](https://docs.medusajs.com/modules/gift-cards/admin/manage-gift-cards#manage-gift-card-product) in a store.
externalDocs:
description: How to manage products
url: https://docs.medusajs.com/modules/products/admin/manage-products
- name: Publishable API Keys
description: |
Publishable API Keys can be used to scope Store API calls with an API key, determining what resources are retrieved when querying the API.
For example, a publishable API key can be associated with one or more sales channels. When it is passed in the header of a request to the List Product store API Route,
the sales channels are inferred from the key and only products associated with those sales channels are retrieved.
Admins can manage publishable API keys and their associated resources. Currently, only Sales Channels are supported as a resource.
externalDocs:
description: How to manage publishable API keys
url: https://docs.medusajs.com/development/publishable-api-keys/admin/manage-publishable-api-keys
- name: Regions
description: |
Regions are different countries or geographical regions that the commerce store serves customers in.
Admins can manage these regions, their providers, and more.
externalDocs:
description: How to manage regions
url: https://docs.medusajs.com/modules/regions-and-currencies/admin/manage-regions
- name: Reservations
description: |
Reservations, provided by the [Inventory Module](https://docs.medusajs.com/modules/multiwarehouse/inventory-module), are quantities of an item that are reserved, typically when an order is placed but not yet fulfilled.
Reservations can be associated with any resources, but commonly with line items of an order.
externalDocs:
description: How to manage item allocations in orders
url: https://docs.medusajs.com/modules/multiwarehouse/admin/manage-item-allocations-in-orders
- name: Return Reasons
description: |
Return reasons are key-value pairs that are used to specify why an order return is being created.
Admins can manage available return reasons, and they can be used by both admins and customers when creating a return.
externalDocs:
description: How to manage return reasons
url: https://docs.medusajs.com/modules/orders/admin/manage-returns#manage-return-reasons
- name: Returns
description: |
A return can be created by a customer or an admin to return items in an order.
Admins can manage these returns and change their state.
externalDocs:
description: How to manage returns
url: https://docs.medusajs.com/modules/orders/admin/manage-returns
- name: Sales Channels
description: |
A sales channel indicates a channel where products can be sold in. For example, a webshop or a mobile app.
Admins can manage sales channels and the products available in them.
externalDocs:
description: How to manage sales channels
url: https://docs.medusajs.com/modules/sales-channels/admin/manage
- name: Shipping Options
description: |
A shipping option is used to define the available shipping methods during checkout or when creating a return.
Admins can create an unlimited number of shipping options, each associated with a shipping profile and fulfillment provider, among other resources.
externalDocs:
description: Shipping Option architecture
url: https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-option
- name: Shipping Profiles
description: |
A shipping profile is used to group products that can be shipped in the same manner.
They are created by the admin and they're not associated with a fulfillment provider.
externalDocs:
description: Shipping Profile architecture
url: https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-profile
- name: Stock Locations
description: |
A stock location, provided by the [Stock Location module](https://docs.medusajs.com/modules/multiwarehouse/stock-location-module), indicates a physical address that stock-kept items, such as physical products, can be stored in.
An admin can create and manage available stock locations.
externalDocs:
description: How to manage stock locations.
url: https://docs.medusajs.com/modules/multiwarehouse/admin/manage-stock-locations
- name: Store
description: |
A store indicates the general configurations and details about the commerce store. By default, there's only one store in the Medusa backend.
Admins can manage the store and its details or configurations.
- 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 manage swaps
url: https://docs.medusajs.com/modules/orders/admin/manage-swaps
- name: Tax Rates
description: |
Each region has at least a default tax rate. Admins can create and manage additional tax rates that can be applied for certain conditions, such as for specific product types.
externalDocs:
description: How to manage tax rates
url: https://docs.medusajs.com/modules/taxes/admin/manage-tax-rates
- name: Uploads
description: |
The upload API Routes are used to upload any type of resources. For example, they can be used to upload CSV files that are used to import products into the store.
externalDocs:
description: How to upload CSV file when importing a product.
url: https://docs.medusajs.com/modules/products/admin/import-products#1-upload-csv-file
- name: Users
description: |
A store can have more than one user, each having the same privileges. Admins can manage users, their passwords, and more.
externalDocs:
description: How to manage users
url: https://docs.medusajs.com/modules/users/admin/manage-users
paths:
/admin/apps:
get:
operationId: GetApps
summary: List Applications
description: Retrieve a list of applications registered in the Medusa backend.
x-authenticated: true
x-codegen:
method: list
x-codeSamples:
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/apps' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Apps Oauth
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminAppsListRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/apps/authorizations:
post:
operationId: PostApps
summary: Generate Token for App
description: Use an app's Oauth provider to generate and store a new token for authentication.
x-authenticated: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostAppsReq'
x-codegen:
method: authorize
x-codeSamples:
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/apps/authorizations' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"application_name": "example",
"state": "ready",
"code": "token"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Apps Oauth
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminAppsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/auth:
get:
operationId: GetAuth
summary: Get Current User
x-authenticated: true
description: Get the currently logged in user's details.
x-codegen:
method: getSession
x-codeSamples:
- lang: JavaScript
label: JS Client
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.auth.getSession()
.then(({ user }) => {
console.log(user.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminGetSession } from "medusa-react"
const Profile = () => {
const { user, isLoading } = useAdminGetSession()
return (
{isLoading && Loading...}
{user && {user.email}}
)
}
export default Profile
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/auth' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Auth
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminAuthRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostAuth
summary: User Login
x-authenticated: false
description: Log a User in and includes the Cookie session in the response header. The cookie session can be used in subsequent requests to authorize the user to perform admin functionalities. When using Medusa's JS or Medusa React clients, the cookie is automatically attached to subsequent requests.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostAuthReq'
x-codegen:
method: createSession
x-codeSamples:
- lang: JavaScript
label: JS Client
source: |
import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.admin.auth.createSession({
email: "user@example.com",
password: "supersecret"
})
.then(({ user }) => {
console.log(user.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminLogin } from "medusa-react"
const Login = () => {
const adminLogin = useAdminLogin()
// ...
const handleLogin = () => {
adminLogin.mutate({
email: "user@example.com",
password: "supersecret",
}, {
onSuccess: ({ user }) => {
console.log(user)
}
})
}
// ...
}
export default Login
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/auth' \
-H 'Content-Type: application/json' \
--data-raw '{
"email": "user@example.com",
"password": "supersecret"
}'
tags:
- Auth
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminAuthRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/incorrect_credentials'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteAuth
summary: User Logout
x-authenticated: true
description: Delete the current session for the logged in user. This will only work if you're using Cookie session for authentication. If the API token is still passed in the header, the user is still authorized to perform admin functionalities in other API Routes.
x-codegen:
method: deleteSession
x-codeSamples:
- lang: JavaScript
label: JS Client
source: |
import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in
medusa.admin.auth.deleteSession()
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteSession } from "medusa-react"
const Logout = () => {
const adminLogout = useAdminDeleteSession()
// ...
const handleLogout = () => {
adminLogout.mutate(undefined, {
onSuccess: () => {
// user logged out.
}
})
}
// ...
}
export default Logout
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/auth' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Auth
responses:
'200':
description: OK
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/auth/token:
post:
operationId: PostToken
summary: User Login (JWT)
x-authenticated: false
description: After a successful login, a JWT token is returned, which can be used to send authenticated requests.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostAuthReq'
x-codegen:
method: getToken
x-codeSamples:
- lang: JavaScript
label: JS Client
source: |
import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.admin.auth.getToken({
email: 'user@example.com',
password: 'supersecret'
})
.then(({ access_token }) => {
console.log(access_token);
})
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/auth/token' \
-H 'Content-Type: application/json' \
--data-raw '{
"email": "user@example.com",
"password": "supersecret"
}'
tags:
- Auth
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminBearerAuthRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/incorrect_credentials'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/batch-jobs:
get:
operationId: GetBatchJobs
summary: List Batch Jobs
description: Retrieve a list of Batch Jobs. The batch jobs can be filtered by fields such as `type` or `confirmed_at`. The batch jobs can also be sorted or paginated.
x-authenticated: true
parameters:
- in: query
name: limit
description: Limit the number of batch jobs returned.
schema:
type: integer
default: 10
- in: query
name: offset
description: The number of batch jobs to skip when retrieving the batch jobs.
schema:
type: integer
default: 0
- in: query
name: id
style: form
explode: false
description: Filter by the batch ID
schema:
oneOf:
- type: string
description: batch job ID
- type: array
description: multiple batch job IDs
items:
type: string
- in: query
name: type
style: form
explode: false
description: Filter by the batch type
schema:
type: array
items:
type: string
- in: query
name: confirmed_at
style: form
explode: false
description: Filter by a confirmation date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: pre_processed_at
style: form
explode: false
description: Filter by a pre-processing date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: completed_at
style: form
explode: false
description: Filter by a completion date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: failed_at
style: form
explode: false
description: Filter by a failure date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: canceled_at
style: form
explode: false
description: Filter by a cancelation date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: order
description: A batch-job field to sort-order the retrieved batch jobs by.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned batch jobs.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned batch jobs.
schema:
type: string
- in: query
name: created_at
style: form
explode: false
description: Filter by a creation date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: updated_at
style: form
explode: false
description: Filter by an update date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
x-codegen:
method: list
queryParams: AdminGetBatchParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.batchJobs.list()
.then(({ batch_jobs, limit, offset, count }) => {
console.log(batch_jobs.length)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminBatchJobs } from "medusa-react"
const BatchJobs = () => {
const {
batch_jobs,
limit,
offset,
count,
isLoading
} = useAdminBatchJobs()
return (
{isLoading &&
Loading...}
{batch_jobs?.length && (
{batch_jobs.map((batchJob) => (
-
{batchJob.id}
))}
)}
{isLoading && Loading...}
{batch_job && {batch_job.created_by}}
)
}
export default BatchJob
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/batch-jobs/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Batch Jobs
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminBatchJobRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/batch-jobs/{id}/cancel:
post:
operationId: PostBatchJobsBatchJobCancel
summary: Cancel a Batch Job
description: Mark a batch job as canceled. When a batch job is canceled, the processing of the batch job doesn’t automatically stop.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the batch job.
schema:
type: string
x-codegen:
method: cancel
x-codeSamples:
- lang: JavaScript
label: JS Client
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.batchJobs.cancel(batchJobId)
.then(({ batch_job }) => {
console.log(batch_job.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCancelBatchJob } from "medusa-react"
type Props = {
batchJobId: string
}
const BatchJob = ({ batchJobId }: Props) => {
const cancelBatchJob = useAdminCancelBatchJob(batchJobId)
// ...
const handleCancel = () => {
cancelBatchJob.mutate(undefined, {
onSuccess: ({ batch_job }) => {
console.log(batch_job)
}
})
}
// ...
}
export default BatchJob
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/batch-jobs/{id}/cancel' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Batch Jobs
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminBatchJobRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/batch-jobs/{id}/confirm:
post:
operationId: PostBatchJobsBatchJobConfirmProcessing
summary: Confirm a Batch Job
description: When a batch job is created, it is not executed automatically if `dry_run` is set to `true`. This API Route confirms that the batch job should be executed.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the batch job.
schema:
type: string
x-codegen:
method: confirm
x-codeSamples:
- lang: JavaScript
label: JS Client
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.batchJobs.confirm(batchJobId)
.then(({ batch_job }) => {
console.log(batch_job.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminConfirmBatchJob } from "medusa-react"
type Props = {
batchJobId: string
}
const BatchJob = ({ batchJobId }: Props) => {
const confirmBatchJob = useAdminConfirmBatchJob(batchJobId)
// ...
const handleConfirm = () => {
confirmBatchJob.mutate(undefined, {
onSuccess: ({ batch_job }) => {
console.log(batch_job)
}
})
}
// ...
}
export default BatchJob
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/batch-jobs/{id}/confirm' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Batch Jobs
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminBatchJobRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/collections:
get:
operationId: GetCollections
summary: List Collections
description: Retrieve a list of Product Collection. The product collections can be filtered by fields such as `handle` or `title`. The collections can also be sorted or paginated.
x-authenticated: true
parameters:
- in: query
name: limit
description: The number of collections to return.
schema:
type: integer
default: 10
- in: query
name: offset
description: The number of collections to skip when retrieving the collections.
schema:
type: integer
default: 0
- in: query
name: title
description: Filter collections by their title.
schema:
type: string
- in: query
name: handle
description: Filter collections by their handle.
schema:
type: string
- in: query
name: q
description: a term to search collections by their title or handle.
schema:
type: string
- in: query
name: order
description: A field to sort-order the retrieved collections by.
schema:
type: string
- in: query
name: discount_condition_id
description: Filter collections by a discount condition ID associated with them.
schema:
type: string
- in: query
name: created_at
description: Filter by a creation date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: updated_at
description: Filter by an update date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: deleted_at
description: Filter by a deletion date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
x-codegen:
method: list
queryParams: AdminGetCollectionsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.collections.list()
.then(({ collections, limit, offset, count }) => {
console.log(collections.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCollections } from "medusa-react"
const Collections = () => {
const { collections, isLoading } = useAdminCollections()
return (
{isLoading &&
Loading...}
{collections && !collections.length &&
No Product Collections
}
{collections && collections.length > 0 && (
{collections.map((collection) => (
- {collection.title}
))}
)}
{isLoading && Loading...}
{collection && {collection.title}}
)
}
export default Collection
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/collections/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Product Collections
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminCollectionsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostCollectionsCollection
summary: Update a Collection
description: Update a Product Collection's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Collection.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostCollectionsCollectionReq'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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.collections.update(collectionId, {
title: "New Collection"
})
.then(({ collection }) => {
console.log(collection.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateCollection } from "medusa-react"
type Props = {
collectionId: string
}
const Collection = ({ collectionId }: Props) => {
const updateCollection = useAdminUpdateCollection(collectionId)
// ...
const handleUpdate = (title: string) => {
updateCollection.mutate({
title
}, {
onSuccess: ({ collection }) => {
console.log(collection.id)
}
})
}
// ...
}
export default Collection
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/collections/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"title": "New Collection"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Product Collections
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminCollectionsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteCollectionsCollection
summary: Delete a Collection
description: Delete a Product Collection. This does not delete associated products.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Collection.
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.collections.delete(collectionId)
.then(({ id, object, deleted }) => {
console.log(id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteCollection } from "medusa-react"
type Props = {
collectionId: string
}
const Collection = ({ collectionId }: Props) => {
const deleteCollection = useAdminDeleteCollection(collectionId)
// ...
const handleDelete = (title: string) => {
deleteCollection.mutate(void 0, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
// ...
}
export default Collection
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/collections/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Product Collections
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminCollectionsDeleteRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/collections/{id}/products/batch:
post:
operationId: PostProductsToCollection
summary: Add Products to Collection
description: Add products to a product collection.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the product collection.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostProductsToCollectionReq'
x-codegen:
method: addProducts
x-codeSamples:
- lang: JavaScript
label: JS Client
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.collections.addProducts(collectionId, {
product_ids: [
productId1,
productId2
]
})
.then(({ collection }) => {
console.log(collection.products)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminAddProductsToCollection } from "medusa-react"
type Props = {
collectionId: string
}
const Collection = ({ collectionId }: Props) => {
const addProducts = useAdminAddProductsToCollection(collectionId)
// ...
const handleAddProducts = (productIds: string[]) => {
addProducts.mutate({
product_ids: productIds
}, {
onSuccess: ({ collection }) => {
console.log(collection.products)
}
})
}
// ...
}
export default Collection
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/collections/{id}/products/batch' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"product_ids": [
"prod_01G1G5V2MBA328390B5AXJ610F"
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Product Collections
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminCollectionsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteProductsFromCollection
summary: Remove Products from Collection
description: Remove a list of products from a collection. This would not delete the product, only the association between the product and the collection.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Product Collection.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDeleteProductsFromCollectionReq'
x-codegen:
method: removeProducts
x-codeSamples:
- lang: JavaScript
label: JS Client
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.collections.removeProducts(collectionId, {
product_ids: [
productId1,
productId2
]
})
.then(({ id, object, removed_products }) => {
console.log(removed_products)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminRemoveProductsFromCollection } from "medusa-react"
type Props = {
collectionId: string
}
const Collection = ({ collectionId }: Props) => {
const removeProducts = useAdminRemoveProductsFromCollection(collectionId)
// ...
const handleRemoveProducts = (productIds: string[]) => {
removeProducts.mutate({
product_ids: productIds
}, {
onSuccess: ({ id, object, removed_products }) => {
console.log(removed_products)
}
})
}
// ...
}
export default Collection
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/collections/{id}/products/batch' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"product_ids": [
"prod_01G1G5V2MBA328390B5AXJ610F"
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Product Collections
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDeleteProductsFromCollectionRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/currencies:
get:
operationId: GetCurrencies
summary: List Currency
description: Retrieve a list of currencies. The currencies can be filtered by fields such as `code`. The currencies can also be sorted or paginated.
x-authenticated: true
parameters:
- in: query
name: code
description: filter by currency code.
schema:
type: string
- in: query
name: includes_tax
description: filter currencies by whether they include taxes or not.
schema:
type: boolean
x-featureFlag: tax_inclusive_pricing
- in: query
name: order
description: A field to sort order the retrieved currencies by.
schema:
type: string
- in: query
name: q
description: Term used to search currencies' name and code.
schema:
type: string
- in: query
name: offset
description: The number of currencies to skip when retrieving the currencies.
schema:
type: number
default: '0'
- in: query
name: limit
description: The number of currencies to return.
schema:
type: number
default: '20'
x-codegen:
method: list
queryParams: AdminGetCurrenciesParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.currencies.list()
.then(({ currencies, count, offset, limit }) => {
console.log(currencies.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCurrencies } from "medusa-react"
const Currencies = () => {
const { currencies, isLoading } = useAdminCurrencies()
return (
{isLoading &&
Loading...}
{currencies && !currencies.length && (
No Currencies
)}
{currencies && currencies.length > 0 && (
{currencies.map((currency) => (
- {currency.name}
))}
)}
{isLoading &&
Loading...}
{customer_groups && !customer_groups.length && (
No Customer Groups
)}
{customer_groups && customer_groups.length > 0 && (
{customer_groups.map(
(customerGroup) => (
-
{customerGroup.name}
)
)}
)}
{isLoading && Loading...}
{customer_group && {customer_group.name}}
)
}
export default CustomerGroup
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/customer-groups/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Customer Groups
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminCustomerGroupsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostCustomerGroupsGroup
summary: Update a Customer Group
description: Update a Customer Group's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the customer group.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostCustomerGroupsGroupReq'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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.customerGroups.update(customerGroupId, {
name: "VIP"
})
.then(({ customer_group }) => {
console.log(customer_group.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateCustomerGroup } from "medusa-react"
type Props = {
customerGroupId: string
}
const CustomerGroup = ({ customerGroupId }: Props) => {
const updateCustomerGroup = useAdminUpdateCustomerGroup(
customerGroupId
)
// ..
const handleUpdate = (name: string) => {
updateCustomerGroup.mutate({
name,
})
}
// ...
}
export default CustomerGroup
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/customer-groups/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"name": "VIP"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Customer Groups
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminCustomerGroupsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteCustomerGroupsCustomerGroup
summary: Delete a Customer Group
description: Delete a customer group. This doesn't delete the customers associated with the customer group.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Customer Group
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.customerGroups.delete(customerGroupId)
.then(({ id, object, deleted }) => {
console.log(id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteCustomerGroup } from "medusa-react"
type Props = {
customerGroupId: string
}
const CustomerGroup = ({ customerGroupId }: Props) => {
const deleteCustomerGroup = useAdminDeleteCustomerGroup(
customerGroupId
)
// ...
const handleDeleteCustomerGroup = () => {
deleteCustomerGroup.mutate()
}
// ...
}
export default CustomerGroup
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/customer-groups/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Customer Groups
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminCustomerGroupsDeleteRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/customer-groups/{id}/customers:
get:
operationId: GetCustomerGroupsGroupCustomers
summary: List Customers
description: Retrieve a list of customers in a customer group. The customers can be filtered by the `q` field. The customers can also be paginated.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the customer group.
schema:
type: string
- in: query
name: limit
description: The number of customers to return.
schema:
type: integer
default: 50
- in: query
name: offset
description: The number of customers to skip when retrieving the customers.
schema:
type: integer
default: 0
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned customers.
schema:
type: string
- in: query
name: q
description: a term to search customers by email, first_name, and last_name.
schema:
type: string
x-codegen:
method: listCustomers
queryParams: AdminGetGroupsGroupCustomersParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.customerGroups.listCustomers(customerGroupId)
.then(({ customers }) => {
console.log(customers.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCustomerGroupCustomers } from "medusa-react"
type Props = {
customerGroupId: string
}
const CustomerGroup = ({ customerGroupId }: Props) => {
const {
customers,
isLoading,
} = useAdminCustomerGroupCustomers(
customerGroupId
)
return (
{isLoading &&
Loading...}
{customers && !customers.length && (
No customers
)}
{customers && customers.length > 0 && (
{customers.map((customer) => (
- {customer.first_name}
))}
)}
{isLoading &&
Loading...}
{customers && !customers.length && (
No customers
)}
{customers && customers.length > 0 && (
{customers.map((customer) => (
- {customer.first_name}
))}
)}
{isLoading && Loading...}
{customer && {customer.first_name}}
)
}
export default Customer
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/customers/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Customers
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminCustomersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostCustomersCustomer
summary: Update a Customer
description: Update a Customer's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Customer.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned customer.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be retrieved in the returned customer.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostCustomersCustomerReq'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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.customers.update(customerId, {
first_name: "Dolly"
})
.then(({ customer }) => {
console.log(customer.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateCustomer } from "medusa-react"
type CustomerData = {
first_name: string
last_name: string
email: string
password: string
}
type Props = {
customerId: string
}
const Customer = ({ customerId }: Props) => {
const updateCustomer = useAdminUpdateCustomer(customerId)
// ...
const handleUpdate = (customerData: CustomerData) => {
updateCustomer.mutate(customerData)
}
// ...
}
export default Customer
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/customers/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"first_name": "Dolly"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Customers
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminCustomersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/discounts:
get:
operationId: GetDiscounts
summary: List Discounts
x-authenticated: true
description: Retrieve a list of Discounts. The discounts can be filtered by fields such as `rule` or `is_dynamic`. The discounts can also be paginated.
parameters:
- in: query
name: q
description: term to search discounts' code field.
schema:
type: string
- in: query
name: rule
description: Filter discounts by rule fields.
schema:
type: object
properties:
type:
type: string
enum:
- fixed
- percentage
- free_shipping
description: Filter discounts by type.
allocation:
type: string
enum:
- total
- item
description: Filter discounts by allocation type.
- in: query
name: is_dynamic
description: Filter discounts by whether they're dynamic or not.
schema:
type: boolean
- in: query
name: is_disabled
description: Filter discounts by whether they're disabled or not.
schema:
type: boolean
- in: query
name: limit
description: The number of discounts to return
schema:
type: number
default: '20'
- in: query
name: offset
description: The number of discounts to skip when retrieving the discounts.
schema:
type: number
default: '0'
- in: query
name: expand
description: Comma-separated relations that should be expanded in each returned discount.
schema:
type: string
- in: query
name: order
description: A discount field to sort-order the retrieved discounts by.
schema:
type: string
- in: query
name: created_at
description: Filter by a creation date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: updated_at
description: Filter by an update date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
x-codegen:
method: list
queryParams: AdminGetDiscountsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.discounts.list()
.then(({ discounts, limit, offset, count }) => {
console.log(discounts.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDiscounts } from "medusa-react"
const Discounts = () => {
const { discounts, isLoading } = useAdminDiscounts()
return (
{isLoading &&
Loading...}
{discounts && !discounts.length && (
No customers
)}
{discounts && discounts.length > 0 && (
{discounts.map((discount) => (
- {discount.code}
))}
)}
{isLoading && Loading...}
{discount && {discount.code}}
)
}
export default Discount
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/discounts/code/{code}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Discounts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDiscountsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/discounts/{discount_id}/conditions:
post:
operationId: PostDiscountsDiscountConditions
summary: Create a Condition
description: Create a Discount Condition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided, based on the type of discount condition. For example, if the discount condition's type is `products`, the `products` field should be provided in the request body.
x-authenticated: true
parameters:
- in: path
name: discount_id
required: true
description: The ID of the discount.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned discount.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned discount.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostDiscountsDiscountConditions'
x-codegen:
method: createCondition
queryParams: AdminPostDiscountsDiscountConditionsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
source: |
import Medusa from "@medusajs/medusa-js"
import { DiscountConditionOperator } from "@medusajs/medusa"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.discounts.createCondition(discountId, {
operator: DiscountConditionOperator.IN,
products: [productId]
})
.then(({ discount }) => {
console.log(discount.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { DiscountConditionOperator } from "@medusajs/medusa"
import { useAdminDiscountCreateCondition } from "medusa-react"
type Props = {
discountId: string
}
const Discount = ({ discountId }: Props) => {
const createCondition = useAdminDiscountCreateCondition(discountId)
// ...
const handleCreateCondition = (
operator: DiscountConditionOperator,
products: string[]
) => {
createCondition.mutate({
operator,
products
}, {
onSuccess: ({ discount }) => {
console.log(discount.id)
}
})
}
// ...
}
export default Discount
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/discounts/{id}/conditions' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"operator": "in"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Discounts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDiscountsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/discounts/{discount_id}/conditions/{condition_id}:
get:
operationId: GetDiscountsDiscountConditionsCondition
summary: Get a Condition
description: Retrieve a Discount Condition's details.
x-authenticated: true
parameters:
- in: path
name: discount_id
required: true
description: The ID of the Discount.
schema:
type: string
- in: path
name: condition_id
required: true
description: The ID of the Discount Condition.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned discount condition.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned discount condition.
schema:
type: string
x-codegen:
method: getCondition
queryParams: AdminGetDiscountsDiscountConditionsConditionParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.discounts.getCondition(discountId, conditionId)
.then(({ discount_condition }) => {
console.log(discount_condition.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminGetDiscountCondition } from "medusa-react"
type Props = {
discountId: string
discountConditionId: string
}
const DiscountCondition = ({
discountId,
discountConditionId
}: Props) => {
const {
discount_condition,
isLoading
} = useAdminGetDiscountCondition(
discountId,
discountConditionId
)
return (
{isLoading && Loading...}
{discount_condition && (
{discount_condition.type}
)}
)
}
export default DiscountCondition
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/discounts/{id}/conditions/{condition_id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Discounts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDiscountConditionsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostDiscountsDiscountConditionsCondition
summary: Update a Condition
description: Update a Discount Condition. Only one of `products`, `product_types`, `product_collections`, `product_tags`, and `customer_groups` should be provided, based on the type of discount condition. For example, if the discount condition's type is `products`, the `products` field should be provided in the request body.
x-authenticated: true
parameters:
- in: path
name: discount_id
required: true
description: The ID of the Discount.
schema:
type: string
- in: path
name: condition_id
required: true
description: The ID of the Discount Condition.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned discount.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned discount.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostDiscountsDiscountConditionsCondition'
x-codegen:
method: updateCondition
queryParams: AdminPostDiscountsDiscountConditionsConditionParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.discounts.updateCondition(discountId, conditionId, {
products: [
productId
]
})
.then(({ discount }) => {
console.log(discount.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDiscountUpdateCondition } from "medusa-react"
type Props = {
discountId: string
conditionId: string
}
const DiscountCondition = ({
discountId,
conditionId
}: Props) => {
const update = useAdminDiscountUpdateCondition(
discountId,
conditionId
)
// ...
const handleUpdate = (
products: string[]
) => {
update.mutate({
products
}, {
onSuccess: ({ discount }) => {
console.log(discount.id)
}
})
}
// ...
}
export default DiscountCondition
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/discounts/{id}/conditions/{condition}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"products": [
"prod_01G1G5V2MBA328390B5AXJ610F"
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Discounts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDiscountsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteDiscountsDiscountConditionsCondition
summary: Delete a Condition
description: Delete a Discount Condition. This does not delete resources associated to the discount condition.
x-authenticated: true
parameters:
- in: path
name: discount_id
required: true
description: The ID of the Discount
schema:
type: string
- in: path
name: condition_id
required: true
description: The ID of the Discount Condition
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned discount.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned discount.
schema:
type: string
x-codegen:
method: deleteCondition
queryParams: AdminDeleteDiscountsDiscountConditionsConditionParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.discounts.deleteCondition(discountId, conditionId)
.then(({ id, object, deleted }) => {
console.log(id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import {
useAdminDiscountRemoveCondition
} from "medusa-react"
type Props = {
discountId: string
}
const Discount = ({ discountId }: Props) => {
const deleteCondition = useAdminDiscountRemoveCondition(
discountId
)
// ...
const handleDelete = (
conditionId: string
) => {
deleteCondition.mutate(conditionId, {
onSuccess: ({ id, object, deleted }) => {
console.log(deleted)
}
})
}
// ...
}
export default Discount
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/discounts/{id}/conditions/{condition_id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Discounts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDiscountConditionsDeleteRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/discounts/{discount_id}/conditions/{condition_id}/batch:
post:
operationId: PostDiscountsDiscountConditionsConditionBatch
summary: Add Batch Resources
description: Add a batch of resources to a discount condition. The type of resource depends on the type of discount condition. For example, if the discount condition's type is `products`, the resources being added should be products.
x-authenticated: true
parameters:
- in: path
name: discount_id
required: true
description: The ID of the discount the condition belongs to.
schema:
type: string
- in: path
name: condition_id
required: true
description: The ID of the discount condition on which to add the item.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned discount.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned discount.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostDiscountsDiscountConditionsConditionBatchReq'
x-codegen:
method: addConditionResourceBatch
queryParams: AdminPostDiscountsDiscountConditionsConditionBatchParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.discounts.addConditionResourceBatch(discountId, conditionId, {
resources: [{ id: itemId }]
})
.then(({ discount }) => {
console.log(discount.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import {
useAdminAddDiscountConditionResourceBatch
} from "medusa-react"
type Props = {
discountId: string
conditionId: string
}
const DiscountCondition = ({
discountId,
conditionId
}: Props) => {
const addConditionResources = useAdminAddDiscountConditionResourceBatch(
discountId,
conditionId
)
// ...
const handleAdd = (itemId: string) => {
addConditionResources.mutate({
resources: [
{
id: itemId
}
]
}, {
onSuccess: ({ discount }) => {
console.log(discount.id)
}
})
}
// ...
}
export default DiscountCondition
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/discounts/{id}/conditions/{condition_id}/batch' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"resources": [{ "id": "item_id" }]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Discounts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDiscountsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteDiscountsDiscountConditionsConditionBatch
summary: Remove Batch Resources
description: Remove a batch of resources from a discount condition. This will only remove the association between the resource and the discount condition, not the resource itself.
x-authenticated: true
parameters:
- in: path
name: discount_id
required: true
description: The ID of the discount.
schema:
type: string
- in: path
name: condition_id
required: true
description: The ID of the condition to remove the resources from.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned discount.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned discount.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDeleteDiscountsDiscountConditionsConditionBatchReq'
x-codegen:
method: deleteConditionResourceBatch
x-codeSamples:
- lang: JavaScript
label: JS Client
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.discounts.deleteConditionResourceBatch(discountId, conditionId, {
resources: [{ id: itemId }]
})
.then(({ discount }) => {
console.log(discount.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import {
useAdminDeleteDiscountConditionResourceBatch
} from "medusa-react"
type Props = {
discountId: string
conditionId: string
}
const DiscountCondition = ({
discountId,
conditionId
}: Props) => {
const deleteConditionResource = useAdminDeleteDiscountConditionResourceBatch(
discountId,
conditionId,
)
// ...
const handleDelete = (itemId: string) => {
deleteConditionResource.mutate({
resources: [
{
id: itemId
}
]
}, {
onSuccess: ({ discount }) => {
console.log(discount.id)
}
})
}
// ...
}
export default DiscountCondition
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/discounts/{id}/conditions/{condition_id}/batch' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"resources": [{ "id": "item_id" }]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Discounts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDiscountsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/discounts/{id}:
get:
operationId: GetDiscountsDiscount
summary: Get a Discount
description: Retrieve a Discount.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Discount
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned discount.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned discount.
schema:
type: string
x-codegen:
method: retrieve
queryParams: AdminGetDiscountParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.discounts.retrieve(discountId)
.then(({ discount }) => {
console.log(discount.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDiscount } from "medusa-react"
type Props = {
discountId: string
}
const Discount = ({ discountId }: Props) => {
const { discount, isLoading } = useAdminDiscount(
discountId
)
return (
{isLoading && Loading...}
{discount && {discount.code}}
)
}
export default Discount
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/discounts/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Discounts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDiscountsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostDiscountsDiscount
summary: Update a Discount
description: Update a Discount with a given set of rules that define how the Discount is applied.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Discount.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned discount.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be retrieved in the returned discount.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostDiscountsDiscountReq'
x-codegen:
method: update
queryParams: AdminPostDiscountsDiscountParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.discounts.update(discountId, {
code: "TEST"
})
.then(({ discount }) => {
console.log(discount.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateDiscount } from "medusa-react"
type Props = {
discountId: string
}
const Discount = ({ discountId }: Props) => {
const updateDiscount = useAdminUpdateDiscount(discountId)
// ...
const handleUpdate = (isDisabled: boolean) => {
updateDiscount.mutate({
is_disabled: isDisabled,
})
}
// ...
}
export default Discount
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/discounts/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"code": "TEST"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Discounts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDiscountsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteDiscountsDiscount
summary: Delete a Discount
description: Delete a Discount. Deleting the discount will make it unavailable for customers to use.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Discount
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.discounts.delete(discountId)
.then(({ id, object, deleted }) => {
console.log(id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteDiscount } from "medusa-react"
const Discount = () => {
const deleteDiscount = useAdminDeleteDiscount(discount_id)
// ...
const handleDelete = () => {
deleteDiscount.mutate()
}
// ...
}
export default Discount
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/discounts/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Discounts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDiscountsDeleteRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/discounts/{id}/dynamic-codes:
post:
operationId: PostDiscountsDiscountDynamicCodes
summary: Create a Dynamic Code
description: Create a dynamic unique code that can map to a parent Discount. This is useful if you want to automatically generate codes with the same rules and conditions.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Discount to create the dynamic code for."
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostDiscountsDiscountDynamicCodesReq'
x-codegen:
method: createDynamicCode
x-codeSamples:
- lang: JavaScript
label: JS Client
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.discounts.createDynamicCode(discountId, {
code: "TEST",
usage_limit: 1
})
.then(({ discount }) => {
console.log(discount.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCreateDynamicDiscountCode } from "medusa-react"
type Props = {
discountId: string
}
const Discount = ({ discountId }: Props) => {
const createDynamicDiscount = useAdminCreateDynamicDiscountCode(discountId)
// ...
const handleCreate = (
code: string,
usageLimit: number
) => {
createDynamicDiscount.mutate({
code,
usage_limit: usageLimit
}, {
onSuccess: ({ discount }) => {
console.log(discount.is_dynamic)
}
})
}
// ...
}
export default Discount
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/discounts/{id}/dynamic-codes' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"code": "TEST"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Discounts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDiscountsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/discounts/{id}/dynamic-codes/{code}:
delete:
operationId: DeleteDiscountsDiscountDynamicCodesCode
summary: Delete a Dynamic Code
description: Delete a dynamic code from a Discount.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Discount
schema:
type: string
- in: path
name: code
required: true
description: The dynamic code to delete
schema:
type: string
x-codegen:
method: deleteDynamicCode
x-codeSamples:
- lang: JavaScript
label: JS Client
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.discounts.deleteDynamicCode(discountId, code)
.then(({ discount }) => {
console.log(discount.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteDynamicDiscountCode } from "medusa-react"
type Props = {
discountId: string
}
const Discount = ({ discountId }: Props) => {
const deleteDynamicDiscount = useAdminDeleteDynamicDiscountCode(discountId)
// ...
const handleDelete = (code: string) => {
deleteDynamicDiscount.mutate(code, {
onSuccess: ({ discount }) => {
console.log(discount.is_dynamic)
}
})
}
// ...
}
export default Discount
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/discounts/{id}/dynamic-codes/{code}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Discounts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDiscountsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/discounts/{id}/regions/{region_id}:
post:
operationId: PostDiscountsDiscountRegionsRegion
summary: Add Region to Discount
description: Add a Region to the list of Regions a Discount can be used in.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Discount.
schema:
type: string
- in: path
name: region_id
required: true
description: The ID of the Region.
schema:
type: string
x-codegen:
method: addRegion
x-codeSamples:
- lang: JavaScript
label: JS Client
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.discounts.addRegion(discountId, regionId)
.then(({ discount }) => {
console.log(discount.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDiscountAddRegion } from "medusa-react"
type Props = {
discountId: string
}
const Discount = ({ discountId }: Props) => {
const addRegion = useAdminDiscountAddRegion(discountId)
// ...
const handleAdd = (regionId: string) => {
addRegion.mutate(regionId, {
onSuccess: ({ discount }) => {
console.log(discount.regions)
}
})
}
// ...
}
export default Discount
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/discounts/{id}/regions/{region_id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Discounts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDiscountsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteDiscountsDiscountRegionsRegion
summary: Remove Region
x-authenticated: true
description: Remove a Region from the list of Regions that a Discount can be used in. This does not delete a region, only the association between it and the discount.
parameters:
- in: path
name: id
required: true
description: The ID of the Discount.
schema:
type: string
- in: path
name: region_id
required: true
description: The ID of the Region.
schema:
type: string
x-codegen:
method: removeRegion
x-codeSamples:
- lang: JavaScript
label: JS Client
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.discounts.removeRegion(discountId, regionId)
.then(({ discount }) => {
console.log(discount.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDiscountRemoveRegion } from "medusa-react"
type Props = {
discountId: string
}
const Discount = ({ discountId }: Props) => {
const deleteRegion = useAdminDiscountRemoveRegion(discountId)
// ...
const handleDelete = (regionId: string) => {
deleteRegion.mutate(regionId, {
onSuccess: ({ discount }) => {
console.log(discount.regions)
}
})
}
// ...
}
export default Discount
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/discounts/{id}/regions/{region_id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Discounts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDiscountsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/draft-orders:
get:
operationId: GetDraftOrders
summary: List Draft Orders
description: Retrieve an list of Draft Orders. The draft orders can be filtered by fields such as `q`. The draft orders can also paginated.
x-authenticated: true
parameters:
- in: query
name: offset
description: The number of draft orders to skip when retrieving the draft orders.
schema:
type: number
default: '0'
- in: query
name: limit
description: Limit the number of draft orders returned.
schema:
type: number
default: '50'
- in: query
name: q
description: a term to search draft orders' display IDs and emails in the draft order's cart
schema:
type: string
- in: query
name: order
description: Field to sort retrieved draft orders by.
schema:
type: string
- in: query
name: expand
description: A comma-separated list of fields to expand.
schema:
type: string
- in: query
name: fields
description: A comma-separated list of fields to include in the response.
schema:
type: string
- in: query
name: created_at
description: Filter by a creation date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: updated_at
description: Filter by an update date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: status
style: form
explode: false
description: Filter by status
schema:
type: array
items:
type: string
enum:
- open
- completed
x-codegen:
method: list
queryParams: AdminGetDraftOrdersParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.draftOrders.list()
.then(({ draft_orders, limit, offset, count }) => {
console.log(draft_orders.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDraftOrders } from "medusa-react"
const DraftOrders = () => {
const { draft_orders, isLoading } = useAdminDraftOrders()
return (
{isLoading &&
Loading...}
{draft_orders && !draft_orders.length && (
No Draft Orders
)}
{draft_orders && draft_orders.length > 0 && (
{draft_orders.map((order) => (
- {order.display_id}
))}
)}
{isLoading && Loading...}
{draft_order && {draft_order.display_id}}
)
}
export default DraftOrder
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/draft-orders/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Draft Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDraftOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostDraftOrdersDraftOrder
summary: Update a Draft Order
description: Update a Draft Order's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Draft Order.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostDraftOrdersDraftOrderReq'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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.draftOrders.update(draftOrderId, {
email: "user@example.com"
})
.then(({ draft_order }) => {
console.log(draft_order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateDraftOrder } from "medusa-react"
type Props = {
draftOrderId: string
}
const DraftOrder = ({ draftOrderId }: Props) => {
const updateDraftOrder = useAdminUpdateDraftOrder(
draftOrderId
)
// ...
const handleUpdate = (email: string) => {
updateDraftOrder.mutate({
email,
}, {
onSuccess: ({ draft_order }) => {
console.log(draft_order.id)
}
})
}
// ...
}
export default DraftOrder
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/draft-orders/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"email": "user@example.com"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Draft Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDraftOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteDraftOrdersDraftOrder
summary: Delete a Draft Order
description: Delete a Draft Order.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Draft Order.
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.draftOrders.delete(draftOrderId)
.then(({ id, object, deleted }) => {
console.log(id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteDraftOrder } from "medusa-react"
type Props = {
draftOrderId: string
}
const DraftOrder = ({ draftOrderId }: Props) => {
const deleteDraftOrder = useAdminDeleteDraftOrder(
draftOrderId
)
// ...
const handleDelete = () => {
deleteDraftOrder.mutate(void 0, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
// ...
}
export default DraftOrder
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/draft-orders/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Draft Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDraftOrdersDeleteRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/draft-orders/{id}/line-items:
post:
operationId: PostDraftOrdersDraftOrderLineItems
summary: Create a Line Item
description: Create a Line Item in the Draft Order.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Draft Order.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostDraftOrdersDraftOrderLineItemsReq'
x-codegen:
method: addLineItem
x-codeSamples:
- lang: JavaScript
label: JS Client
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.draftOrders.addLineItem(draftOrderId, {
quantity: 1
})
.then(({ draft_order }) => {
console.log(draft_order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDraftOrderAddLineItem } from "medusa-react"
type Props = {
draftOrderId: string
}
const DraftOrder = ({ draftOrderId }: Props) => {
const addLineItem = useAdminDraftOrderAddLineItem(
draftOrderId
)
// ...
const handleAdd = (quantity: number) => {
addLineItem.mutate({
quantity,
}, {
onSuccess: ({ draft_order }) => {
console.log(draft_order.cart)
}
})
}
// ...
}
export default DraftOrder
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/draft-orders/{id}/line-items' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"quantity": 1
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Draft Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDraftOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/draft-orders/{id}/line-items/{line_id}:
post:
operationId: PostDraftOrdersDraftOrderLineItemsItem
summary: Update a Line Item
description: Update a Line Item in a Draft Order.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Draft Order.
schema:
type: string
- in: path
name: line_id
required: true
description: The ID of the Line Item.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostDraftOrdersDraftOrderLineItemsItemReq'
x-codegen:
method: updateLineItem
x-codeSamples:
- lang: JavaScript
label: JS Client
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.draftOrders.updateLineItem(draftOrderId, lineId, {
quantity: 1
})
.then(({ draft_order }) => {
console.log(draft_order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDraftOrderUpdateLineItem } from "medusa-react"
type Props = {
draftOrderId: string
}
const DraftOrder = ({ draftOrderId }: Props) => {
const updateLineItem = useAdminDraftOrderUpdateLineItem(
draftOrderId
)
// ...
const handleUpdate = (
itemId: string,
quantity: number
) => {
updateLineItem.mutate({
item_id: itemId,
quantity,
})
}
// ...
}
export default DraftOrder
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/draft-orders/{id}/line-items/{line_id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"quantity": 1
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Draft Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDraftOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteDraftOrdersDraftOrderLineItemsItem
summary: Delete a Line Item
description: Delete a Line Item from a Draft Order.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Draft Order.
schema:
type: string
- in: path
name: line_id
required: true
description: The ID of the line item.
schema:
type: string
x-codegen:
method: removeLineItem
x-codeSamples:
- lang: JavaScript
label: JS Client
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.draftOrders.removeLineItem(draftOrderId, itemId)
.then(({ draft_order }) => {
console.log(draft_order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDraftOrderRemoveLineItem } from "medusa-react"
type Props = {
draftOrderId: string
}
const DraftOrder = ({ draftOrderId }: Props) => {
const deleteLineItem = useAdminDraftOrderRemoveLineItem(
draftOrderId
)
// ...
const handleDelete = (itemId: string) => {
deleteLineItem.mutate(itemId, {
onSuccess: ({ draft_order }) => {
console.log(draft_order.cart)
}
})
}
// ...
}
export default DraftOrder
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/draft-orders/{id}/line-items/{line_id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Draft Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDraftOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/draft-orders/{id}/pay:
post:
summary: Mark Paid
operationId: PostDraftOrdersDraftOrderRegisterPayment
description: Capture the draft order's payment. This will also set the draft order's status to `completed` and create an Order from the draft order. The payment is captured through Medusa's system payment, which is manual payment that isn't integrated with any third-party payment provider. It is assumed that the payment capturing is handled manually by the admin.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The Draft Order ID.
schema:
type: string
x-codegen:
method: markPaid
x-codeSamples:
- lang: JavaScript
label: JS Client
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.draftOrders.markPaid(draftOrderId)
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDraftOrderRegisterPayment } from "medusa-react"
type Props = {
draftOrderId: string
}
const DraftOrder = ({ draftOrderId }: Props) => {
const registerPayment = useAdminDraftOrderRegisterPayment(
draftOrderId
)
// ...
const handlePayment = () => {
registerPayment.mutate(void 0, {
onSuccess: ({ order }) => {
console.log(order.id)
}
})
}
// ...
}
export default DraftOrder
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/draft-orders/{id}/pay' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Draft Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostDraftOrdersDraftOrderRegisterPaymentRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/gift-cards:
get:
operationId: GetGiftCards
summary: List Gift Cards
description: Retrieve a list of Gift Cards. The gift cards can be filtered by fields such as `q`. The gift cards can also paginated.
x-authenticated: true
parameters:
- in: query
name: offset
description: The number of gift cards to skip when retrieving the gift cards.
schema:
type: number
default: '0'
- in: query
name: limit
description: Limit the number of gift cards returned.
schema:
type: number
default: '50'
- in: query
name: q
description: a term to search gift cards' code or display ID
schema:
type: string
- in: query
name: order
description: A gift card field to sort-order the retrieved gift cards by.
schema:
type: string
x-codegen:
method: list
queryParams: AdminGetGiftCardsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.giftCards.list()
.then(({ gift_cards, limit, offset, count }) => {
console.log(gift_cards.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { GiftCard } from "@medusajs/medusa"
import { useAdminGiftCards } from "medusa-react"
const CustomGiftCards = () => {
const { gift_cards, isLoading } = useAdminGiftCards()
return (
{isLoading &&
Loading...}
{gift_cards && !gift_cards.length && (
No custom gift cards...
)}
{gift_cards && gift_cards.length > 0 && (
{gift_cards.map((giftCard: GiftCard) => (
- {giftCard.code}
))}
)}
{isLoading && Loading...}
{gift_card && {gift_card.code}}
)
}
export default CustomGiftCard
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/gift-cards/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Gift Cards
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminGiftCardsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostGiftCardsGiftCard
summary: Update a Gift Card
description: Update a Gift Card's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Gift Card.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostGiftCardsGiftCardReq'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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.giftCards.update(giftCardId, {
region_id
})
.then(({ gift_card }) => {
console.log(gift_card.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateGiftCard } from "medusa-react"
type Props = {
customGiftCardId: string
}
const CustomGiftCard = ({ customGiftCardId }: Props) => {
const updateGiftCard = useAdminUpdateGiftCard(
customGiftCardId
)
// ...
const handleUpdate = (regionId: string) => {
updateGiftCard.mutate({
region_id: regionId,
}, {
onSuccess: ({ gift_card }) => {
console.log(gift_card.id)
}
})
}
// ...
}
export default CustomGiftCard
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/gift-cards/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"region_id": "{region_id}"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Gift Cards
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminGiftCardsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteGiftCardsGiftCard
summary: Delete a Gift Card
description: Delete a Gift Card. Once deleted, it can't be used by customers.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Gift Card to delete.
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.giftCards.delete(giftCardId)
.then(({ id, object, deleted }) => {
console.log(id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteGiftCard } from "medusa-react"
type Props = {
customGiftCardId: string
}
const CustomGiftCard = ({ customGiftCardId }: Props) => {
const deleteGiftCard = useAdminDeleteGiftCard(
customGiftCardId
)
// ...
const handleDelete = () => {
deleteGiftCard.mutate(void 0, {
onSuccess: ({ id, object, deleted}) => {
console.log(id)
}
})
}
// ...
}
export default CustomGiftCard
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/gift-cards/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Gift Cards
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminGiftCardsDeleteRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/inventory-items:
get:
operationId: GetInventoryItems
summary: List Inventory Items
description: Retrieve a list of inventory items. The inventory items can be filtered by fields such as `q` or `location_id`. The inventory items can also be paginated.
x-authenticated: true
parameters:
- in: query
name: offset
description: The number of inventory items to skip when retrieving the inventory items.
schema:
type: integer
default: 0
- in: query
name: limit
description: Limit the number of inventory items returned.
schema:
type: integer
default: 20
- in: query
name: expand
description: Comma-separated relations that should be expanded in each returned inventory item.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned inventory item.
schema:
type: string
- in: query
name: q
description: term to search inventory item's sku, title, and description.
schema:
type: string
- in: query
name: order
description: Field to sort-order inventory items by.
schema:
type: string
- in: query
name: location_id
style: form
explode: false
description: Filter by location IDs.
schema:
type: array
items:
type: string
- in: query
name: id
style: form
explode: false
description: Filter by the inventory ID
schema:
oneOf:
- type: string
description: inventory ID
- type: array
description: an array of inventory IDs
items:
type: string
- in: query
name: sku
description: Filter by SKU
schema:
type: string
- in: query
name: origin_country
description: Filter by origin country
schema:
type: string
- in: query
name: mid_code
description: Filter by MID code
schema:
type: string
- in: query
name: material
description: Filter by material
schema:
type: string
- in: query
name: hs_code
description: Filter by HS Code
schema:
type: string
- in: query
name: weight
description: Filter by weight
schema:
type: string
- in: query
name: length
description: Filter by length
schema:
type: string
- in: query
name: height
description: Filter by height
schema:
type: string
- in: query
name: width
description: Filter by width
schema:
type: string
- in: query
name: requires_shipping
description: Filter by whether the item requires shipping
schema:
type: string
x-codegen:
method: list
queryParams: AdminGetInventoryItemsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.inventoryItems.list()
.then(({ inventory_items, count, offset, limit }) => {
console.log(inventory_items.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminInventoryItems } from "medusa-react"
function InventoryItems() {
const {
inventory_items,
isLoading
} = useAdminInventoryItems()
return (
{isLoading &&
Loading...}
{inventory_items && !inventory_items.length && (
No Items
)}
{inventory_items && inventory_items.length > 0 && (
{inventory_items.map(
(item) => (
- {item.id}
)
)}
)}
{isLoading && Loading...}
{inventory_item && (
{inventory_item.sku}
)}
)
}
export default InventoryItem
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/inventory-items/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Inventory Items
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminInventoryItemsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostInventoryItemsInventoryItem
summary: Update an Inventory Item
description: Update an Inventory Item's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Inventory Item.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned inventory level.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned inventory level.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostInventoryItemsInventoryItemReq'
x-codegen:
method: update
queryParams: AdminPostInventoryItemsInventoryItemParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.inventoryItems.update(inventoryItemId, {
origin_country: "US",
})
.then(({ inventory_item }) => {
console.log(inventory_item.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateInventoryItem } from "medusa-react"
type Props = {
inventoryItemId: string
}
const InventoryItem = ({ inventoryItemId }: Props) => {
const updateInventoryItem = useAdminUpdateInventoryItem(
inventoryItemId
)
// ...
const handleUpdate = (origin_country: string) => {
updateInventoryItem.mutate({
origin_country,
}, {
onSuccess: ({ inventory_item }) => {
console.log(inventory_item.origin_country)
}
})
}
// ...
}
export default InventoryItem
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/inventory-items/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"origin_country": "US"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Inventory Items
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminInventoryItemsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteInventoryItemsInventoryItem
summary: Delete an Inventory Item
description: Delete an Inventory Item. This does not delete the associated product variant.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Inventory Item to delete.
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.inventoryItems.delete(inventoryItemId)
.then(({ id, object, deleted }) => {
console.log(id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteInventoryItem } from "medusa-react"
type Props = {
inventoryItemId: string
}
const InventoryItem = ({ inventoryItemId }: Props) => {
const deleteInventoryItem = useAdminDeleteInventoryItem(
inventoryItemId
)
// ...
const handleDelete = () => {
deleteInventoryItem.mutate()
}
// ...
}
export default InventoryItem
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/inventory-items/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Inventory Items
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminInventoryItemsDeleteRes'
'400':
$ref: '#/components/responses/400_error'
/admin/inventory-items/{id}/location-levels:
get:
operationId: GetInventoryItemsInventoryItemLocationLevels
summary: List Inventory Level
description: Retrieve a list of inventory levels of an inventory item. The inventory levels can be filtered by fields such as `location_id`.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Inventory Item the locations are associated with.
schema:
type: string
- in: query
name: location_id
style: form
explode: false
description: Filter by location IDs.
schema:
type: array
items:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned inventory levels.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned inventory levels.
schema:
type: string
x-codegen:
method: listLocationLevels
queryParams: AdminGetInventoryItemsItemLocationLevelsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.inventoryItems.listLocationLevels(inventoryItemId)
.then(({ inventory_item }) => {
console.log(inventory_item.location_levels);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import {
useAdminInventoryItemLocationLevels,
} from "medusa-react"
type Props = {
inventoryItemId: string
}
const InventoryItem = ({ inventoryItemId }: Props) => {
const {
inventory_item,
isLoading,
} = useAdminInventoryItemLocationLevels(inventoryItemId)
return (
{isLoading &&
Loading...}
{inventory_item && (
{inventory_item.location_levels.map((level) => (
{level.stocked_quantity}
))}
)}
{isLoading &&
Loading...}
{notes && !notes.length &&
No Notes}
{notes && notes.length > 0 && (
{notes.map((note) => (
- {note.resource_type}
))}
)}
{isLoading && Loading...}
{note && {note.resource_type}}
)
}
export default Note
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/notes/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Notes
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminNotesRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostNotesNote
summary: Update a Note
x-authenticated: true
description: Update a Note's details.
parameters:
- in: path
name: id
required: true
description: The ID of the Note
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostNotesNoteReq'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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.notes.update(noteId, {
value: "We delivered this order"
})
.then(({ note }) => {
console.log(note.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateNote } from "medusa-react"
type Props = {
noteId: string
}
const Note = ({ noteId }: Props) => {
const updateNote = useAdminUpdateNote(noteId)
// ...
const handleUpdate = (
value: string
) => {
updateNote.mutate({
value
}, {
onSuccess: ({ note }) => {
console.log(note.value)
}
})
}
// ...
}
export default Note
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/notes/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"value": "We delivered this order"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Notes
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminNotesRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteNotesNote
summary: Delete a Note
description: Delete a Note.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Note to delete.
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.notes.delete(noteId)
.then(({ id, object, deleted }) => {
console.log(id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteNote } from "medusa-react"
type Props = {
noteId: string
}
const Note = ({ noteId }: Props) => {
const deleteNote = useAdminDeleteNote(noteId)
// ...
const handleDelete = () => {
deleteNote.mutate()
}
// ...
}
export default Note
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/notes/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Notes
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminNotesDeleteRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/notifications:
get:
operationId: GetNotifications
summary: List Notifications
description: Retrieve a list of notifications. The notifications can be filtered by fields such as `event_name` or `resource_type`. The notifications can also be paginated.
x-authenticated: true
parameters:
- in: query
name: offset
description: The number of inventory items to skip when retrieving the inventory items.
schema:
type: integer
default: 0
- in: query
name: limit
description: Limit the number of notifications returned.
schema:
type: integer
default: 50
- in: query
name: fields
description: Comma-separated fields that should be included in each returned notification.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in each returned notification.
schema:
type: string
- in: query
name: event_name
description: Filter by the name of the event that triggered sending this notification.
schema:
type: string
- in: query
name: resource_type
description: Filter by the resource type.
schema:
type: string
- in: query
name: resource_id
description: Filter by the resource ID.
schema:
type: string
- in: query
name: to
description: Filter by the address that the Notification was sent to. This will usually be an email address, but it can also represent other addresses such as a chat bot user id.
schema:
type: string
- in: query
name: include_resends
description: A boolean indicating whether the result set should include resent notifications or not
schema:
type: string
x-codegen:
method: list
queryParams: AdminGetNotificationsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.notifications.list()
.then(({ notifications }) => {
console.log(notifications.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminNotifications } from "medusa-react"
const Notifications = () => {
const { notifications, isLoading } = useAdminNotifications()
return (
{isLoading &&
Loading...}
{notifications && !notifications.length && (
No Notifications
)}
{notifications && notifications.length > 0 && (
{notifications.map((notification) => (
- {notification.to}
))}
)}
{isLoading &&
Loading...}
{order_edits && !order_edits.length && (
No Order Edits
)}
{order_edits && order_edits.length > 0 && (
{order_edits.map((orderEdit) => (
-
{orderEdit.status}
))}
)}
{isLoading && Loading...}
{order_edit && {order_edit.status}}
)
}
export default OrderEdit
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/order-edits/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Order Edits
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrderEditsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostOrderEditsOrderEdit
summary: Update an Order Edit
description: Update an Order Edit's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the OrderEdit.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostOrderEditsOrderEditReq'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orderEdits.update(orderEditId, {
internal_note: "internal reason XY"
})
.then(({ order_edit }) => {
console.log(order_edit.id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateOrderEdit } from "medusa-react"
type Props = {
orderEditId: string
}
const OrderEdit = ({ orderEditId }: Props) => {
const updateOrderEdit = useAdminUpdateOrderEdit(
orderEditId,
)
const handleUpdate = (
internalNote: string
) => {
updateOrderEdit.mutate({
internal_note: internalNote
}, {
onSuccess: ({ order_edit }) => {
console.log(order_edit.internal_note)
}
})
}
// ...
}
export default OrderEdit
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/order-edits/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"internal_note": "internal reason XY"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Order Edits
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrderEditsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteOrderEditsOrderEdit
summary: Delete an Order Edit
description: Delete an Order Edit. Only order edits that have the status `created` can be deleted.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Order Edit to delete.
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orderEdits.delete(orderEditId)
.then(({ id, object, deleted }) => {
console.log(id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteOrderEdit } from "medusa-react"
type Props = {
orderEditId: string
}
const OrderEdit = ({ orderEditId }: Props) => {
const deleteOrderEdit = useAdminDeleteOrderEdit(
orderEditId
)
const handleDelete = () => {
deleteOrderEdit.mutate(void 0, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
// ...
}
export default OrderEdit
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/order-edits/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Order Edits
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrderEditDeleteRes'
'400':
$ref: '#/components/responses/400_error'
/admin/order-edits/{id}/cancel:
post:
operationId: PostOrderEditsOrderEditCancel
summary: Cancel an Order Edit
description: Cancel an Order Edit.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the OrderEdit.
schema:
type: string
x-codegen:
method: cancel
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orderEdits.cancel(orderEditId)
.then(({ order_edit }) => {
console.log(order_edit.id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import {
useAdminCancelOrderEdit
} from "medusa-react"
type Props = {
orderEditId: string
}
const OrderEdit = ({ orderEditId }: Props) => {
const cancelOrderEdit =
useAdminCancelOrderEdit(
orderEditId
)
const handleCancel = () => {
cancelOrderEdit.mutate(void 0, {
onSuccess: ({ order_edit }) => {
console.log(
order_edit.id
)
}
})
}
// ...
}
export default OrderEdit
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/order-edits/{id}/cancel' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Order Edits
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrderEditsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'500':
$ref: '#/components/responses/500_error'
/admin/order-edits/{id}/changes/{change_id}:
delete:
operationId: DeleteOrderEditsOrderEditItemChange
summary: Delete a Line Item Change
description: Delete a line item change that indicates the addition, deletion, or update of a line item in the original order.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Order Edit.
schema:
type: string
- in: path
name: change_id
required: true
description: The ID of the Line Item Change to delete.
schema:
type: string
x-codegen:
method: deleteItemChange
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orderEdits.deleteItemChange(orderEdit_id, itemChangeId)
.then(({ id, object, deleted }) => {
console.log(id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteOrderEditItemChange } from "medusa-react"
type Props = {
orderEditId: string
itemChangeId: string
}
const OrderEditItemChange = ({
orderEditId,
itemChangeId
}: Props) => {
const deleteItemChange = useAdminDeleteOrderEditItemChange(
orderEditId,
itemChangeId
)
const handleDeleteItemChange = () => {
deleteItemChange.mutate(void 0, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
// ...
}
export default OrderEditItemChange
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/order-edits/{id}/changes/{change_id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Order Edits
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrderEditItemChangeDeleteRes'
'400':
$ref: '#/components/responses/400_error'
/admin/order-edits/{id}/confirm:
post:
operationId: PostOrderEditsOrderEditConfirm
summary: Confirm an OrderEdit
description: Confirm an Order Edit. This will reflect the changes in the order edit on the associated order.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the order edit.
schema:
type: string
x-codegen:
method: confirm
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orderEdits.confirm(orderEditId)
.then(({ order_edit }) => {
console.log(order_edit.id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminConfirmOrderEdit } from "medusa-react"
type Props = {
orderEditId: string
}
const OrderEdit = ({ orderEditId }: Props) => {
const confirmOrderEdit = useAdminConfirmOrderEdit(
orderEditId
)
const handleConfirmOrderEdit = () => {
confirmOrderEdit.mutate(void 0, {
onSuccess: ({ order_edit }) => {
console.log(
order_edit.confirmed_at,
order_edit.confirmed_by
)
}
})
}
// ...
}
export default OrderEdit
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/order-edits/{id}/confirm' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Order Edits
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrderEditsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'500':
$ref: '#/components/responses/500_error'
/admin/order-edits/{id}/items:
post:
operationId: PostOrderEditsEditLineItems
summary: Add a Line Item
description: Create a line item change in the order edit that indicates adding an item in the original order. The item will not be added to the original order until the order edit is confirmed.
parameters:
- in: path
name: id
required: true
description: The ID of the Order Edit.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostOrderEditsEditLineItemsReq'
x-authenticated: true
x-codegen:
method: addLineItem
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orderEdits.addLineItem(orderEditId, {
variant_id,
quantity
})
.then(({ order_edit }) => {
console.log(order_edit.id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminOrderEditAddLineItem } from "medusa-react"
type Props = {
orderEditId: string
}
const OrderEdit = ({ orderEditId }: Props) => {
const addLineItem = useAdminOrderEditAddLineItem(
orderEditId
)
const handleAddLineItem =
(quantity: number, variantId: string) => {
addLineItem.mutate({
quantity,
variant_id: variantId,
}, {
onSuccess: ({ order_edit }) => {
console.log(order_edit.changes)
}
})
}
// ...
}
export default OrderEdit
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/order-edits/{id}/items' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{ "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6", "quantity": 3 }'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Order Edits
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrderEditsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/order-edits/{id}/items/{item_id}:
post:
operationId: PostOrderEditsEditLineItemsLineItem
summary: Upsert Line Item Change
description: Create or update a line item change in the order edit that indicates addition, deletion, or update of a line item into an original order. Line item changes are only reflected on the original order after the order edit is confirmed.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Order Edit.
schema:
type: string
- in: path
name: item_id
required: true
description: The ID of the line item in the original order.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostOrderEditsEditLineItemsLineItemReq'
x-codegen:
method: updateLineItem
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orderEdits.updateLineItem(orderEditId, lineItemId, {
quantity: 5
})
.then(({ order_edit }) => {
console.log(order_edit.id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminOrderEditUpdateLineItem } from "medusa-react"
type Props = {
orderEditId: string
itemId: string
}
const OrderEditItemChange = ({
orderEditId,
itemId
}: Props) => {
const updateLineItem = useAdminOrderEditUpdateLineItem(
orderEditId,
itemId
)
const handleUpdateLineItem = (quantity: number) => {
updateLineItem.mutate({
quantity,
}, {
onSuccess: ({ order_edit }) => {
console.log(order_edit.items)
}
})
}
// ...
}
export default OrderEditItemChange
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/order-edits/{id}/items/{item_id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{ "quantity": 5 }'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Order Edits
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrderEditsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteOrderEditsOrderEditLineItemsLineItem
summary: Delete Line Item
description: Create a line item change in the order edit that indicates deleting an item in the original order. The item in the original order will not be deleted until the order edit is confirmed.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Order Edit.
schema:
type: string
- in: path
name: item_id
required: true
description: The ID of line item in the original order.
schema:
type: string
x-codegen:
method: removeLineItem
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orderEdits.removeLineItem(orderEditId, lineItemId)
.then(({ order_edit }) => {
console.log(order_edit.id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminOrderEditDeleteLineItem } from "medusa-react"
type Props = {
orderEditId: string
itemId: string
}
const OrderEditLineItem = ({
orderEditId,
itemId
}: Props) => {
const removeLineItem = useAdminOrderEditDeleteLineItem(
orderEditId,
itemId
)
const handleRemoveLineItem = () => {
removeLineItem.mutate(void 0, {
onSuccess: ({ order_edit }) => {
console.log(order_edit.changes)
}
})
}
// ...
}
export default OrderEditLineItem
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/order-edits/{id}/items/{item_id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Order Edits
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrderEditsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/order-edits/{id}/request:
post:
operationId: PostOrderEditsOrderEditRequest
summary: Request Confirmation
description: Request customer confirmation of an Order Edit. This would emit the event `order-edit.requested` which Notification Providers listen to and send a notification to the customer about the order edit.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Order Edit.
schema:
type: string
x-codegen:
method: requestConfirmation
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orderEdits.requestConfirmation(orderEditId)
.then({ order_edit }) => {
console.log(order_edit.id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import {
useAdminRequestOrderEditConfirmation,
} from "medusa-react"
type Props = {
orderEditId: string
}
const OrderEdit = ({ orderEditId }: Props) => {
const requestOrderConfirmation =
useAdminRequestOrderEditConfirmation(
orderEditId
)
const handleRequestConfirmation = () => {
requestOrderConfirmation.mutate(void 0, {
onSuccess: ({ order_edit }) => {
console.log(
order_edit.requested_at,
order_edit.requested_by
)
}
})
}
// ...
}
export default OrderEdit
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/order-edits/{id}/request' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Order Edits
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrderEditsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders:
get:
operationId: GetOrders
summary: List Orders
description: Retrieve a list of Orders. The orders can be filtered by fields such as `status` or `display_id`. The order can also be paginated.
x-authenticated: true
parameters:
- in: query
name: q
description: term to search orders' shipping address, first name, email, and display ID
schema:
type: string
- in: query
name: id
description: Filter by ID.
schema:
type: string
- in: query
name: status
style: form
explode: false
description: Filter by status
schema:
type: array
items:
type: string
enum:
- pending
- completed
- archived
- canceled
- requires_action
- in: query
name: fulfillment_status
style: form
explode: false
description: Filter by fulfillment status
schema:
type: array
items:
type: string
enum:
- not_fulfilled
- fulfilled
- partially_fulfilled
- shipped
- partially_shipped
- canceled
- returned
- partially_returned
- requires_action
- in: query
name: payment_status
style: form
explode: false
description: Filter by payment status
schema:
type: array
items:
type: string
enum:
- captured
- awaiting
- not_paid
- refunded
- partially_refunded
- canceled
- requires_action
- in: query
name: display_id
description: Filter by display ID
schema:
type: string
- in: query
name: cart_id
description: Filter by cart ID
schema:
type: string
- in: query
name: customer_id
description: Filter by customer ID
schema:
type: string
- in: query
name: email
description: Filter by email
schema:
type: string
- in: query
name: region_id
style: form
explode: false
description: Filter by region IDs.
schema:
oneOf:
- type: string
description: ID of a Region.
- type: array
items:
type: string
description: ID of a Region.
- in: query
name: currency_code
style: form
explode: false
description: Filter by currency codes.
schema:
type: string
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
description: See a list of codes.
- in: query
name: tax_rate
description: Filter by tax rate.
schema:
type: string
- in: query
name: created_at
description: Filter by a creation date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: updated_at
description: Filter by an update date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: canceled_at
description: Filter by a cancelation date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: sales_channel_id
style: form
explode: false
description: Filter by Sales Channel IDs
schema:
type: array
items:
type: string
description: The ID of a Sales Channel
- in: query
name: offset
description: The number of orders to skip when retrieving the orders.
schema:
type: integer
default: 0
- in: query
name: limit
description: Limit the number of orders returned.
schema:
type: integer
default: 50
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
- in: query
name: order
description: Field to sort retrieved orders by.
schema:
type: string
x-codegen:
method: list
queryParams: AdminGetOrdersParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.list()
.then(({ orders, limit, offset, count }) => {
console.log(orders.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminOrders } from "medusa-react"
const Orders = () => {
const { orders, isLoading } = useAdminOrders()
return (
{isLoading &&
Loading...}
{orders && !orders.length &&
No Orders}
{orders && orders.length > 0 && (
{orders.map((order) => (
- {order.display_id}
))}
)}
{isLoading && Loading...}
{order && {order.display_id}}
)
}
export default Order
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/orders/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostOrdersOrder
summary: Update an Order
description: Update and order's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Order.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostOrdersOrderReq'
x-codegen:
method: update
params: AdminPostOrdersOrderParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.update(orderId, {
email: "user@example.com"
})
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateOrder } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const updateOrder = useAdminUpdateOrder(
orderId
)
const handleUpdate = (
email: string
) => {
updateOrder.mutate({
email,
}, {
onSuccess: ({ order }) => {
console.log(order.email)
}
})
}
// ...
}
export default Order
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/adasda' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"email": "user@example.com"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/archive:
post:
operationId: PostOrdersOrderArchive
summary: Archive Order
description: Archive an order and change its status.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Order.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
x-codegen:
method: archive
params: AdminPostOrdersOrderArchiveParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.archive(orderId)
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminArchiveOrder } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const archiveOrder = useAdminArchiveOrder(
orderId
)
// ...
const handleArchivingOrder = () => {
archiveOrder.mutate(void 0, {
onSuccess: ({ order }) => {
console.log(order.status)
}
})
}
// ...
}
export default Order
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/archive' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/cancel:
post:
operationId: PostOrdersOrderCancel
summary: Cancel an Order
description: Cancel an order and change its status. This will also cancel any associated Fulfillments and Payments, and it may fail if the Payment or Fulfillment Provider is unable to cancel the Payment/Fulfillment.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Order.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
x-codegen:
method: cancel
params: AdminPostOrdersOrderCancel
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.cancel(orderId)
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCancelOrder } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const cancelOrder = useAdminCancelOrder(
orderId
)
// ...
const handleCancel = () => {
cancelOrder.mutate(void 0, {
onSuccess: ({ order }) => {
console.log(order.status)
}
})
}
// ...
}
export default Order
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/cancel' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/capture:
post:
operationId: PostOrdersOrderCapture
summary: Capture an Order's Payments
description: Capture all the Payments associated with an Order. The payment of canceled orders can't be captured.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Order.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
x-codegen:
method: capturePayment
params: AdminPostOrdersOrderCaptureParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.capturePayment(orderId)
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCapturePayment } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const capturePayment = useAdminCapturePayment(
orderId
)
// ...
const handleCapture = () => {
capturePayment.mutate(void 0, {
onSuccess: ({ order }) => {
console.log(order.status)
}
})
}
// ...
}
export default Order
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/capture' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/claims:
post:
operationId: PostOrdersOrderClaims
summary: Create a Claim
description: Create a Claim for an order. If a return shipping method is specified, a return will also be created and associated with the claim. If the claim's type is `refund`, the refund is processed as well.
externalDocs:
description: How are claims created
url: https://docs.medusajs.com/modules/orders/claims#how-are-claims-created
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Order.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostOrdersOrderClaimsReq'
x-codegen:
method: createClaim
params: AdminPostOrdersOrderClaimsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.createClaim(orderId, {
type: 'refund',
claim_items: [
{
item_id,
quantity: 1
}
]
})
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCreateClaim } from "medusa-react"
type Props = {
orderId: string
}
const CreateClaim = ({ orderId }: Props) => {
const CreateClaim = (orderId: string) => {
const createClaim = useAdminCreateClaim(orderId)
// ...
const handleCreate = (itemId: string) => {
createClaim.mutate({
type: "refund",
claim_items: [
{
item_id: itemId,
quantity: 1,
},
],
}, {
onSuccess: ({ order }) => {
console.log(order.claims)
}
})
}
// ...
}
export default CreateClaim
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/claims' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"type": "refund",
"claim_items": [
{
"item_id": "asdsd",
"quantity": 1
}
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/claims/{claim_id}:
post:
operationId: PostOrdersOrderClaimsClaim
summary: Update a Claim
description: Update a Claim's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Order associated with the claim.
schema:
type: string
- in: path
name: claim_id
required: true
description: The ID of the Claim.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostOrdersOrderClaimsClaimReq'
x-codegen:
method: updateClaim
params: AdminPostOrdersOrderClaimsClaimParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.updateClaim(orderId, claimId, {
no_notification: true
})
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateClaim } from "medusa-react"
type Props = {
orderId: string
claimId: string
}
const Claim = ({ orderId, claimId }: Props) => {
const updateClaim = useAdminUpdateClaim(orderId)
// ...
const handleUpdate = () => {
updateClaim.mutate({
claim_id: claimId,
no_notification: false
}, {
onSuccess: ({ order }) => {
console.log(order.claims)
}
})
}
// ...
}
export default Claim
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/claims/{claim_id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"no_notification": true
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/claims/{claim_id}/cancel:
post:
operationId: PostOrdersClaimCancel
summary: Cancel a Claim
description: Cancel a Claim and change its status. A claim can't be canceled if it has a refund, if its fulfillments haven't been canceled, of if its associated return hasn't been canceled.
x-authenticated: true
externalDocs:
description: Canceling a claim
url: https://docs.medusajs.com/modules/orders/claims#cancel-a-claim
parameters:
- in: path
name: id
required: true
description: The ID of the order the claim is associated with.
schema:
type: string
- in: path
name: claim_id
required: true
description: The ID of the Claim.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
x-codegen:
method: cancelClaim
params: AdminPostOrdersClaimCancel
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.cancelClaim(orderId, claimId)
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCancelClaim } from "medusa-react"
type Props = {
orderId: string
claimId: string
}
const Claim = ({ orderId, claimId }: Props) => {
const cancelClaim = useAdminCancelClaim(orderId)
// ...
const handleCancel = () => {
cancelClaim.mutate(claimId)
}
// ...
}
export default Claim
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/claims/{claim_id}/cancel' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/claims/{claim_id}/fulfillments:
post:
operationId: PostOrdersOrderClaimsClaimFulfillments
summary: Create a Claim Fulfillment
description: Create a Fulfillment for a Claim, and change its fulfillment status to `partially_fulfilled` or `fulfilled` depending on whether all the items were fulfilled. It may also change the status to `requires_action` if any actions are required.
x-authenticated: true
externalDocs:
description: Fulfill a claim
url: https://docs.medusajs.com/modules/orders/claims#fulfill-a-claim
parameters:
- in: path
name: id
required: true
description: The ID of the Order the claim is associated with.
schema:
type: string
- in: path
name: claim_id
required: true
description: The ID of the Claim.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostOrdersOrderClaimsClaimFulfillmentsReq'
x-codegen:
method: fulfillClaim
params: AdminPostOrdersOrderClaimsClaimFulfillmentsReq
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.fulfillClaim(orderId, claimId, {
})
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminFulfillClaim } from "medusa-react"
type Props = {
orderId: string
claimId: string
}
const Claim = ({ orderId, claimId }: Props) => {
const fulfillClaim = useAdminFulfillClaim(orderId)
// ...
const handleFulfill = () => {
fulfillClaim.mutate({
claim_id: claimId,
}, {
onSuccess: ({ order }) => {
console.log(order.claims)
}
})
}
// ...
}
export default Claim
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/claims/{claim_id}/fulfillments' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/claims/{claim_id}/fulfillments/{fulfillment_id}/cancel:
post:
operationId: PostOrdersClaimFulfillmentsCancel
summary: Cancel Claim's Fulfillment
description: Cancel a claim's fulfillment and change its fulfillment status to `canceled`.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the order the claim is associated with.
schema:
type: string
- in: path
name: claim_id
required: true
description: The ID of the claim.
schema:
type: string
- in: path
name: fulfillment_id
required: true
description: The ID of the fulfillment.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
x-codegen:
method: cancelClaimFulfillment
params: AdminPostOrdersClaimFulfillmentsCancelParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.cancelClaimFulfillment(orderId, claimId, fulfillmentId)
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCancelClaimFulfillment } from "medusa-react"
type Props = {
orderId: string
claimId: string
}
const Claim = ({ orderId, claimId }: Props) => {
const cancelFulfillment = useAdminCancelClaimFulfillment(
orderId
)
// ...
const handleCancel = (fulfillmentId: string) => {
cancelFulfillment.mutate({
claim_id: claimId,
fulfillment_id: fulfillmentId,
}, {
onSuccess: ({ order }) => {
console.log(order.claims)
}
})
}
// ...
}
export default Claim
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/claims/{claim_id}/fulfillments/{fulfillment_id}/cancel' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/claims/{claim_id}/shipments:
post:
operationId: PostOrdersOrderClaimsClaimShipments
summary: Ship a Claim's Fulfillment
description: Create a shipment for the claim and mark its fulfillment as shipped. This changes the claim's fulfillment status to either `partially_shipped` or `shipped`, depending on whether all the items were shipped.
x-authenticated: true
externalDocs:
description: Fulfill a claim
url: https://docs.medusajs.com/modules/orders/claims#fulfill-a-claim
parameters:
- in: path
name: id
required: true
description: The ID of the Order the claim is associated with.
schema:
type: string
- in: path
name: claim_id
required: true
description: The ID of the Claim.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostOrdersOrderClaimsClaimShipmentsReq'
x-codegen:
method: createClaimShipment
params: AdminPostOrdersOrderClaimsClaimShipmentsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.createClaimShipment(orderId, claimId, {
fulfillment_id
})
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCreateClaimShipment } from "medusa-react"
type Props = {
orderId: string
claimId: string
}
const Claim = ({ orderId, claimId }: Props) => {
const createShipment = useAdminCreateClaimShipment(orderId)
// ...
const handleCreateShipment = (fulfillmentId: string) => {
createShipment.mutate({
claim_id: claimId,
fulfillment_id: fulfillmentId,
}, {
onSuccess: ({ order }) => {
console.log(order.claims)
}
})
}
// ...
}
export default Claim
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/claims/{claim_id}/shipments' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"fulfillment_id": "{fulfillment_id}"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/complete:
post:
operationId: PostOrdersOrderComplete
summary: Complete an Order
description: Complete an Order and change its status. A canceled order can't be completed.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Order.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
x-codegen:
method: complete
params: AdminPostOrdersOrderCompleteParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.complete(orderId)
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCompleteOrder } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const completeOrder = useAdminCompleteOrder(
orderId
)
// ...
const handleComplete = () => {
completeOrder.mutate(void 0, {
onSuccess: ({ order }) => {
console.log(order.status)
}
})
}
// ...
}
export default Order
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/complete' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/fulfillment:
post:
operationId: PostOrdersOrderFulfillments
summary: Create a Fulfillment
description: Create a Fulfillment of an Order using the fulfillment provider, and change the order's fulfillment status to either `partially_fulfilled` or `fulfilled`, depending on whether all the items were fulfilled.
x-authenticated: true
externalDocs:
description: Fulfillments of orders
url: https://docs.medusajs.com/modules/orders/#fulfillments-in-orders
parameters:
- in: path
name: id
required: true
description: The ID of the Order.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostOrdersOrderFulfillmentsReq'
x-codegen:
method: createFulfillment
params: AdminPostOrdersOrderFulfillmentsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.createFulfillment(orderId, {
items: [
{
item_id,
quantity: 1
}
]
})
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCreateFulfillment } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const createFulfillment = useAdminCreateFulfillment(
orderId
)
// ...
const handleCreateFulfillment = (
itemId: string,
quantity: number
) => {
createFulfillment.mutate({
items: [
{
item_id: itemId,
quantity,
},
],
}, {
onSuccess: ({ order }) => {
console.log(order.fulfillments)
}
})
}
// ...
}
export default Order
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/fulfillment' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"items": [
{
"item_id": "{item_id}",
"quantity": 1
}
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/fulfillments/{fulfillment_id}/cancel:
post:
operationId: PostOrdersOrderFulfillmentsCancel
summary: Cancel a Fulfilmment
description: Cancel an order's fulfillment and change its fulfillment status to `canceled`.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Order.
schema:
type: string
- in: path
name: fulfillment_id
required: true
description: The ID of the Fulfillment.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
x-codegen:
method: cancelFulfillment
params: AdminPostOrdersOrderFulfillementsCancelParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.cancelFulfillment(orderId, fulfillmentId)
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCancelFulfillment } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const cancelFulfillment = useAdminCancelFulfillment(
orderId
)
// ...
const handleCancel = (
fulfillmentId: string
) => {
cancelFulfillment.mutate(fulfillmentId, {
onSuccess: ({ order }) => {
console.log(order.fulfillments)
}
})
}
// ...
}
export default Order
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/fulfillments/{fulfillment_id}/cancel' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/line-items/{line_item_id}/reserve:
post:
operationId: PostOrdersOrderLineItemReservations
summary: Create a Reservation
description: Create a Reservation for a line item at a specified location, optionally for a partial quantity.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Order.
schema:
type: string
- in: path
name: line_item_id
required: true
description: The ID of the Line item.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersOrderLineItemReservationReq'
x-codeSamples:
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/line-items/{line_item_id}/reserve' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"location_id": "loc_1"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostReservationsReq'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/refund:
post:
operationId: PostOrdersOrderRefunds
summary: Create a Refund
description: Refund an amount for an order. The amount must be less than or equal the `refundable_amount` of the order.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Order.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostOrdersOrderRefundsReq'
x-codegen:
method: refundPayment
params: AdminPostOrdersOrderRefundsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.refundPayment(orderId, {
amount: 1000,
reason: "Do not like it"
})
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminRefundPayment } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const refundPayment = useAdminRefundPayment(
orderId
)
// ...
const handleRefund = (
amount: number,
reason: string
) => {
refundPayment.mutate({
amount,
reason,
}, {
onSuccess: ({ order }) => {
console.log(order.refunds)
}
})
}
// ...
}
export default Order
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/adasda/refund' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"amount": 1000,
"reason": "Do not like it"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/reservations:
get:
operationId: GetOrdersOrderReservations
summary: Get Order Reservations
description: Retrieve the list of reservations of an Order
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Order.
schema:
type: string
- in: query
name: offset
description: The number of reservations to skip when retrieving the reservations.
schema:
type: integer
default: 0
- in: query
name: limit
description: Limit the number of reservations returned.
schema:
type: integer
default: 20
x-codeSamples:
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/orders/{id}/reservations' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminReservationsListRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/return:
post:
operationId: PostOrdersOrderReturns
summary: Request a Return
description: Request and create a Return for items in an order. If the return shipping method is specified, it will be automatically fulfilled.
x-authenticated: true
externalDocs:
description: Return creation process
url: https://docs.medusajs.com/modules/orders/returns#returns-process
parameters:
- in: path
name: id
required: true
description: The ID of the Order.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostOrdersOrderReturnsReq'
x-codegen:
method: requestReturn
params: AdminPostOrdersOrderReturnsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.requestReturn(orderId, {
items: [
{
item_id,
quantity: 1
}
]
})
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminRequestReturn } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const requestReturn = useAdminRequestReturn(
orderId
)
// ...
const handleRequestingReturn = (
itemId: string,
quantity: number
) => {
requestReturn.mutate({
items: [
{
item_id: itemId,
quantity
}
]
}, {
onSuccess: ({ order }) => {
console.log(order.returns)
}
})
}
// ...
}
export default Order
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/return' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"items": [
{
"item_id": "{item_id}",
"quantity": 1
}
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/shipment:
post:
operationId: PostOrdersOrderShipment
summary: Ship a Fulfillment
description: Create a shipment and mark a fulfillment as shipped. This changes the order's fulfillment status to either `partially_shipped` or `shipped`, depending on whether all the items were shipped.
x-authenticated: true
externalDocs:
description: Fulfillments of orders
url: https://docs.medusajs.com/modules/orders/#fulfillments-in-orders
parameters:
- in: path
name: id
required: true
description: The ID of the Order.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostOrdersOrderShipmentReq'
x-codegen:
method: createShipment
params: AdminPostOrdersOrderShipmentParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.createShipment(order_id, {
fulfillment_id
})
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCreateShipment } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const createShipment = useAdminCreateShipment(
orderId
)
// ...
const handleCreate = (
fulfillmentId: string
) => {
createShipment.mutate({
fulfillment_id: fulfillmentId,
}, {
onSuccess: ({ order }) => {
console.log(order.fulfillment_status)
}
})
}
// ...
}
export default Order
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/shipment' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"fulfillment_id": "{fulfillment_id}"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/shipping-methods:
post:
operationId: PostOrdersOrderShippingMethods
summary: Add a Shipping Method
description: Add a Shipping Method to an Order. If another Shipping Method exists with the same Shipping Profile, the previous Shipping Method will be replaced.
parameters:
- in: path
name: id
required: true
description: The ID of the Order.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostOrdersOrderShippingMethodsReq'
x-authenticated: true
x-codegen:
method: addShippingMethod
params: AdminPostOrdersOrderShippingMethodsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.addShippingMethod(orderId, {
price: 1000,
option_id
})
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminAddShippingMethod } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const addShippingMethod = useAdminAddShippingMethod(
orderId
)
// ...
const handleAddShippingMethod = (
optionId: string,
price: number
) => {
addShippingMethod.mutate({
option_id: optionId,
price
}, {
onSuccess: ({ order }) => {
console.log(order.shipping_methods)
}
})
}
// ...
}
export default Order
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/shipping-methods' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"price": 1000,
"option_id": "{option_id}"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/swaps:
post:
operationId: PostOrdersOrderSwaps
summary: Create a Swap
description: Create a Swap. This includes creating a return that is associated with the swap.
x-authenticated: true
externalDocs:
description: How are swaps created
url: https://docs.medusajs.com/modules/orders/swaps#how-are-swaps-created
parameters:
- in: path
name: id
required: true
description: The ID of the Order.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostOrdersOrderSwapsReq'
x-codegen:
method: createSwap
queryParams: AdminPostOrdersOrderSwapsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.createSwap(orderId, {
return_items: [
{
item_id,
quantity: 1
}
]
})
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCreateSwap } from "medusa-react"
type Props = {
orderId: string
}
const CreateSwap = ({ orderId }: Props) => {
const createSwap = useAdminCreateSwap(orderId)
// ...
const handleCreate = (
returnItems: {
item_id: string,
quantity: number
}[]
) => {
createSwap.mutate({
return_items: returnItems
}, {
onSuccess: ({ order }) => {
console.log(order.swaps)
}
})
}
// ...
}
export default CreateSwap
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/swaps' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"return_items": [
{
"item_id": "asfasf",
"quantity": 1
}
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/swaps/{swap_id}/cancel:
post:
operationId: PostOrdersSwapCancel
summary: Cancel a Swap
description: Cancel a Swap and change its status.
x-authenticated: true
externalDocs:
description: Canceling a swap
url: https://docs.medusajs.com/modules/orders/swaps#canceling-a-swap
parameters:
- in: path
name: id
required: true
description: The ID of the Order the swap is associated with.
schema:
type: string
- in: path
name: swap_id
required: true
description: The ID of the Swap.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
x-codegen:
method: cancelSwap
params: AdminPostOrdersSwapCancelParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.cancelSwap(orderId, swapId)
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCancelSwap } from "medusa-react"
type Props = {
orderId: string,
swapId: string
}
const Swap = ({
orderId,
swapId
}: Props) => {
const cancelSwap = useAdminCancelSwap(
orderId
)
// ...
const handleCancel = () => {
cancelSwap.mutate(swapId, {
onSuccess: ({ order }) => {
console.log(order.swaps)
}
})
}
// ...
}
export default Swap
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{order_id}/swaps/{swap_id}/cancel' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/swaps/{swap_id}/fulfillments:
post:
operationId: PostOrdersOrderSwapsSwapFulfillments
summary: Create a Swap Fulfillment
description: Create a Fulfillment for a Swap and change its fulfillment status to `fulfilled`. If it requires any additional actions, its fulfillment status may change to `requires_action`.
x-authenticated: true
externalDocs:
description: Handling a swap's fulfillment
url: https://docs.medusajs.com/modules/orders/swaps#handling-swap-fulfillment
parameters:
- in: path
name: id
required: true
description: The ID of the Order the swap is associated with.
schema:
type: string
- in: path
name: swap_id
required: true
description: The ID of the Swap.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostOrdersOrderSwapsSwapFulfillmentsReq'
x-codegen:
method: fulfillSwap
params: AdminPostOrdersOrderSwapsSwapFulfillmentsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.fulfillSwap(orderId, swapId, {
})
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminFulfillSwap } from "medusa-react"
type Props = {
orderId: string,
swapId: string
}
const Swap = ({
orderId,
swapId
}: Props) => {
const fulfillSwap = useAdminFulfillSwap(
orderId
)
// ...
const handleFulfill = () => {
fulfillSwap.mutate({
swap_id: swapId,
}, {
onSuccess: ({ order }) => {
console.log(order.swaps)
}
})
}
// ...
}
export default Swap
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/swaps/{swap_id}/fulfillments' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/swaps/{swap_id}/fulfillments/{fulfillment_id}/cancel:
post:
operationId: PostOrdersSwapFulfillmentsCancel
summary: Cancel Swap's Fulfilmment
description: Cancel a swap's fulfillment and change its fulfillment status to `canceled`.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the order the swap is associated with.
schema:
type: string
- in: path
name: swap_id
required: true
description: The ID of the swap.
schema:
type: string
- in: path
name: fulfillment_id
required: true
description: The ID of the fulfillment.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
x-codegen:
method: cancelSwapFulfillment
params: AdminPostOrdersSwapFulfillementsCancelParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.cancelSwapFulfillment(orderId, swapId, fulfillmentId)
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCancelSwapFulfillment } from "medusa-react"
type Props = {
orderId: string,
swapId: string
}
const Swap = ({
orderId,
swapId
}: Props) => {
const cancelFulfillment = useAdminCancelSwapFulfillment(
orderId
)
// ...
const handleCancelFulfillment = (
fulfillmentId: string
) => {
cancelFulfillment.mutate({
swap_id: swapId,
fulfillment_id: fulfillmentId,
})
}
// ...
}
export default Swap
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/swaps/{swap_id}/fulfillments/{fulfillment_id}/cancel' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/swaps/{swap_id}/process-payment:
post:
operationId: PostOrdersOrderSwapsSwapProcessPayment
summary: Process a Swap Payment
description: Process a swap's payment either by refunding or issuing a payment. This depends on the `difference_due` of the swap. If `difference_due` is negative, the amount is refunded. If `difference_due` is positive, the amount is captured.
x-authenticated: true
externalDocs:
description: Handling a swap's payment
url: https://docs.medusajs.com/modules/orders/swaps#handling-swap-payment
parameters:
- in: path
name: id
required: true
description: The ID of the order the swap is associated with.
schema:
type: string
- in: path
name: swap_id
required: true
description: The ID of the swap.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
x-codegen:
method: processSwapPayment
params: AdminPostOrdersOrderSwapsSwapProcessPaymentParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.processSwapPayment(orderId, swapId)
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminProcessSwapPayment } from "medusa-react"
type Props = {
orderId: string,
swapId: string
}
const Swap = ({
orderId,
swapId
}: Props) => {
const processPayment = useAdminProcessSwapPayment(
orderId
)
// ...
const handleProcessPayment = () => {
processPayment.mutate(swapId, {
onSuccess: ({ order }) => {
console.log(order.swaps)
}
})
}
// ...
}
export default Swap
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/swaps/{swap_id}/process-payment' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/orders/{id}/swaps/{swap_id}/shipments:
post:
operationId: PostOrdersOrderSwapsSwapShipments
summary: Ship a Swap's Fulfillment
description: Create a shipment for a swap and mark its fulfillment as shipped. This changes the swap's fulfillment status to either `partially_shipped` or `shipped`, depending on whether all the items were shipped.
x-authenticated: true
externalDocs:
description: Handling swap fulfillments
url: https://docs.medusajs.com/modules/orders/swaps#handling-swap-fulfillment
parameters:
- in: path
name: id
required: true
description: The ID of the Order.
schema:
type: string
- in: path
name: swap_id
required: true
description: The ID of the Swap.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned order.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostOrdersOrderSwapsSwapShipmentsReq'
x-codegen:
method: createSwapShipment
params: AdminPostOrdersOrderSwapsSwapShipmentsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.orders.createSwapShipment(orderId, swapId, {
fulfillment_id
})
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCreateSwapShipment } from "medusa-react"
type Props = {
orderId: string,
swapId: string
}
const Swap = ({
orderId,
swapId
}: Props) => {
const createShipment = useAdminCreateSwapShipment(
orderId
)
// ...
const handleCreateShipment = (
fulfillmentId: string
) => {
createShipment.mutate({
swap_id: swapId,
fulfillment_id: fulfillmentId,
}, {
onSuccess: ({ order }) => {
console.log(order.swaps)
}
})
}
// ...
}
export default Swap
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/orders/{id}/swaps/{swap_id}/shipments' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"fulfillment_id": "{fulfillment_id}"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/payment-collections/{id}:
get:
operationId: GetPaymentCollectionsPaymentCollection
summary: Get a Payment Collection
description: Retrieve a Payment Collection's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Payment Collection.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned payment collection.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned payment collection.
schema:
type: string
x-codegen:
method: retrieve
queryParams: AdminGetPaymentCollectionsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.paymentCollections.retrieve(paymentCollectionId)
.then(({ payment_collection }) => {
console.log(payment_collection.id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminPaymentCollection } from "medusa-react"
type Props = {
paymentCollectionId: string
}
const PaymentCollection = ({ paymentCollectionId }: Props) => {
const {
payment_collection,
isLoading,
} = useAdminPaymentCollection(paymentCollectionId)
return (
{isLoading && Loading...}
{payment_collection && (
{payment_collection.status}
)}
)
}
export default PaymentCollection
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/payment-collections/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Payment Collections
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPaymentCollectionsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostPaymentCollectionsPaymentCollection
summary: Update Payment Collection
description: Update a Payment Collection's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Payment Collection.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminUpdatePaymentCollectionsReq'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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.paymentCollections.update(paymentCollectionId, {
description
})
.then(({ payment_collection }) => {
console.log(payment_collection.id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdatePaymentCollection } from "medusa-react"
type Props = {
paymentCollectionId: string
}
const PaymentCollection = ({ paymentCollectionId }: Props) => {
const updateCollection = useAdminUpdatePaymentCollection(
paymentCollectionId
)
// ...
const handleUpdate = (
description: string
) => {
updateCollection.mutate({
description
}, {
onSuccess: ({ payment_collection }) => {
console.log(payment_collection.description)
}
})
}
// ...
}
export default PaymentCollection
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/payment-collections/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"description": "Description of payment collection"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Payment Collections
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPaymentCollectionsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeletePaymentCollectionsPaymentCollection
summary: Delete a Payment Collection
description: Delete a Payment Collection. Only payment collections with the statuses `canceled` or `not_paid` can be deleted.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Payment Collection.
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.paymentCollections.delete(paymentCollectionId)
.then(({ id, object, deleted }) => {
console.log(id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeletePaymentCollection } from "medusa-react"
type Props = {
paymentCollectionId: string
}
const PaymentCollection = ({ paymentCollectionId }: Props) => {
const deleteCollection = useAdminDeletePaymentCollection(
paymentCollectionId
)
// ...
const handleDelete = () => {
deleteCollection.mutate(void 0, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
// ...
}
export default PaymentCollection
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/payment-collections/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Payment Collections
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPaymentCollectionDeleteRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
/admin/payment-collections/{id}/authorize:
post:
operationId: PostPaymentCollectionsPaymentCollectionAuthorize
summary: Mark Authorized
description: Set the status of a Payment Collection as `authorized`. This will also change the `authorized_amount` of the payment collection.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Payment Collection.
schema:
type: string
x-codegen:
method: markAsAuthorized
x-codeSamples:
- lang: JavaScript
label: JS Client
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.paymentCollections.markAsAuthorized(paymentCollectionId)
.then(({ payment_collection }) => {
console.log(payment_collection.id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminMarkPaymentCollectionAsAuthorized } from "medusa-react"
type Props = {
paymentCollectionId: string
}
const PaymentCollection = ({ paymentCollectionId }: Props) => {
const markAsAuthorized = useAdminMarkPaymentCollectionAsAuthorized(
paymentCollectionId
)
// ...
const handleAuthorization = () => {
markAsAuthorized.mutate(void 0, {
onSuccess: ({ payment_collection }) => {
console.log(payment_collection.status)
}
})
}
// ...
}
export default PaymentCollection
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/payment-collections/{id}/authorize' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Payment Collections
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPaymentCollectionsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/payments/{id}:
get:
operationId: GetPaymentsPayment
summary: Get Payment details
description: Retrieve a Payment's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Payment.
schema:
type: string
x-codegen:
method: retrieve
queryParams: GetPaymentsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.payments.retrieve(paymentId)
.then(({ payment }) => {
console.log(payment.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminPayment } from "medusa-react"
type Props = {
paymentId: string
}
const Payment = ({ paymentId }: Props) => {
const {
payment,
isLoading,
} = useAdminPayment(paymentId)
return (
{isLoading && Loading...}
{payment && {payment.amount}}
)
}
export default Payment
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/payments/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Payments
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPaymentRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/payments/{id}/capture:
post:
operationId: PostPaymentsPaymentCapture
summary: Capture a Payment
description: Capture a Payment.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Payment.
schema:
type: string
x-codegen:
method: capturePayment
x-codeSamples:
- lang: JavaScript
label: JS Client
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.payments.capturePayment(paymentId)
.then(({ payment }) => {
console.log(payment.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminPaymentsCapturePayment } from "medusa-react"
type Props = {
paymentId: string
}
const Payment = ({ paymentId }: Props) => {
const capture = useAdminPaymentsCapturePayment(
paymentId
)
// ...
const handleCapture = () => {
capture.mutate(void 0, {
onSuccess: ({ payment }) => {
console.log(payment.amount)
}
})
}
// ...
}
export default Payment
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/payments/{id}/capture' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Payments
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPaymentRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/payments/{id}/refund:
post:
operationId: PostPaymentsPaymentRefunds
summary: Refund Payment
description: Refund a payment. The payment must be captured first.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Payment.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostPaymentRefundsReq'
x-codegen:
method: refundPayment
x-codeSamples:
- lang: JavaScript
label: JS Client
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.payments.refundPayment(paymentId, {
amount: 1000,
reason: "return",
note: "Do not like it",
})
.then(({ payment }) => {
console.log(payment.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { RefundReason } from "@medusajs/medusa"
import { useAdminPaymentsRefundPayment } from "medusa-react"
type Props = {
paymentId: string
}
const Payment = ({ paymentId }: Props) => {
const refund = useAdminPaymentsRefundPayment(
paymentId
)
// ...
const handleRefund = (
amount: number,
reason: RefundReason,
note: string
) => {
refund.mutate({
amount,
reason,
note
}, {
onSuccess: ({ refund }) => {
console.log(refund.amount)
}
})
}
// ...
}
export default Payment
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/payments/pay_123/refund' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"amount": 1000,
"reason": "return",
"note": "Do not like it"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Payments
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminRefundRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/price-lists:
get:
operationId: GetPriceLists
summary: List Price Lists
description: Retrieve a list of price lists. The price lists can be filtered by fields such as `q` or `status`. The price lists can also be sorted or paginated.
x-authenticated: true
parameters:
- in: query
name: limit
description: Limit the number of price lists returned.
schema:
type: number
default: '10'
- in: query
name: offset
description: The number of price lists to skip when retrieving the price lists.
schema:
type: number
default: '0'
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned price lists.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned price lists.
schema:
type: string
- in: query
name: order
description: A price-list field to sort-order the retrieved price lists by.
schema:
type: string
- in: query
name: id
description: Filter by ID
schema:
type: string
- in: query
name: q
description: term to search price lists' description, name, and customer group's name.
schema:
type: string
- in: query
name: status
style: form
explode: false
description: Filter by status.
schema:
type: array
items:
type: string
enum:
- active
- draft
- in: query
name: name
description: Filter by name
schema:
type: string
- in: query
name: customer_groups
style: form
explode: false
description: Filter by customer-group IDs.
schema:
type: array
items:
type: string
- in: query
name: type
style: form
explode: false
description: Filter by type.
schema:
type: array
items:
type: string
enum:
- sale
- override
- in: query
name: created_at
description: Filter by a creation date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: updated_at
description: Filter by an update date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: deleted_at
description: Filter by a deletion date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
x-codegen:
method: list
queryParams: AdminGetPriceListPaginationParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.priceLists.list()
.then(({ price_lists, limit, offset, count }) => {
console.log(price_lists.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminPriceLists } from "medusa-react"
const PriceLists = () => {
const { price_lists, isLoading } = useAdminPriceLists()
return (
{isLoading &&
Loading...}
{price_lists && !price_lists.length && (
No Price Lists
)}
{price_lists && price_lists.length > 0 && (
{price_lists.map((price_list) => (
- {price_list.name}
))}
)}
{isLoading && Loading...}
{price_list && {price_list.name}}
)
}
export default PriceList
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/price-lists/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Price Lists
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPriceListRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostPriceListsPriceListPriceList
summary: Update a Price List
description: Update a Price List's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Price List.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostPriceListsPriceListPriceListReq'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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.priceLists.update(priceListId, {
name: "New Price List"
})
.then(({ price_list }) => {
console.log(price_list.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdatePriceList } from "medusa-react"
type Props = {
priceListId: string
}
const PriceList = ({
priceListId
}: Props) => {
const updatePriceList = useAdminUpdatePriceList(priceListId)
// ...
const handleUpdate = (
endsAt: Date
) => {
updatePriceList.mutate({
ends_at: endsAt,
}, {
onSuccess: ({ price_list }) => {
console.log(price_list.ends_at)
}
})
}
// ...
}
export default PriceList
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/price-lists/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"name": "New Price List"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Price Lists
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPriceListRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeletePriceListsPriceList
summary: Delete a Price List
description: Delete a Price List and its associated prices.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Price List.
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.priceLists.delete(priceListId)
.then(({ id, object, deleted }) => {
console.log(id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeletePriceList } from "medusa-react"
type Props = {
priceListId: string
}
const PriceList = ({
priceListId
}: Props) => {
const deletePriceList = useAdminDeletePriceList(priceListId)
// ...
const handleDelete = () => {
deletePriceList.mutate(void 0, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
// ...
}
export default PriceList
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/price-lists/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Price Lists
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPriceListDeleteRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/price-lists/{id}/prices/batch:
post:
operationId: PostPriceListsPriceListPricesBatch
summary: Add or Update Prices
description: Add or update a list of prices in a Price List.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Price List.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostPriceListPricesPricesReq'
x-codegen:
method: addPrices
x-codeSamples:
- lang: JavaScript
label: JS Client
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.priceLists.addPrices(priceListId, {
prices: [
{
amount: 1000,
variant_id,
currency_code: "eur"
}
]
})
.then(({ price_list }) => {
console.log(price_list.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCreatePriceListPrices } from "medusa-react"
type PriceData = {
amount: number
variant_id: string
currency_code: string
}
type Props = {
priceListId: string
}
const PriceList = ({
priceListId
}: Props) => {
const addPrices = useAdminCreatePriceListPrices(priceListId)
// ...
const handleAddPrices = (prices: PriceData[]) => {
addPrices.mutate({
prices
}, {
onSuccess: ({ price_list }) => {
console.log(price_list.prices)
}
})
}
// ...
}
export default PriceList
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/price-lists/{id}/prices/batch' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"prices": [
{
"amount": 100,
"variant_id": "afasfa",
"currency_code": "eur"
}
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Price Lists
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPriceListRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeletePriceListsPriceListPricesBatch
summary: Delete Prices
description: Delete a list of prices in a Price List
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Price List
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDeletePriceListPricesPricesReq'
x-codegen:
method: deletePrices
x-codeSamples:
- lang: JavaScript
label: JS Client
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.priceLists.deletePrices(priceListId, {
price_ids: [
price_id
]
})
.then(({ ids, object, deleted }) => {
console.log(ids.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeletePriceListPrices } from "medusa-react"
const PriceList = (
priceListId: string
) => {
const deletePrices = useAdminDeletePriceListPrices(priceListId)
// ...
const handleDeletePrices = (priceIds: string[]) => {
deletePrices.mutate({
price_ids: priceIds
}, {
onSuccess: ({ ids, deleted, object }) => {
console.log(ids)
}
})
}
// ...
}
export default PriceList
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/price-lists/{id}/prices/batch' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"price_ids": [
"adasfa"
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Price Lists
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPriceListDeleteBatchRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/price-lists/{id}/products:
get:
operationId: GetPriceListsPriceListProducts
summary: List Products
description: Retrieve a price list's products. The products can be filtered by fields such as `q` or `status`. The products can also be sorted or paginated.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: ID of the price list.
schema:
type: string
- in: query
name: q
description: term used to search products' title, description, product variant's title and sku, and product collection's title.
schema:
type: string
- in: query
name: id
style: form
explode: false
description: Filter by product IDs.
schema:
oneOf:
- type: string
description: ID of the product.
- type: array
items:
type: string
description: ID of a product.
- in: query
name: status
description: Filter by product status
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- draft
- proposed
- published
- rejected
- in: query
name: collection_id
description: Filter by product collection ID. Only products in the specified collections are retrieved.
style: form
explode: false
schema:
type: array
items:
type: string
- in: query
name: tags
description: Filter by tag IDs. Only products having the specified tags are retrieved.
style: form
explode: false
schema:
type: array
items:
type: string
- in: query
name: title
description: Filter by title
schema:
type: string
- in: query
name: description
description: Filter by description
schema:
type: string
- in: query
name: handle
description: Filter by handle
schema:
type: string
- in: query
name: is_giftcard
description: A boolean value to filter by whether the product is a gift card or not.
schema:
type: boolean
- in: query
name: type
description: Filter product type.
schema:
type: string
- in: query
name: order
description: A product field to sort-order the retrieved products by.
schema:
type: string
- in: query
name: created_at
description: Filter by a creation date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: updated_at
description: Filter by an update date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: deleted_at
description: Filter by a deletion date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: offset
description: The number of products to skip when retrieving the products.
schema:
type: integer
default: 0
- in: query
name: limit
description: Limit the number of products returned.
schema:
type: integer
default: 50
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned products.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned products.
schema:
type: string
x-codegen:
method: listProducts
queryParams: AdminGetPriceListsPriceListProductsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.priceLists.listProducts(priceListId)
.then(({ products, limit, offset, count }) => {
console.log(products.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminPriceListProducts } from "medusa-react"
type Props = {
priceListId: string
}
const PriceListProducts = ({
priceListId
}: Props) => {
const { products, isLoading } = useAdminPriceListProducts(
priceListId
)
return (
{isLoading &&
Loading...}
{products && !products.length && (
No Price Lists
)}
{products && products.length > 0 && (
{products.map((product) => (
- {product.title}
))}
)}
{isLoading &&
Loading...}
{product_categories && !product_categories.length && (
No Categories
)}
{product_categories && product_categories.length > 0 && (
{product_categories.map(
(category) => (
- {category.name}
)
)}
)}
{isLoading && Loading...}
{product_category && (
{product_category.name}
)}
)
}
export default Category
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/product-categories/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Product Categories
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminProductCategoriesCategoryRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostProductCategoriesCategory
summary: Update a Product Category
description: Updates a Product Category.
x-authenticated: true
x-featureFlag: product_categories
parameters:
- in: path
name: id
required: true
description: The ID of the Product Category.
schema:
type: string
- in: query
name: expand
description: (Comma separated) Which fields should be expanded in each product category.
schema:
type: string
- in: query
name: fields
description: (Comma separated) Which fields should be retrieved in each product category.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostProductCategoriesCategoryReq'
x-codegen:
method: update
queryParams: AdminPostProductCategoriesCategoryParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.productCategories.update(productCategoryId, {
name: "Skinny Jeans"
})
.then(({ product_category }) => {
console.log(product_category.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateProductCategory } from "medusa-react"
type Props = {
productCategoryId: string
}
const Category = ({
productCategoryId
}: Props) => {
const updateCategory = useAdminUpdateProductCategory(
productCategoryId
)
// ...
const handleUpdate = (
name: string
) => {
updateCategory.mutate({
name,
}, {
onSuccess: ({ product_category }) => {
console.log(product_category.id)
}
})
}
// ...
}
export default Category
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/product-categories/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"name": "Skinny Jeans"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Product Categories
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminProductCategoriesCategoryRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteProductCategoriesCategory
summary: Delete a Product Category
description: Delete a Product Category. This does not delete associated products.
x-authenticated: true
x-featureFlag: product_categories
parameters:
- in: path
name: id
required: true
description: The ID of the Product Category
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.productCategories.delete(productCategoryId)
.then(({ id, object, deleted }) => {
console.log(id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteProductCategory } from "medusa-react"
type Props = {
productCategoryId: string
}
const Category = ({
productCategoryId
}: Props) => {
const deleteCategory = useAdminDeleteProductCategory(
productCategoryId
)
// ...
const handleDelete = () => {
deleteCategory.mutate(void 0, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
// ...
}
export default Category
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/product-categories/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Product Categories
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminProductCategoriesCategoryDeleteRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/product-categories/{id}/products/batch:
post:
operationId: PostProductCategoriesCategoryProductsBatch
summary: Add Products to a Category
description: Add a list of products to a product category.
x-authenticated: true
x-featureFlag: product_categories
parameters:
- in: path
name: id
required: true
description: The ID of the Product Category.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned product category.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned product category.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostProductCategoriesCategoryProductsBatchReq'
x-codegen:
method: addProducts
queryParams: AdminPostProductCategoriesCategoryProductsBatchParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.productCategories.addProducts(productCategoryId, {
product_ids: [
{
id: productId
}
]
})
.then(({ product_category }) => {
console.log(product_category.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminAddProductsToCategory } from "medusa-react"
type ProductsData = {
id: string
}
type Props = {
productCategoryId: string
}
const Category = ({
productCategoryId
}: Props) => {
const addProducts = useAdminAddProductsToCategory(
productCategoryId
)
// ...
const handleAddProducts = (
productIds: ProductsData[]
) => {
addProducts.mutate({
product_ids: productIds
}, {
onSuccess: ({ product_category }) => {
console.log(product_category.products)
}
})
}
// ...
}
export default Category
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/product-categories/{id}/products/batch' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"product_ids": [
{
"id": "{product_id}"
}
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Product Categories
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminProductCategoriesCategoryRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteProductCategoriesCategoryProductsBatch
summary: Remove Products from Category
description: Remove a list of products from a product category.
x-authenticated: true
x-featureFlag: product_categories
parameters:
- in: path
name: id
required: true
description: The ID of the Product Category.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned product category.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned product category.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDeleteProductCategoriesCategoryProductsBatchReq'
x-codegen:
method: removeProducts
queryParams: AdminDeleteProductCategoriesCategoryProductsBatchParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.productCategories.removeProducts(productCategoryId, {
product_ids: [
{
id: productId
}
]
})
.then(({ product_category }) => {
console.log(product_category.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteProductsFromCategory } from "medusa-react"
type ProductsData = {
id: string
}
type Props = {
productCategoryId: string
}
const Category = ({
productCategoryId
}: Props) => {
const deleteProducts = useAdminDeleteProductsFromCategory(
productCategoryId
)
// ...
const handleDeleteProducts = (
productIds: ProductsData[]
) => {
deleteProducts.mutate({
product_ids: productIds
}, {
onSuccess: ({ product_category }) => {
console.log(product_category.products)
}
})
}
// ...
}
export default Category
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/product-categories/{id}/products/batch' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"product_ids": [
{
"id": "{product_id}"
}
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Product Categories
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminProductCategoriesCategoryRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/product-tags:
get:
operationId: GetProductTags
summary: List Product Tags
description: Retrieve a list of product tags. The product tags can be filtered by fields such as `q` or `value`. The product tags can also be sorted or paginated.
x-authenticated: true
parameters:
- in: query
name: limit
description: Limit the number of product tags returned.
schema:
type: integer
default: 10
- in: query
name: offset
description: The number of product tags to skip when retrieving the product tags.
schema:
type: integer
default: 0
- in: query
name: order
description: A product tag field to sort-order the retrieved product tags by.
schema:
type: string
- in: query
name: discount_condition_id
description: Filter by the ID of a discount condition. Only product tags that this discount condition is applied to will be retrieved.
schema:
type: string
- in: query
name: value
style: form
explode: false
description: Filter by tag value.
schema:
type: array
items:
type: string
- in: query
name: q
description: term to search product tags' values.
schema:
type: string
- in: query
name: id
style: form
explode: false
description: Filter by tag IDs.
schema:
type: array
items:
type: string
- in: query
name: created_at
description: Filter by a creation date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: updated_at
description: Filter by an update date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
x-codegen:
method: list
queryParams: AdminGetProductTagsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.productTags.list()
.then(({ product_tags }) => {
console.log(product_tags.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminProductTags } from "medusa-react"
function ProductTags() {
const {
product_tags,
isLoading
} = useAdminProductTags()
return (
{isLoading &&
Loading...}
{product_tags && !product_tags.length && (
No Product Tags
)}
{product_tags && product_tags.length > 0 && (
{product_tags.map(
(tag) => (
- {tag.value}
)
)}
)}
{isLoading &&
Loading...}
{product_types && !product_types.length && (
No Product Tags
)}
{product_types && product_types.length > 0 && (
{product_types.map(
(type) => (
- {type.value}
)
)}
)}
{isLoading &&
Loading...}
{products && !products.length &&
No Products}
{products && products.length > 0 && (
{products.map((product) => (
- {product.title}
))}
)}
{isLoading &&
Loading...}
{tags && !tags.length &&
No Product Tags}
{tags && tags.length > 0 && (
{tags.map((tag) => (
- {tag.value} - {tag.usage_count}
))}
)}
{isLoading && Loading...}
{product && {product.title}}
)
}
export default Product
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/products/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Products
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminProductsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostProductsProduct
summary: Update a Product
description: Update a Product's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Product.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostProductsProductReq'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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.update(productId, {
title: "Shirt",
})
.then(({ product }) => {
console.log(product.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateProduct } from "medusa-react"
type Props = {
productId: string
}
const Product = ({ productId }: Props) => {
const updateProduct = useAdminUpdateProduct(
productId
)
// ...
const handleUpdate = (
title: string
) => {
updateProduct.mutate({
title,
}, {
onSuccess: ({ product }) => {
console.log(product.id)
}
})
}
// ...
}
export default Product
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/products/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"title": "Size"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Products
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminProductsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteProductsProduct
summary: Delete a Product
description: Delete a Product and its associated product variants and options.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Product.
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.delete(productId)
.then(({ id, object, deleted }) => {
console.log(id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteProduct } from "medusa-react"
type Props = {
productId: string
}
const Product = ({ productId }: Props) => {
const deleteProduct = useAdminDeleteProduct(
productId
)
// ...
const handleDelete = () => {
deleteProduct.mutate(void 0, {
onSuccess: ({ id, object, deleted}) => {
console.log(id)
}
})
}
// ...
}
export default Product
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/products/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Products
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminProductsDeleteRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/products/{id}/metadata:
post:
operationId: PostProductsProductMetadata
summary: Set Metadata
description: Set the metadata of a Product. It can be any key-value pair, which allows adding custom data to a product.
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Product.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostProductsProductMetadataReq'
x-codegen:
method: setMetadata
x-codeSamples:
- lang: JavaScript
label: JS Client
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.setMetadata(productId, {
key: "test",
value: "true"
})
.then(({ product }) => {
console.log(product.id);
})
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/products/{id}/metadata' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"key": "test",
"value": "true"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Products
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminProductsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/products/{id}/options:
post:
operationId: PostProductsProductOptions
summary: Add a Product Option
description: Add a Product Option to a Product.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Product.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostProductsProductOptionsReq'
x-codegen:
method: addOption
x-codeSamples:
- lang: JavaScript
label: JS Client
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.addOption(productId, {
title: "Size"
})
.then(({ product }) => {
console.log(product.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCreateProductOption } from "medusa-react"
type Props = {
productId: string
}
const CreateProductOption = ({ productId }: Props) => {
const createOption = useAdminCreateProductOption(
productId
)
// ...
const handleCreate = (
title: string
) => {
createOption.mutate({
title
}, {
onSuccess: ({ product }) => {
console.log(product.options)
}
})
}
// ...
}
export default CreateProductOption
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/products/{id}/options' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"title": "Size"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Products
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminProductsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/products/{id}/options/{option_id}:
post:
operationId: PostProductsProductOptionsOption
summary: Update a Product Option
description: Update a Product Option's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Product.
schema:
type: string
- in: path
name: option_id
required: true
description: The ID of the Product Option.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostProductsProductOptionsOption'
x-codegen:
method: updateOption
x-codeSamples:
- lang: JavaScript
label: JS Client
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.updateOption(productId, optionId, {
title: "Size"
})
.then(({ product }) => {
console.log(product.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateProductOption } from "medusa-react"
type Props = {
productId: string
optionId: string
}
const ProductOption = ({
productId,
optionId
}: Props) => {
const updateOption = useAdminUpdateProductOption(
productId
)
// ...
const handleUpdate = (
title: string
) => {
updateOption.mutate({
option_id: optionId,
title,
}, {
onSuccess: ({ product }) => {
console.log(product.options)
}
})
}
// ...
}
export default ProductOption
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/products/{id}/options/{option_id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"title": "Size"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Products
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminProductsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteProductsProductOptionsOption
summary: Delete a Product Option
description: Delete a Product Option. If there are product variants that use this product option, they must be deleted before deleting the product option.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Product.
schema:
type: string
- in: path
name: option_id
required: true
description: The ID of the Product Option.
schema:
type: string
x-codegen:
method: deleteOption
x-codeSamples:
- lang: JavaScript
label: JS Client
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.deleteOption(productId, optionId)
.then(({ option_id, object, deleted, product }) => {
console.log(product.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteProductOption } from "medusa-react"
type Props = {
productId: string
optionId: string
}
const ProductOption = ({
productId,
optionId
}: Props) => {
const deleteOption = useAdminDeleteProductOption(
productId
)
// ...
const handleDelete = () => {
deleteOption.mutate(optionId, {
onSuccess: ({ option_id, object, deleted, product }) => {
console.log(product.options)
}
})
}
// ...
}
export default ProductOption
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/products/{id}/options/{option_id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Products
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminProductsDeleteOptionRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/products/{id}/variants:
get:
operationId: GetProductsProductVariants
summary: List a Product's Variants
description: |
Retrieve a list of Product Variants associated with a Product. The variants can be paginated.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: ID of the product.
schema:
type: string
- in: query
name: id
description: IDs to filter product variants by.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned product variants.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned product variants.
schema:
type: string
- in: query
name: offset
description: The number of product variants to skip when retrieving the product variants.
schema:
type: integer
default: 0
- in: query
name: limit
description: Limit the number of product variants returned.
schema:
type: integer
default: 100
- in: query
name: q
description: Search term to search product variants' title, sku, and products' title.
schema:
type: string
- in: query
name: order
description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
schema:
type: string
- in: query
name: manage_inventory
description: Filter product variants by whether their inventory is managed or not.
schema:
type: boolean
- in: query
name: allow_backorder
description: Filter product variants by whether they are allowed to be backordered or not.
schema:
type: boolean
- in: query
name: created_at
description: Filter by a creation date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: updated_at
description: Filter by an update date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
x-codegen:
method: listVariants
queryParams: AdminGetProductsVariantsParams
x-codeSamples:
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/products/{id}/variants' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Products
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminProductsListVariantsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostProductsProductVariants
summary: Create a Product Variant
description: Create a Product Variant associated with a Product. Each product variant must have a unique combination of Product Option values.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Product.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostProductsProductVariantsReq'
x-codegen:
method: createVariant
x-codeSamples:
- lang: JavaScript
label: JS Client
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.createVariant(productId, {
title: "Color",
prices: [
{
amount: 1000,
currency_code: "eur"
}
],
options: [
{
option_id,
value: "S"
}
],
inventory_quantity: 100
})
.then(({ product }) => {
console.log(product.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCreateVariant } from "medusa-react"
type CreateVariantData = {
title: string
prices: {
amount: number
currency_code: string
}[]
options: {
option_id: string
value: string
}[]
}
type Props = {
productId: string
}
const CreateProductVariant = ({ productId }: Props) => {
const createVariant = useAdminCreateVariant(
productId
)
// ...
const handleCreate = (
variantData: CreateVariantData
) => {
createVariant.mutate(variantData, {
onSuccess: ({ product }) => {
console.log(product.variants)
}
})
}
// ...
}
export default CreateProductVariant
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/products/{id}/variants' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"title": "Color",
"prices": [
{
"amount": 1000,
"currency_code": "eur"
}
],
"options": [
{
"option_id": "asdasf",
"value": "S"
}
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Products
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminProductsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/products/{id}/variants/{variant_id}:
post:
operationId: PostProductsProductVariantsVariant
summary: Update a Product Variant
description: Update a Product Variant's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Product.
schema:
type: string
- in: path
name: variant_id
required: true
description: The ID of the Product Variant.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostProductsProductVariantsVariantReq'
x-codegen:
method: updateVariant
x-codeSamples:
- lang: JavaScript
label: JS Client
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.updateVariant(productId, variantId, {
title: "Color",
prices: [
{
amount: 1000,
currency_code: "eur"
}
],
options: [
{
option_id,
value: "S"
}
],
inventory_quantity: 100
})
.then(({ product }) => {
console.log(product.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateVariant } from "medusa-react"
type Props = {
productId: string
variantId: string
}
const ProductVariant = ({
productId,
variantId
}: Props) => {
const updateVariant = useAdminUpdateVariant(
productId
)
// ...
const handleUpdate = (title: string) => {
updateVariant.mutate({
variant_id: variantId,
title,
}, {
onSuccess: ({ product }) => {
console.log(product.variants)
}
})
}
// ...
}
export default ProductVariant
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/products/{id}/variants/{variant_id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"title": "Color",
"prices": [
{
"amount": 1000,
"currency_code": "eur"
}
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Products
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminProductsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteProductsProductVariantsVariant
summary: Delete a Product Variant
description: Delete a Product Variant.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Product.
schema:
type: string
- in: path
name: variant_id
required: true
description: The ID of the Product Variant.
schema:
type: string
x-codegen:
method: deleteVariant
x-codeSamples:
- lang: JavaScript
label: JS Client
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.deleteVariant(productId, variantId)
.then(({ variant_id, object, deleted, product }) => {
console.log(product.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteVariant } from "medusa-react"
type Props = {
productId: string
variantId: string
}
const ProductVariant = ({
productId,
variantId
}: Props) => {
const deleteVariant = useAdminDeleteVariant(
productId
)
// ...
const handleDelete = () => {
deleteVariant.mutate(variantId, {
onSuccess: ({ variant_id, object, deleted, product }) => {
console.log(product.variants)
}
})
}
// ...
}
export default ProductVariant
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/products/{id}/variants/{variant_id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Products
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminProductsDeleteVariantRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/publishable-api-keys:
get:
operationId: GetPublishableApiKeys
summary: List Publishable API keys
description: Retrieve a list of publishable API keys. The publishable API keys can be filtered by fields such as `q`. The publishable API keys can also be paginated.
x-authenticated: true
parameters:
- in: query
name: q
description: term to search publishable API keys' titles.
schema:
type: string
- in: query
name: limit
description: Limit the number of publishable API keys returned.
schema:
type: number
default: '20'
- in: query
name: offset
description: The number of publishable API keys to skip when retrieving the publishable API keys.
schema:
type: number
default: '0'
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned publishable API keys.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned publishable API keys.
schema:
type: string
- in: query
name: order
description: A field to sort-order the retrieved publishable API keys by.
schema:
type: string
- in: query
name: created_at
required: false
description: Filter by a creation date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: updated_at
required: false
description: Filter by a update date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: revoked_at
required: false
description: Filter by a revocation date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
x-codegen:
method: list
queryParams: GetPublishableApiKeysParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.publishableApiKeys.list()
.then(({ publishable_api_keys, count, limit, offset }) => {
console.log(publishable_api_keys)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { PublishableApiKey } from "@medusajs/medusa"
import { useAdminPublishableApiKeys } from "medusa-react"
const PublishableApiKeys = () => {
const { publishable_api_keys, isLoading } =
useAdminPublishableApiKeys()
return (
{isLoading &&
Loading...}
{publishable_api_keys && !publishable_api_keys.length && (
No Publishable API Keys
)}
{publishable_api_keys &&
publishable_api_keys.length > 0 && (
{publishable_api_keys.map(
(publishableApiKey: PublishableApiKey) => (
-
{publishableApiKey.title}
)
)}
)}
{isLoading && Loading...}
{publishable_api_key && {publishable_api_key.title}}
)
}
export default PublishableApiKey
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/publishable-api-keys/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Publishable Api Keys
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPublishableApiKeysRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostPublishableApiKysPublishableApiKey
summary: Update Publishable API Key
description: Update a Publishable API Key's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Publishable API Key.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostPublishableApiKeysPublishableApiKeyReq'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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.publishableApiKeys.update(publishableApiKeyId, {
title: "new title"
})
.then(({ publishable_api_key }) => {
console.log(publishable_api_key.id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdatePublishableApiKey } from "medusa-react"
type Props = {
publishableApiKeyId: string
}
const PublishableApiKey = ({
publishableApiKeyId
}: Props) => {
const updateKey = useAdminUpdatePublishableApiKey(
publishableApiKeyId
)
// ...
const handleUpdate = (title: string) => {
updateKey.mutate({
title,
}, {
onSuccess: ({ publishable_api_key }) => {
console.log(publishable_api_key.id)
}
})
}
// ...
}
export default PublishableApiKey
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/publishable-api-key/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"title": "new title"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Publishable Api Keys
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPublishableApiKeysRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeletePublishableApiKeysPublishableApiKey
summary: Delete Publishable API Key
description: Delete a Publishable API Key. Associated resources, such as sales channels, are not deleted.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Publishable API Key to delete.
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.publishableApiKeys.delete(publishableApiKeyId)
.then(({ id, object, deleted }) => {
console.log(id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeletePublishableApiKey } from "medusa-react"
type Props = {
publishableApiKeyId: string
}
const PublishableApiKey = ({
publishableApiKeyId
}: Props) => {
const deleteKey = useAdminDeletePublishableApiKey(
publishableApiKeyId
)
// ...
const handleDelete = () => {
deleteKey.mutate(void 0, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
// ...
}
export default PublishableApiKey
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/publishable-api-key/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Publishable Api Keys
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPublishableApiKeyDeleteRes'
'400':
$ref: '#/components/responses/400_error'
/admin/publishable-api-keys/{id}/revoke:
post:
operationId: PostPublishableApiKeysPublishableApiKeyRevoke
summary: Revoke a Publishable API Key
description: Revoke a Publishable API Key. Revoking the publishable API Key can't be undone, and the key can't be used in future requests.
parameters:
- in: path
name: id
required: true
description: The ID of the Publishable API Key.
schema:
type: string
x-authenticated: true
x-codegen:
method: revoke
x-codeSamples:
- lang: JavaScript
label: JS Client
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.publishableApiKeys.revoke(publishableApiKeyId)
.then(({ publishable_api_key }) => {
console.log(publishable_api_key.id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminRevokePublishableApiKey } from "medusa-react"
type Props = {
publishableApiKeyId: string
}
const PublishableApiKey = ({
publishableApiKeyId
}: Props) => {
const revokeKey = useAdminRevokePublishableApiKey(
publishableApiKeyId
)
// ...
const handleRevoke = () => {
revokeKey.mutate(void 0, {
onSuccess: ({ publishable_api_key }) => {
console.log(publishable_api_key.revoked_at)
}
})
}
// ...
}
export default PublishableApiKey
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/publishable-api-keys/{id}/revoke' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Publishable Api Keys
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPublishableApiKeysRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/publishable-api-keys/{id}/sales-channels:
get:
operationId: GetPublishableApiKeySalesChannels
summary: List Sales Channels
description: List the sales channels associated with a publishable API key. The sales channels can be filtered by fields such as `q`.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the publishable API key.
schema:
type: string
- in: query
name: q
description: query to search sales channels' names and descriptions.
schema:
type: string
x-codegen:
method: listSalesChannels
queryParams: GetPublishableApiKeySalesChannelsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.publishableApiKeys.listSalesChannels()
.then(({ sales_channels }) => {
console.log(sales_channels.length)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import {
useAdminPublishableApiKeySalesChannels,
} from "medusa-react"
type Props = {
publishableApiKeyId: string
}
const SalesChannels = ({
publishableApiKeyId
}: Props) => {
const { sales_channels, isLoading } =
useAdminPublishableApiKeySalesChannels(
publishableApiKeyId
)
return (
{isLoading &&
Loading...}
{sales_channels && !sales_channels.length && (
No Sales Channels
)}
{sales_channels && sales_channels.length > 0 && (
{sales_channels.map((salesChannel) => (
- {salesChannel.name}
))}
)}
{isLoading &&
Loading...}
{regions && !regions.length &&
No Regions}
{regions && regions.length > 0 && (
{regions.map((region) => (
- {region.name}
))}
)}
{isLoading && Loading...}
{region && {region.name}}
)
}
export default Region
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/regions/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Regions
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminRegionsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostRegionsRegion
summary: Update a Region
description: Update a Region's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Region.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostRegionsRegionReq'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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.regions.update(regionId, {
name: "Europe"
})
.then(({ region }) => {
console.log(region.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateRegion } from "medusa-react"
type Props = {
regionId: string
}
const Region = ({
regionId
}: Props) => {
const updateRegion = useAdminUpdateRegion(regionId)
// ...
const handleUpdate = (
countries: string[]
) => {
updateRegion.mutate({
countries,
}, {
onSuccess: ({ region }) => {
console.log(region.id)
}
})
}
// ...
}
export default Region
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/regions/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"name": "Europe"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Regions
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminRegionsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteRegionsRegion
summary: Delete a Region
description: Delete a Region. Associated resources, such as providers or currencies are not deleted. Associated tax rates are deleted.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Region.
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.regions.delete(regionId)
.then(({ id, object, deleted }) => {
console.log(id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteRegion } from "medusa-react"
type Props = {
regionId: string
}
const Region = ({
regionId
}: Props) => {
const deleteRegion = useAdminDeleteRegion(regionId)
// ...
const handleDelete = () => {
deleteRegion.mutate(void 0, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
// ...
}
export default Region
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/regions/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Regions
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminRegionsDeleteRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/regions/{id}/countries:
post:
operationId: PostRegionsRegionCountries
summary: Add Country
description: Add a Country to the list of Countries in a Region.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Region.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostRegionsRegionCountriesReq'
x-codegen:
method: addCountry
x-codeSamples:
- lang: JavaScript
label: JS Client
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.regions.addCountry(regionId, {
country_code: "dk"
})
.then(({ region }) => {
console.log(region.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminRegionAddCountry } from "medusa-react"
type Props = {
regionId: string
}
const Region = ({
regionId
}: Props) => {
const addCountry = useAdminRegionAddCountry(regionId)
// ...
const handleAddCountry = (
countryCode: string
) => {
addCountry.mutate({
country_code: countryCode
}, {
onSuccess: ({ region }) => {
console.log(region.countries)
}
})
}
// ...
}
export default Region
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/regions/{region_id}/countries' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"country_code": "dk"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Regions
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminRegionsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/regions/{id}/countries/{country_code}:
delete:
operationId: PostRegionsRegionCountriesCountry
summary: Remove Country
x-authenticated: true
description: Remove a Country from the list of Countries in a Region. The country will still be available in the system, and it can be used in other regions.
parameters:
- in: path
name: id
required: true
description: The ID of the Region.
schema:
type: string
- in: path
name: country_code
description: The 2 character ISO code for the Country.
required: true
schema:
type: string
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
description: See a list of codes.
x-codegen:
method: deleteCountry
x-codeSamples:
- lang: JavaScript
label: JS Client
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.regions.deleteCountry(regionId, "dk")
.then(({ region }) => {
console.log(region.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminRegionRemoveCountry } from "medusa-react"
type Props = {
regionId: string
}
const Region = ({
regionId
}: Props) => {
const removeCountry = useAdminRegionRemoveCountry(regionId)
// ...
const handleRemoveCountry = (
countryCode: string
) => {
removeCountry.mutate(countryCode, {
onSuccess: ({ region }) => {
console.log(region.countries)
}
})
}
// ...
}
export default Region
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/regions/{id}/countries/{country_code}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Regions
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminRegionsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/regions/{id}/fulfillment-options:
get:
operationId: GetRegionsRegionFulfillmentOptions
summary: List Fulfillment Options
description: Retrieve a list of fulfillment options available in a Region.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Region.
schema:
type: string
x-codegen:
method: retrieveFulfillmentOptions
x-codeSamples:
- lang: JavaScript
label: JS Client
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.regions.retrieveFulfillmentOptions(regionId)
.then(({ fulfillment_options }) => {
console.log(fulfillment_options.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminRegionFulfillmentOptions } from "medusa-react"
type Props = {
regionId: string
}
const Region = ({
regionId
}: Props) => {
const {
fulfillment_options,
isLoading
} = useAdminRegionFulfillmentOptions(
regionId
)
return (
{isLoading &&
Loading...}
{fulfillment_options && !fulfillment_options.length && (
No Regions
)}
{fulfillment_options &&
fulfillment_options.length > 0 && (
{fulfillment_options.map((option) => (
-
{option.provider_id}
))}
)}
{isLoading &&
Loading...}
{reservations && !reservations.length && (
No Reservations
)}
{reservations && reservations.length > 0 && (
{reservations.map((reservation) => (
- {reservation.quantity}
))}
)}
{isLoading && Loading...}
{reservation && {reservation.inventory_item_id}}
)
}
export default Reservation
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/reservations/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Reservations
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminReservationsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostReservationsReservation
summary: Update a Reservation
description: Update a Reservation's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Reservation.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostReservationsReservationReq'
x-codeSamples:
- lang: JavaScript
label: JS Client
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.reservations.update(reservationId, {
quantity: 3
})
.then(({ reservation }) => {
console.log(reservation.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateReservation } from "medusa-react"
type Props = {
reservationId: string
}
const Reservation = ({ reservationId }: Props) => {
const updateReservation = useAdminUpdateReservation(
reservationId
)
// ...
const handleUpdate = (
quantity: number
) => {
updateReservation.mutate({
quantity,
})
}
// ...
}
export default Reservation
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/reservations/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"quantity": 3,
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Reservations
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminReservationsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteReservationsReservation
summary: Delete a Reservation
description: Delete a Reservation. Associated resources, such as the line item, will not be deleted.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Reservation to delete.
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.reservations.delete(reservationId)
.then(({ id, object, deleted }) => {
console.log(id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteReservation } from "medusa-react"
type Props = {
reservationId: string
}
const Reservation = ({ reservationId }: Props) => {
const deleteReservation = useAdminDeleteReservation(
reservationId
)
// ...
const handleDelete = () => {
deleteReservation.mutate(void 0, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
// ...
}
export default Reservation
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/reservations/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Reservations
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminReservationsDeleteRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/return-reasons:
get:
operationId: GetReturnReasons
summary: List Return Reasons
description: Retrieve a list of Return Reasons.
x-authenticated: true
x-codegen:
method: list
x-codeSamples:
- lang: JavaScript
label: JS Client
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.returnReasons.list()
.then(({ return_reasons }) => {
console.log(return_reasons.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminReturnReasons } from "medusa-react"
const ReturnReasons = () => {
const { return_reasons, isLoading } = useAdminReturnReasons()
return (
{isLoading &&
Loading...}
{return_reasons && !return_reasons.length && (
No Return Reasons
)}
{return_reasons && return_reasons.length > 0 && (
{return_reasons.map((reason) => (
-
{reason.label}: {reason.value}
))}
)}
{isLoading && Loading...}
{return_reason && {return_reason.label}}
)
}
export default ReturnReason
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/return-reasons/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Return Reasons
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminReturnReasonsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostReturnReasonsReason
summary: Update a Return Reason
description: Update a Return Reason's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Return Reason.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostReturnReasonsReasonReq'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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.returnReasons.update(returnReasonId, {
label: "Damaged"
})
.then(({ return_reason }) => {
console.log(return_reason.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateReturnReason } from "medusa-react"
type Props = {
returnReasonId: string
}
const ReturnReason = ({ returnReasonId }: Props) => {
const updateReturnReason = useAdminUpdateReturnReason(
returnReasonId
)
// ...
const handleUpdate = (
label: string
) => {
updateReturnReason.mutate({
label,
}, {
onSuccess: ({ return_reason }) => {
console.log(return_reason.label)
}
})
}
// ...
}
export default ReturnReason
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/return-reasons/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"label": "Damaged"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Return Reasons
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminReturnReasonsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteReturnReason
summary: Delete a Return Reason
description: Delete a return reason.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the return reason
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.returnReasons.delete(returnReasonId)
.then(({ id, object, deleted }) => {
console.log(id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteReturnReason } from "medusa-react"
type Props = {
returnReasonId: string
}
const ReturnReason = ({ returnReasonId }: Props) => {
const deleteReturnReason = useAdminDeleteReturnReason(
returnReasonId
)
// ...
const handleDelete = () => {
deleteReturnReason.mutate(void 0, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
// ...
}
export default ReturnReason
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/return-reasons/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Return Reasons
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminReturnReasonsDeleteRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/returns:
get:
operationId: GetReturns
summary: List Returns
description: Retrieve a list of Returns. The returns can be paginated.
parameters:
- in: query
name: limit
description: Limit the number of Returns returned.
schema:
type: number
default: '50'
- in: query
name: offset
description: The number of Returns to skip when retrieving the Returns.
schema:
type: number
default: '0'
x-codegen:
method: list
queryParams: AdminGetReturnsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.returns.list()
.then(({ returns, limit, offset, count }) => {
console.log(returns.length)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminReturns } from "medusa-react"
const Returns = () => {
const { returns, isLoading } = useAdminReturns()
return (
{isLoading &&
Loading...}
{returns && !returns.length && (
No Returns
)}
{returns && returns.length > 0 && (
{returns.map((returnData) => (
-
{returnData.status}
))}
)}
{isLoading &&
Loading...}
{sales_channels && !sales_channels.length && (
No Sales Channels
)}
{sales_channels && sales_channels.length > 0 && (
{sales_channels.map((salesChannel) => (
- {salesChannel.name}
))}
)}
{isLoading && Loading...}
{sales_channel && {sales_channel.name}}
)
}
export default SalesChannel
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/sales-channels/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Sales Channels
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminSalesChannelsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostSalesChannelsSalesChannel
summary: Update a Sales Channel
description: Update a Sales Channel's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Sales Channel.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostSalesChannelsSalesChannelReq'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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.salesChannels.update(salesChannelId, {
name: "App"
})
.then(({ sales_channel }) => {
console.log(sales_channel.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateSalesChannel } from "medusa-react"
type Props = {
salesChannelId: string
}
const SalesChannel = ({ salesChannelId }: Props) => {
const updateSalesChannel = useAdminUpdateSalesChannel(
salesChannelId
)
// ...
const handleUpdate = (
is_disabled: boolean
) => {
updateSalesChannel.mutate({
is_disabled,
}, {
onSuccess: ({ sales_channel }) => {
console.log(sales_channel.is_disabled)
}
})
}
// ...
}
export default SalesChannel
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/sales-channels/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"name": "App"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Sales Channels
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminSalesChannelsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteSalesChannelsSalesChannel
summary: Delete a Sales Channel
description: Delete a sales channel. Associated products, stock locations, and other resources are not deleted.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Sales channel.
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.salesChannels.delete(salesChannelId)
.then(({ id, object, deleted }) => {
console.log(id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteSalesChannel } from "medusa-react"
type Props = {
salesChannelId: string
}
const SalesChannel = ({ salesChannelId }: Props) => {
const deleteSalesChannel = useAdminDeleteSalesChannel(
salesChannelId
)
// ...
const handleDelete = () => {
deleteSalesChannel.mutate(void 0, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
// ...
}
export default SalesChannel
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/sales-channels/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Sales Channels
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminSalesChannelsDeleteRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/sales-channels/{id}/products/batch:
post:
operationId: PostSalesChannelsChannelProductsBatch
summary: Add Products to Sales Channel
description: Add a list of products to a sales channel.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Sales channel.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostSalesChannelsChannelProductsBatchReq'
x-codegen:
method: addProducts
x-codeSamples:
- lang: JavaScript
label: JS Client
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.salesChannels.addProducts(salesChannelId, {
product_ids: [
{
id: productId
}
]
})
.then(({ sales_channel }) => {
console.log(sales_channel.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminAddProductsToSalesChannel } from "medusa-react"
type Props = {
salesChannelId: string
}
const SalesChannel = ({ salesChannelId }: Props) => {
const addProducts = useAdminAddProductsToSalesChannel(
salesChannelId
)
// ...
const handleAddProducts = (productId: string) => {
addProducts.mutate({
product_ids: [
{
id: productId,
},
],
}, {
onSuccess: ({ sales_channel }) => {
console.log(sales_channel.id)
}
})
}
// ...
}
export default SalesChannel
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/sales-channels/{id}/products/batch' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"product_ids": [
{
"id": "{product_id}"
}
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Sales Channels
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminSalesChannelsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteSalesChannelsChannelProductsBatch
summary: Remove Products from Sales Channel
description: Remove a list of products from a sales channel. This does not delete the product. It only removes the association between the product and the sales channel.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Sales Channel
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDeleteSalesChannelsChannelProductsBatchReq'
x-codegen:
method: removeProducts
x-codeSamples:
- lang: JavaScript
label: JS Client
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.salesChannels.removeProducts(salesChannelId, {
product_ids: [
{
id: productId
}
]
})
.then(({ sales_channel }) => {
console.log(sales_channel.id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import {
useAdminDeleteProductsFromSalesChannel,
} from "medusa-react"
type Props = {
salesChannelId: string
}
const SalesChannel = ({ salesChannelId }: Props) => {
const deleteProducts = useAdminDeleteProductsFromSalesChannel(
salesChannelId
)
// ...
const handleDeleteProducts = (productId: string) => {
deleteProducts.mutate({
product_ids: [
{
id: productId,
},
],
}, {
onSuccess: ({ sales_channel }) => {
console.log(sales_channel.id)
}
})
}
// ...
}
export default SalesChannel
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/sales-channels/{id}/products/batch' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"product_ids": [
{
"id": "{product_id}"
}
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Sales Channels
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminSalesChannelsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/sales-channels/{id}/stock-locations:
post:
operationId: PostSalesChannelsSalesChannelStockLocation
summary: Associate a Stock Location
description: Associate a stock location with a Sales Channel.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Sales Channel.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostSalesChannelsChannelStockLocationsReq'
x-codegen:
method: addLocation
x-codeSamples:
- lang: JavaScript
label: JS Client
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.salesChannels.addLocation(salesChannelId, {
location_id: "loc_123"
})
.then(({ sales_channel }) => {
console.log(sales_channel.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import {
useAdminAddLocationToSalesChannel
} from "medusa-react"
type Props = {
salesChannelId: string
}
const SalesChannel = ({ salesChannelId }: Props) => {
const addLocation = useAdminAddLocationToSalesChannel()
// ...
const handleAddLocation = (locationId: string) => {
addLocation.mutate({
sales_channel_id: salesChannelId,
location_id: locationId
}, {
onSuccess: ({ sales_channel }) => {
console.log(sales_channel.locations)
}
})
}
// ...
}
export default SalesChannel
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/sales-channels/{id}/stock-locations' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"locaton_id": "loc_123"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Sales Channels
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminSalesChannelsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteSalesChannelsSalesChannelStockLocation
summary: Remove Stock Location from Sales Channels.
description: Remove a stock location from a Sales Channel. This only removes the association between the stock location and the sales channel. It does not delete the stock location.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Sales Channel.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDeleteSalesChannelsChannelStockLocationsReq'
x-codegen:
method: removeLocation
x-codeSamples:
- lang: JavaScript
label: JS Client
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.salesChannels.removeLocation(salesChannelId, {
location_id: "loc_id"
})
.then(({ sales_channel }) => {
console.log(sales_channel.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import {
useAdminRemoveLocationFromSalesChannel
} from "medusa-react"
type Props = {
salesChannelId: string
}
const SalesChannel = ({ salesChannelId }: Props) => {
const removeLocation = useAdminRemoveLocationFromSalesChannel()
// ...
const handleRemoveLocation = (locationId: string) => {
removeLocation.mutate({
sales_channel_id: salesChannelId,
location_id: locationId
}, {
onSuccess: ({ sales_channel }) => {
console.log(sales_channel.locations)
}
})
}
// ...
}
export default SalesChannel
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/sales-channels/{id}/stock-locations' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"locaton_id": "loc_id"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Sales Channels
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminSalesChannelsDeleteLocationRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/shipping-options:
get:
operationId: GetShippingOptions
summary: List Shipping Options
description: Retrieve a list of Shipping Options. The shipping options can be filtered by fields such as `region_id` or `is_return`. The shipping options can also be sorted or paginated.
x-authenticated: true
parameters:
- in: query
name: name
description: Filter by name.
schema:
type: string
- in: query
name: region_id
description: Filter by the ID of the region the shipping options belong to.
schema:
type: string
- in: query
name: is_return
description: Filter by whether the shipping options are return shipping options.
schema:
type: boolean
- in: query
name: admin_only
description: Filter by whether the shipping options are available for admin users only.
schema:
type: boolean
- in: query
name: q
description: Term used to search shipping options' name.
schema:
type: string
- in: query
name: order
description: A shipping option field to sort-order the retrieved shipping options by.
schema:
type: string
- in: query
name: id
style: form
explode: false
description: Filter by shipping option IDs.
schema:
oneOf:
- type: string
description: ID of the shipping option.
- type: array
items:
type: string
description: ID of a shipping option.
- in: query
name: created_at
description: Filter by a creation date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: updated_at
description: Filter by an update date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: deleted_at
description: Filter by a deletion date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: offset
description: The number of users to skip when retrieving the shipping options.
schema:
type: integer
default: 0
- in: query
name: limit
description: Limit the number of shipping options returned.
schema:
type: integer
default: 20
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned shipping options.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned shipping options.
schema:
type: string
x-codegen:
method: list
queryParams: AdminGetShippingOptionsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.shippingOptions.list()
.then(({ shipping_options, count }) => {
console.log(shipping_options.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminShippingOptions } from "medusa-react"
const ShippingOptions = () => {
const {
shipping_options,
isLoading
} = useAdminShippingOptions()
return (
{isLoading &&
Loading...}
{shipping_options && !shipping_options.length && (
No Shipping Options
)}
{shipping_options && shipping_options.length > 0 && (
{shipping_options.map((option) => (
- {option.name}
))}
)}
{isLoading && Loading...}
{shipping_option && {shipping_option.name}}
)
}
export default ShippingOption
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/shipping-options/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Shipping Options
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminShippingOptionsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostShippingOptionsOption
summary: Update Shipping Option
description: Update a Shipping Option's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Shipping Option.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostShippingOptionsOptionReq'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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.shippingOptions.update(optionId, {
name: "PostFake",
requirements: [
{
id,
type: "max_subtotal",
amount: 1000
}
]
})
.then(({ shipping_option }) => {
console.log(shipping_option.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateShippingOption } from "medusa-react"
type Props = {
shippingOptionId: string
}
const ShippingOption = ({ shippingOptionId }: Props) => {
const updateShippingOption = useAdminUpdateShippingOption(
shippingOptionId
)
// ...
const handleUpdate = (
name: string,
requirements: {
id: string,
type: string,
amount: number
}[]
) => {
updateShippingOption.mutate({
name,
requirements
}, {
onSuccess: ({ shipping_option }) => {
console.log(shipping_option.requirements)
}
})
}
// ...
}
export default ShippingOption
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/shipping-options/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"requirements": [
{
"type": "max_subtotal",
"amount": 1000
}
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Shipping Options
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminShippingOptionsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteShippingOptionsOption
summary: Delete Shipping Option
description: Delete a Shipping Option. Once deleted, it can't be used when creating orders or returns.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Shipping Option.
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.shippingOptions.delete(optionId)
.then(({ id, object, deleted }) => {
console.log(id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteShippingOption } from "medusa-react"
type Props = {
shippingOptionId: string
}
const ShippingOption = ({ shippingOptionId }: Props) => {
const deleteShippingOption = useAdminDeleteShippingOption(
shippingOptionId
)
// ...
const handleDelete = () => {
deleteShippingOption.mutate(void 0, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
// ...
}
export default ShippingOption
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/shipping-options/{option_id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Shipping Options
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminShippingOptionsDeleteRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/shipping-profiles:
get:
operationId: GetShippingProfiles
summary: List Shipping Profiles
description: Retrieve a list of Shipping Profiles.
x-authenticated: true
x-codegen:
method: list
x-codeSamples:
- lang: JavaScript
label: JS Client
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.shippingProfiles.list()
.then(({ shipping_profiles }) => {
console.log(shipping_profiles.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminShippingProfiles } from "medusa-react"
const ShippingProfiles = () => {
const {
shipping_profiles,
isLoading
} = useAdminShippingProfiles()
return (
{isLoading &&
Loading...}
{shipping_profiles && !shipping_profiles.length && (
No Shipping Profiles
)}
{shipping_profiles && shipping_profiles.length > 0 && (
{shipping_profiles.map((profile) => (
- {profile.name}
))}
)}
{isLoading && Loading...}
{shipping_profile && (
{shipping_profile.name}
)}
)
}
export default ShippingProfile
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/shipping-profiles/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Shipping Profiles
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminShippingProfilesRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostShippingProfilesProfile
summary: Update a Shipping Profile
description: Update a Shipping Profile's details.
parameters:
- in: path
name: id
required: true
description: The ID of the Shipping Profile.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostShippingProfilesProfileReq'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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.shippingProfiles.update(shippingProfileId, {
name: 'Large Products'
})
.then(({ shipping_profile }) => {
console.log(shipping_profile.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { ShippingProfileType } from "@medusajs/medusa"
import { useAdminUpdateShippingProfile } from "medusa-react"
type Props = {
shippingProfileId: string
}
const ShippingProfile = ({ shippingProfileId }: Props) => {
const updateShippingProfile = useAdminUpdateShippingProfile(
shippingProfileId
)
// ...
const handleUpdate = (
name: string,
type: ShippingProfileType
) => {
updateShippingProfile.mutate({
name,
type
}, {
onSuccess: ({ shipping_profile }) => {
console.log(shipping_profile.name)
}
})
}
// ...
}
export default ShippingProfile
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/shipping-profiles/{id} \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"name": "Large Products"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Shipping Profiles
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminShippingProfilesRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteShippingProfilesProfile
summary: Delete a Shipping Profile
description: Delete a Shipping Profile. Associated shipping options are deleted as well.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Shipping Profile.
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.shippingProfiles.delete(profileId)
.then(({ id, object, deleted }) => {
console.log(id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteShippingProfile } from "medusa-react"
type Props = {
shippingProfileId: string
}
const ShippingProfile = ({ shippingProfileId }: Props) => {
const deleteShippingProfile = useAdminDeleteShippingProfile(
shippingProfileId
)
// ...
const handleDelete = () => {
deleteShippingProfile.mutate(void 0, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
// ...
}
export default ShippingProfile
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/shipping-profiles/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Shipping Profiles
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDeleteShippingProfileRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/stock-locations:
get:
operationId: GetStockLocations
summary: List Stock Locations
description: Retrieve a list of stock locations. The stock locations can be filtered by fields such as `name` or `created_at`. The stock locations can also be sorted or paginated.
x-authenticated: true
parameters:
- in: query
name: id
description: Filter by ID.
schema:
type: string
- in: query
name: name
description: Filter by name.
schema:
type: string
- in: query
name: order
description: A stock-location field to sort-order the retrieved stock locations by.
schema:
type: string
- in: query
name: created_at
description: Filter by a creation date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: updated_at
description: Filter by an update date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: deleted_at
description: Filter by a deletion date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: offset
description: The number of stock locations to skip when retrieving the stock locations.
schema:
type: integer
default: 0
- in: query
name: limit
description: Limit the number of stock locations returned.
schema:
type: integer
default: 20
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned stock locations.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned stock locations.
schema:
type: string
x-codegen:
method: list
queryParams: AdminGetStockLocationsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.stockLocations.list()
.then(({ stock_locations, limit, offset, count }) => {
console.log(stock_locations.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminStockLocations } from "medusa-react"
function StockLocations() {
const {
stock_locations,
isLoading
} = useAdminStockLocations()
return (
{isLoading &&
Loading...}
{stock_locations && !stock_locations.length && (
No Locations
)}
{stock_locations && stock_locations.length > 0 && (
{stock_locations.map(
(location) => (
- {location.name}
)
)}
)}
{isLoading && Loading...}
{stock_location && (
{stock_location.name}
)}
)
}
export default StockLocation
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/stock-locations/{id}' \
-H 'x-medusa-access-token: {api_token}' \
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Stock Locations
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminStockLocationsRes'
post:
operationId: PostStockLocationsStockLocation
summary: Update a Stock Location
description: Update a Stock Location's details.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Stock Location.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned stock location.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned stock location.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostStockLocationsLocationReq'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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.stockLocations.update(stockLocationId, {
name: 'Main Warehouse'
})
.then(({ stock_location }) => {
console.log(stock_location.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateStockLocation } from "medusa-react"
type Props = {
stockLocationId: string
}
const StockLocation = ({ stockLocationId }: Props) => {
const updateLocation = useAdminUpdateStockLocation(
stockLocationId
)
// ...
const handleUpdate = (
name: string
) => {
updateLocation.mutate({
name
}, {
onSuccess: ({ stock_location }) => {
console.log(stock_location.name)
}
})
}
}
export default StockLocation
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/stock-locations/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"name": "Main Warehouse"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Stock Locations
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminStockLocationsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteStockLocationsStockLocation
summary: Delete a Stock Location
description: Delete a Stock Location.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Stock Location.
schema:
type: string
x-codeSamples:
- lang: JavaScript
label: JS Client
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.stockLocations.delete(stockLocationId)
.then(({ id, object, deleted }) => {
console.log(id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteStockLocation } from "medusa-react"
type Props = {
stockLocationId: string
}
const StockLocation = ({ stockLocationId }: Props) => {
const deleteLocation = useAdminDeleteStockLocation(
stockLocationId
)
// ...
const handleDelete = () => {
deleteLocation.mutate(void 0, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
}
export default StockLocation
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/stock-locations/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Stock Locations
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminStockLocationsDeleteRes'
'400':
$ref: '#/components/responses/400_error'
/admin/store:
get:
operationId: GetStore
summary: Get Store details
description: Retrieve the Store's details.
x-authenticated: true
x-codegen:
method: retrieve
x-codeSamples:
- lang: JavaScript
label: JS Client
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.store.retrieve()
.then(({ store }) => {
console.log(store.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminStore } from "medusa-react"
const Store = () => {
const {
store,
isLoading
} = useAdminStore()
return (
{isLoading && Loading...}
{store && {store.name}}
)
}
export default Store
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/store' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Store
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminExtendedStoresRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostStore
summary: Update Store Details
description: Update the Store's details.
x-authenticated: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostStoreReq'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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.store.update({
name: "Medusa Store"
})
.then(({ store }) => {
console.log(store.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateStore } from "medusa-react"
function Store() {
const updateStore = useAdminUpdateStore()
// ...
const handleUpdate = (
name: string
) => {
updateStore.mutate({
name
}, {
onSuccess: ({ store }) => {
console.log(store.name)
}
})
}
}
export default Store
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/store' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"name": "Medusa Store"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Store
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminStoresRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/store/currencies/{code}:
post:
operationId: PostStoreCurrenciesCode
summary: Add a Currency Code
description: Add a Currency Code to the available currencies in a store. This does not create new currencies, as currencies are defined within the Medusa backend. To create a currency, you can create a migration that inserts the currency into the database.
x-authenticated: true
parameters:
- in: path
name: code
required: true
description: The 3 character ISO currency code.
schema:
type: string
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
description: See a list of codes.
x-codegen:
method: addCurrency
x-codeSamples:
- lang: JavaScript
label: JS Client
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.store.addCurrency("eur")
.then(({ store }) => {
console.log(store.currencies);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminAddStoreCurrency } from "medusa-react"
const Store = () => {
const addCurrency = useAdminAddStoreCurrency()
// ...
const handleAdd = (code: string) => {
addCurrency.mutate(code, {
onSuccess: ({ store }) => {
console.log(store.currencies)
}
})
}
// ...
}
export default Store
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/store/currencies/{currency_code}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Store
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminStoresRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteStoreCurrenciesCode
summary: Remove a Currency
description: Remove a Currency Code from the available currencies in a store. This does not completely delete the currency and it can be added again later to the store.
x-authenticated: true
parameters:
- in: path
name: code
required: true
description: The 3 character ISO currency code.
schema:
type: string
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
description: See a list of codes.
x-codegen:
method: deleteCurrency
x-codeSamples:
- lang: JavaScript
label: JS Client
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.store.deleteCurrency("eur")
.then(({ store }) => {
console.log(store.currencies);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteStoreCurrency } from "medusa-react"
const Store = () => {
const deleteCurrency = useAdminDeleteStoreCurrency()
// ...
const handleAdd = (code: string) => {
deleteCurrency.mutate(code, {
onSuccess: ({ store }) => {
console.log(store.currencies)
}
})
}
// ...
}
export default Store
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/store/currencies/{currency_code}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Store
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminStoresRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/store/payment-providers:
get:
operationId: GetStorePaymentProviders
summary: List Payment Providers
description: Retrieve a list of available Payment Providers in a store.
x-authenticated: true
x-codegen:
method: listPaymentProviders
x-codeSamples:
- lang: JavaScript
label: JS Client
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.store.listPaymentProviders()
.then(({ payment_providers }) => {
console.log(payment_providers.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminStorePaymentProviders } from "medusa-react"
const PaymentProviders = () => {
const {
payment_providers,
isLoading
} = useAdminStorePaymentProviders()
return (
{isLoading &&
Loading...}
{payment_providers && !payment_providers.length && (
No Payment Providers
)}
{payment_providers &&
payment_providers.length > 0 &&(
{payment_providers.map((provider) => (
- {provider.id}
))}
)}
{isLoading &&
Loading...}
{tax_providers && !tax_providers.length && (
No Tax Providers
)}
{tax_providers &&
tax_providers.length > 0 &&(
{tax_providers.map((provider) => (
- {provider.id}
))}
)}
{isLoading &&
Loading...}
{swaps && !swaps.length &&
No Swaps}
{swaps && swaps.length > 0 && (
{swaps.map((swap) => (
- {swap.payment_status}
))}
)}
{isLoading && Loading...}
{swap && {swap.id}}
)
}
export default Swap
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/swaps/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Swaps
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminSwapsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/tax-rates:
get:
operationId: GetTaxRates
summary: List Tax Rates
description: Retrieve a list of Tax Rates. The tax rates can be filtered by fields such as `name` or `rate`. The tax rates can also be paginated.
x-authenticated: true
parameters:
- in: query
name: name
description: Filter by name.
schema:
type: string
- in: query
name: region_id
style: form
explode: false
description: Filter by Region IDs
schema:
oneOf:
- type: string
- type: array
items:
type: string
- in: query
name: code
description: Filter by code.
schema:
type: string
- in: query
name: created_at
description: Filter by a creation date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: updated_at
description: Filter by an update date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: deleted_at
description: Filter by a deletion date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: rate
style: form
explode: false
description: Filter by Rate
schema:
oneOf:
- type: number
- type: object
properties:
lt:
type: number
description: filter by rates less than this number
gt:
type: number
description: filter by rates greater than this number
lte:
type: number
description: filter by rates less than or equal to this number
gte:
type: number
description: filter by rates greater than or equal to this number
- in: query
name: q
description: Term used to search tax rates by name.
schema:
type: string
- in: query
name: order
description: A tax rate field to sort-order the retrieved tax rates by.
schema:
type: string
- in: query
name: offset
description: The number of tax rates to skip when retrieving the tax rates.
schema:
type: integer
default: 0
- in: query
name: limit
description: Limit the number of tax rates returned.
schema:
type: integer
default: 50
- in: query
name: fields
description: Comma-separated fields that should be included in the returned tax rate.
style: form
explode: false
schema:
type: array
items:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned tax rate.
style: form
explode: false
schema:
type: array
items:
type: string
x-codegen:
method: list
queryParams: AdminGetTaxRatesParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.taxRates.list()
.then(({ tax_rates, limit, offset, count }) => {
console.log(tax_rates.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminTaxRates } from "medusa-react"
const TaxRates = () => {
const {
tax_rates,
isLoading
} = useAdminTaxRates()
return (
{isLoading &&
Loading...}
{tax_rates && !tax_rates.length && (
No Tax Rates
)}
{tax_rates && tax_rates.length > 0 && (
{tax_rates.map((tax_rate) => (
- {tax_rate.code}
))}
)}
{isLoading && Loading...}
{tax_rate && {tax_rate.code}}
)
}
export default TaxRate
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/tax-rates/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Tax Rates
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminTaxRatesRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostTaxRatesTaxRate
summary: Update a Tax Rate
description: Update a Tax Rate's details.
parameters:
- in: path
name: id
required: true
description: ID of the tax rate.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned tax rate.
style: form
explode: false
schema:
type: array
items:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned tax rate.
style: form
explode: false
schema:
type: array
items:
type: string
x-authenticated: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostTaxRatesTaxRateReq'
x-codegen:
method: update
queryParams: AdminPostTaxRatesTaxRateParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.taxRates.update(taxRateId, {
name: "New Tax Rate"
})
.then(({ tax_rate }) => {
console.log(tax_rate.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateTaxRate } from "medusa-react"
type Props = {
taxRateId: string
}
const TaxRate = ({ taxRateId }: Props) => {
const updateTaxRate = useAdminUpdateTaxRate(taxRateId)
// ...
const handleUpdate = (
name: string
) => {
updateTaxRate.mutate({
name
}, {
onSuccess: ({ tax_rate }) => {
console.log(tax_rate.name)
}
})
}
// ...
}
export default TaxRate
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/tax-rates/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"name": "New Tax Rate"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Tax Rates
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminTaxRatesRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteTaxRatesTaxRate
summary: Delete a Tax Rate
description: Delete a Tax Rate. Resources associated with the tax rate, such as products or product types, are not deleted.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the Shipping Option.
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.taxRates.delete(taxRateId)
.then(({ id, object, deleted }) => {
console.log(id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteTaxRate } from "medusa-react"
type Props = {
taxRateId: string
}
const TaxRate = ({ taxRateId }: Props) => {
const deleteTaxRate = useAdminDeleteTaxRate(taxRateId)
// ...
const handleDelete = () => {
deleteTaxRate.mutate(void 0, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
// ...
}
export default TaxRate
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/tax-rates/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Tax Rates
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminTaxRatesDeleteRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/tax-rates/{id}/product-types/batch:
post:
operationId: PostTaxRatesTaxRateProductTypes
summary: Add to Product Types
description: Add Product Types to a Tax Rate.
parameters:
- in: path
name: id
required: true
description: ID of the tax rate.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned tax rate.
style: form
explode: false
schema:
type: array
items:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned tax rate.
style: form
explode: false
schema:
type: array
items:
type: string
x-authenticated: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostTaxRatesTaxRateProductTypesReq'
x-codegen:
method: addProductTypes
queryParams: AdminPostTaxRatesTaxRateProductTypesParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.taxRates.addProductTypes(taxRateId, {
product_types: [
productTypeId
]
})
.then(({ tax_rate }) => {
console.log(tax_rate.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import {
useAdminCreateProductTypeTaxRates,
} from "medusa-react"
type Props = {
taxRateId: string
}
const TaxRate = ({ taxRateId }: Props) => {
const addProductTypes = useAdminCreateProductTypeTaxRates(
taxRateId
)
// ...
const handleAddProductTypes = (productTypeIds: string[]) => {
addProductTypes.mutate({
product_types: productTypeIds,
}, {
onSuccess: ({ tax_rate }) => {
console.log(tax_rate.product_types)
}
})
}
// ...
}
export default TaxRate
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/tax-rates/{id}/product-types/batch' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"product_types": [
"{product_type_id}"
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Tax Rates
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminTaxRatesRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteTaxRatesTaxRateProductTypes
summary: Remove Product Types from Rate
description: Remove product types from a tax rate. This only removes the association between the product types and the tax rate. It does not delete the product types.
parameters:
- in: path
name: id
required: true
description: ID of the tax rate.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned tax rate.
style: form
explode: false
schema:
type: array
items:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned tax rate.
style: form
explode: false
schema:
type: array
items:
type: string
x-authenticated: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDeleteTaxRatesTaxRateProductTypesReq'
x-codegen:
method: removeProductTypes
queryParams: AdminDeleteTaxRatesTaxRateProductTypesParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.taxRates.removeProductTypes(taxRateId, {
product_types: [
productTypeId
]
})
.then(({ tax_rate }) => {
console.log(tax_rate.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import {
useAdminDeleteProductTypeTaxRates,
} from "medusa-react"
type Props = {
taxRateId: string
}
const TaxRate = ({ taxRateId }: Props) => {
const removeProductTypes = useAdminDeleteProductTypeTaxRates(
taxRateId
)
// ...
const handleRemoveProductTypes = (
productTypeIds: string[]
) => {
removeProductTypes.mutate({
product_types: productTypeIds,
}, {
onSuccess: ({ tax_rate }) => {
console.log(tax_rate.product_types)
}
})
}
// ...
}
export default TaxRate
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/tax-rates/{id}/product-types/batch' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"product_types": [
"{product_type_id}"
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Tax Rates
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminTaxRatesRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/tax-rates/{id}/products/batch:
post:
operationId: PostTaxRatesTaxRateProducts
summary: Add to Products
description: Add products to a tax rate.
parameters:
- in: path
name: id
required: true
description: ID of the tax rate.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned tax rate.
style: form
explode: false
schema:
type: array
items:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned tax rate.
style: form
explode: false
schema:
type: array
items:
type: string
x-authenticated: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostTaxRatesTaxRateProductsReq'
x-codegen:
method: addProducts
queryParams: AdminPostTaxRatesTaxRateProductsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.taxRates.addProducts(taxRateId, {
products: [
productId
]
})
.then(({ tax_rate }) => {
console.log(tax_rate.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCreateProductTaxRates } from "medusa-react"
type Props = {
taxRateId: string
}
const TaxRate = ({ taxRateId }: Props) => {
const addProduct = useAdminCreateProductTaxRates(taxRateId)
// ...
const handleAddProduct = (productIds: string[]) => {
addProduct.mutate({
products: productIds,
}, {
onSuccess: ({ tax_rate }) => {
console.log(tax_rate.products)
}
})
}
// ...
}
export default TaxRate
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/tax-rates/{id}/products/batch' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"products": [
"{product_id}"
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Tax Rates
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminTaxRatesRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteTaxRatesTaxRateProducts
summary: Remove Products from Rate
description: Remove products from a tax rate. This only removes the association between the products and the tax rate. It does not delete the products.
parameters:
- in: path
name: id
required: true
description: ID of the tax rate.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned tax rate.
style: form
explode: false
schema:
type: array
items:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned tax rate.
style: form
explode: false
schema:
type: array
items:
type: string
x-authenticated: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDeleteTaxRatesTaxRateProductsReq'
x-codegen:
method: removeProducts
queryParams: AdminDeleteTaxRatesTaxRateProductsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.taxRates.removeProducts(taxRateId, {
products: [
productId
]
})
.then(({ tax_rate }) => {
console.log(tax_rate.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteProductTaxRates } from "medusa-react"
type Props = {
taxRateId: string
}
const TaxRate = ({ taxRateId }: Props) => {
const removeProduct = useAdminDeleteProductTaxRates(taxRateId)
// ...
const handleRemoveProduct = (productIds: string[]) => {
removeProduct.mutate({
products: productIds,
}, {
onSuccess: ({ tax_rate }) => {
console.log(tax_rate.products)
}
})
}
// ...
}
export default TaxRate
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/tax-rates/{id}/products/batch' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"products": [
"{product_id}"
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Tax Rates
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminTaxRatesRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/tax-rates/{id}/shipping-options/batch:
post:
operationId: PostTaxRatesTaxRateShippingOptions
summary: Add to Shipping Options
description: Add Shipping Options to a Tax Rate.
parameters:
- in: path
name: id
required: true
description: ID of the tax rate.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned tax rate.
style: form
explode: false
schema:
type: array
items:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned tax rate.
style: form
explode: false
schema:
type: array
items:
type: string
x-authenticated: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostTaxRatesTaxRateShippingOptionsReq'
x-codegen:
method: addShippingOptions
queryParams: AdminPostTaxRatesTaxRateShippingOptionsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.taxRates.addShippingOptions(taxRateId, {
shipping_options: [
shippingOptionId
]
})
.then(({ tax_rate }) => {
console.log(tax_rate.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCreateShippingTaxRates } from "medusa-react"
type Props = {
taxRateId: string
}
const TaxRate = ({ taxRateId }: Props) => {
const addShippingOption = useAdminCreateShippingTaxRates(
taxRateId
)
// ...
const handleAddShippingOptions = (
shippingOptionIds: string[]
) => {
addShippingOption.mutate({
shipping_options: shippingOptionIds,
}, {
onSuccess: ({ tax_rate }) => {
console.log(tax_rate.shipping_options)
}
})
}
// ...
}
export default TaxRate
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/tax-rates/{id}/shipping-options/batch' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"shipping_options": [
"{shipping_option_id}"
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Tax Rates
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminTaxRatesRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteTaxRatesTaxRateShippingOptions
summary: Remove Shipping Options from Rate
description: Remove shipping options from a tax rate. This only removes the association between the shipping options and the tax rate. It does not delete the shipping options.
parameters:
- in: path
name: id
required: true
description: ID of the tax rate.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned tax rate.
style: form
explode: false
schema:
type: array
items:
type: string
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned tax rate.
style: form
explode: false
schema:
type: array
items:
type: string
x-authenticated: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDeleteTaxRatesTaxRateShippingOptionsReq'
x-codegen:
method: removeShippingOptions
queryParams: AdminDeleteTaxRatesTaxRateShippingOptionsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.taxRates.removeShippingOptions(taxRateId, {
shipping_options: [
shippingOptionId
]
})
.then(({ tax_rate }) => {
console.log(tax_rate.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteShippingTaxRates } from "medusa-react"
type Props = {
taxRateId: string
}
const TaxRate = ({ taxRateId }: Props) => {
const removeShippingOptions = useAdminDeleteShippingTaxRates(
taxRateId
)
// ...
const handleRemoveShippingOptions = (
shippingOptionIds: string[]
) => {
removeShippingOptions.mutate({
shipping_options: shippingOptionIds,
}, {
onSuccess: ({ tax_rate }) => {
console.log(tax_rate.shipping_options)
}
})
}
// ...
}
export default TaxRate
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/tax-rates/{id}/shipping-options/batch' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"shipping_options": [
"{shipping_option_id}"
]
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Tax Rates
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminTaxRatesRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/uploads:
post:
operationId: PostUploads
summary: Upload Files
description: Upload at least one file to a public bucket or storage. The file upload is handled by the file service installed on the Medusa backend.
x-authenticated: true
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
files:
type: string
format: binary
x-codeSamples:
- lang: JavaScript
label: JS Client
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.uploads.create(file)
.then(({ uploads }) => {
console.log(uploads.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUploadFile } from "medusa-react"
const UploadFile = () => {
const uploadFile = useAdminUploadFile()
// ...
const handleFileUpload = (file: File) => {
uploadFile.mutate(file, {
onSuccess: ({ uploads }) => {
console.log(uploads[0].key)
}
})
}
// ...
}
export default UploadFile
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/uploads' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: image/jpeg' \
--form 'files=@""' \
--form 'files=@""'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Uploads
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminUploadsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteUploads
summary: Delete an Uploaded File
description: Delete an uploaded file from storage. The file is deleted using the installed file service on the Medusa backend.
x-authenticated: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDeleteUploadsReq'
x-codeSamples:
- lang: JavaScript
label: JS Client
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.uploads.delete({
file_key
})
.then(({ id, object, deleted }) => {
console.log(id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteFile } from "medusa-react"
const Image = () => {
const deleteFile = useAdminDeleteFile()
// ...
const handleDeleteFile = (fileKey: string) => {
deleteFile.mutate({
file_key: fileKey
}, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
// ...
}
export default Image
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/uploads' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"file_key": "{file_key}"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Uploads
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDeleteUploadsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/uploads/download-url:
post:
operationId: PostUploadsDownloadUrl
summary: Get a File's Download URL
description: Create and retrieve a presigned or public download URL for a file. The URL creation is handled by the file service installed on the Medusa backend.
x-authenticated: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminPostUploadsDownloadUrlReq'
x-codeSamples:
- lang: JavaScript
label: JS Client
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.uploads.getPresignedDownloadUrl({
file_key
})
.then(({ download_url }) => {
console.log(download_url);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminCreatePresignedDownloadUrl } from "medusa-react"
const Image = () => {
const createPresignedUrl = useAdminCreatePresignedDownloadUrl()
// ...
const handlePresignedUrl = (fileKey: string) => {
createPresignedUrl.mutate({
file_key: fileKey
}, {
onSuccess: ({ download_url }) => {
console.log(download_url)
}
})
}
// ...
}
export default Image
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/uploads/download-url' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"file_key": "{file_key}"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Uploads
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminUploadsDownloadUrlRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/uploads/protected:
post:
operationId: PostUploadsProtected
summary: Protected File Upload
description: Upload at least one file to an ACL or a non-public bucket. The file upload is handled by the file service installed on the Medusa backend.
x-authenticated: true
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
files:
type: string
format: binary
x-codeSamples:
- lang: JavaScript
label: JS Client
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.uploads.createProtected(file)
.then(({ uploads }) => {
console.log(uploads.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUploadProtectedFile } from "medusa-react"
const UploadFile = () => {
const uploadFile = useAdminUploadProtectedFile()
// ...
const handleFileUpload = (file: File) => {
uploadFile.mutate(file, {
onSuccess: ({ uploads }) => {
console.log(uploads[0].key)
}
})
}
// ...
}
export default UploadFile
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/uploads/protected' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: image/jpeg' \
--form 'files=@""' \
--form 'files=@""'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Uploads
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminUploadsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/users:
get:
operationId: GetUsers
summary: List Users
description: Retrieves a list of users. The users can be filtered by fields such as `q` or `email`. The users can also be sorted or paginated.
x-authenticated: true
parameters:
- in: query
name: email
description: Filter by email.
schema:
type: string
- in: query
name: first_name
description: Filter by first name.
schema:
type: string
- in: query
name: last_name
description: Filter by last name.
schema:
type: string
- in: query
name: q
description: Term used to search users' first name, last name, and email.
schema:
type: string
- in: query
name: order
description: A user field to sort-order the retrieved users by.
schema:
type: string
- in: query
name: id
style: form
explode: false
description: Filter by user IDs.
schema:
oneOf:
- type: string
description: ID of the user.
- type: array
items:
type: string
description: ID of a user.
- in: query
name: created_at
description: Filter by a creation date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: updated_at
description: Filter by an update date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: deleted_at
description: Filter by a deletion date range.
schema:
type: object
properties:
lt:
type: string
description: filter by dates less than this date
format: date
gt:
type: string
description: filter by dates greater than this date
format: date
lte:
type: string
description: filter by dates less than or equal to this date
format: date
gte:
type: string
description: filter by dates greater than or equal to this date
format: date
- in: query
name: offset
description: The number of users to skip when retrieving the users.
schema:
type: integer
default: 0
- in: query
name: limit
description: Limit the number of users returned.
schema:
type: integer
default: 20
- in: query
name: fields
description: Comma-separated fields that should be included in the returned users.
schema:
type: string
x-codegen:
method: list
queryParams: AdminGetUsersParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.list()
.then(({ users, limit, offset, count }) => {
console.log(users.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUsers } from "medusa-react"
const Users = () => {
const { users, isLoading } = useAdminUsers()
return (
{isLoading &&
Loading...}
{users && !users.length &&
No Users}
{users && users.length > 0 && (
{users.map((user) => (
- {user.email}
))}
)}
{isLoading && Loading...}
{user && {user.first_name} {user.last_name}}
)
}
export default User
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/users/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Users
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminUserRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
post:
operationId: PostUsersUser
summary: Update a User
description: Update an admin user's details.
parameters:
- in: path
name: id
required: true
description: The ID of the User.
schema:
type: string
x-authenticated: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminUpdateUserRequest'
x-codegen:
method: update
x-codeSamples:
- lang: JavaScript
label: JS Client
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, {
first_name: "Marcellus"
})
.then(({ user }) => {
console.log(user.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminUpdateUser } from "medusa-react"
type Props = {
userId: string
}
const User = ({ userId }: Props) => {
const updateUser = useAdminUpdateUser(userId)
// ...
const handleUpdateUser = (
firstName: string
) => {
updateUser.mutate({
first_name: firstName,
}, {
onSuccess: ({ user }) => {
console.log(user.first_name)
}
})
}
// ...
}
export default User
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/admin/users/{id}' \
-H 'x-medusa-access-token: {api_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"first_name": "Marcellus"
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Users
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminUserRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
delete:
operationId: DeleteUsersUser
summary: Delete a User
description: Delete a User. Once deleted, the user will not be able to authenticate or perform admin functionalities.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The ID of the User.
schema:
type: string
x-codegen:
method: delete
x-codeSamples:
- lang: JavaScript
label: JS Client
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.delete(userId)
.then(({ id, object, deleted }) => {
console.log(id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminDeleteUser } from "medusa-react"
type Props = {
userId: string
}
const User = ({ userId }: Props) => {
const deleteUser = useAdminDeleteUser(userId)
// ...
const handleDeleteUser = () => {
deleteUser.mutate(void 0, {
onSuccess: ({ id, object, deleted }) => {
console.log(id)
}
})
}
// ...
}
export default User
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/admin/users/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Users
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminDeleteUserRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/variants:
get:
operationId: GetVariants
summary: List Product Variants
description: Retrieve a list of Product Variants. The product variant can be filtered by fields such as `id` or `title`. The product variant can also be paginated.
x-authenticated: true
parameters:
- in: query
name: id
style: form
explode: false
description: Filter by product variant IDs.
schema:
oneOf:
- type: string
description: A product variant ID.
- type: array
description: An array of product variant IDs.
items:
type: string
- in: query
name: expand
description: '"Comma-separated relations that should be expanded in the returned product variants."'
schema:
type: string
- in: query
name: fields
description: '"Comma-separated fields that should be included in the returned product variants."'
schema:
type: string
- in: query
name: offset
description: The number of product variants to skip when retrieving the product variants.
schema:
type: number
default: '0'
- in: query
name: limit
description: Limit the number of product variants returned.
schema:
type: number
default: '100'
- in: query
name: cart_id
style: form
explode: false
description: The ID of the cart to use for the price selection context.
schema:
type: string
- in: query
name: region_id
style: form
explode: false
description: The ID of the region to use for the price selection context.
schema:
type: string
externalDocs:
description: Price selection context overview
url: https://docs.medusajs.com/modules/price-lists/price-selection-strategy#context-object
- in: query
name: currency_code
style: form
explode: false
description: The 3 character ISO currency code to use for the price selection context.
schema:
type: string
externalDocs:
description: Price selection context overview
url: https://docs.medusajs.com/modules/price-lists/price-selection-strategy#context-object
- in: query
name: customer_id
style: form
explode: false
description: The ID of the customer to use for the price selection context.
schema:
type: string
externalDocs:
description: Price selection context overview
url: https://docs.medusajs.com/modules/price-lists/price-selection-strategy#context-object
- in: query
name: title
style: form
explode: false
description: Filter by title.
schema:
oneOf:
- type: string
description: a single title to filter by
- type: array
description: multiple titles to filter by
items:
type: string
- in: query
name: inventory_quantity
description: Filter by available inventory quantity
schema:
oneOf:
- type: number
description: a specific number to filter by.
- type: object
description: filter using less and greater than comparisons.
properties:
lt:
type: number
description: filter by inventory quantity less than this number
gt:
type: number
description: filter by inventory quantity greater than this number
lte:
type: number
description: filter by inventory quantity less than or equal to this number
gte:
type: number
description: filter by inventory quantity greater than or equal to this number
x-codegen:
method: list
queryParams: AdminGetVariantsParams
x-codeSamples:
- lang: JavaScript
label: JS Client
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.variants.list()
.then(({ variants, limit, offset, count }) => {
console.log(variants.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminVariants } from "medusa-react"
const Variants = () => {
const { variants, isLoading } = useAdminVariants()
return (
{isLoading &&
Loading...}
{variants && !variants.length && (
No Variants
)}
{variants && variants.length > 0 && (
{variants.map((variant) => (
- {variant.title}
))}
)}
{isLoading && Loading...}
{variant && {variant.title}}
)
}
export default Variant
- lang: Shell
label: cURL
source: |
curl '{backend_url}/admin/variants/{id}' \
-H 'x-medusa-access-token: {api_token}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Product Variants
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminVariantsRes'
'400':
$ref: '#/components/responses/400_error'
'401':
$ref: '#/components/responses/unauthorized'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
/admin/variants/{id}/inventory:
get:
operationId: GetVariantsVariantInventory
summary: Get Variant's Inventory
description: Retrieve the available inventory of a Product Variant.
x-authenticated: true
parameters:
- in: path
name: id
required: true
description: The Product Variant ID.
schema:
type: string
x-codegen:
method: getInventory
x-codeSamples:
- lang: JavaScript
label: JS Client
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.variants.getInventory(variantId)
.then(({ variant }) => {
console.log(variant.inventory, variant.sales_channel_availability)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAdminVariantsInventory } from "medusa-react"
type Props = {
variantId: string
}
const VariantInventory = ({ variantId }: Props) => {
const { variant, isLoading } = useAdminVariantsInventory(
variantId
)
return (
{isLoading &&
Loading...}
{variant && variant.inventory.length === 0 && (
Variant doesn't have inventory details
)}
{variant && variant.inventory.length > 0 && (
{variant.inventory.map((inventory) => (
- {inventory.title}
))}
)}