) => {
updatePaymentSession.mutate({
provider_id: providerId,
data
}, {
onSuccess: ({ cart }) => {
console.log(cart.payment_session)
}
})
}
// ...
}
export default Cart
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/store/carts/{id}/payment-sessions/manual' \
-H 'Content-Type: application/json' \
--data-raw '{
"data": {}
}'
tags:
- Carts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreCartsRes'
'400':
$ref: '#/components/responses/400_error'
'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: DeleteCartsCartPaymentSessionsSession
summary: Delete a Payment Session
description: Delete a Payment Session in a Cart. May be useful if a payment has failed. The totals will be recalculated.
parameters:
- in: path
name: id
required: true
description: The ID of the Cart.
schema:
type: string
- in: path
name: provider_id
required: true
description: The ID of the Payment Provider used to create the Payment Session to be deleted.
schema:
type: string
x-codegen:
method: deletePaymentSession
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.carts.deletePaymentSession(cartId, "manual")
.then(({ cart }) => {
console.log(cart.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useDeletePaymentSession } from "medusa-react"
type Props = {
cartId: string
}
const Cart = ({ cartId }: Props) => {
const deletePaymentSession = useDeletePaymentSession(cartId)
const handleDeletePaymentSession = (
providerId: string
) => {
deletePaymentSession.mutate({
provider_id: providerId,
}, {
onSuccess: ({ cart }) => {
console.log(cart.payment_sessions)
}
})
}
// ...
}
export default Cart
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/store/carts/{id}/payment-sessions/{provider_id}'
tags:
- Carts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreCartsRes'
'400':
$ref: '#/components/responses/400_error'
'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'
/store/carts/{id}/payment-sessions/{provider_id}/refresh:
post:
operationId: PostCartsCartPaymentSessionsSession
summary: Refresh a Payment Session
description: Refresh a Payment Session to ensure that it is in sync with the Cart. This is usually not necessary, but is provided for edge cases.
parameters:
- in: path
name: id
required: true
description: The ID of the Cart.
schema:
type: string
- in: path
name: provider_id
required: true
description: The ID of the Payment Provider that created the Payment Session to be refreshed.
schema:
type: string
x-codegen:
method: refreshPaymentSession
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.carts.refreshPaymentSession(cartId, "manual")
.then(({ cart }) => {
console.log(cart.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useRefreshPaymentSession } from "medusa-react"
type Props = {
cartId: string
}
const Cart = ({ cartId }: Props) => {
const refreshPaymentSession = useRefreshPaymentSession(cartId)
const handleRefresh = (
providerId: string
) => {
refreshPaymentSession.mutate({
provider_id: providerId,
}, {
onSuccess: ({ cart }) => {
console.log(cart.payment_sessions)
}
})
}
// ...
}
export default Cart
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/store/carts/{id}/payment-sessions/{provider_id}/refresh'
tags:
- Carts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreCartsRes'
'400':
$ref: '#/components/responses/400_error'
'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'
/store/carts/{id}/shipping-methods:
post:
operationId: PostCartsCartShippingMethod
summary: Add Shipping Method
description: Add a Shipping Method to the Cart. The validation of the `data` field is handled by the fulfillment provider of the chosen shipping option.
parameters:
- in: path
name: id
required: true
description: The cart ID.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StorePostCartsCartShippingMethodReq'
x-codegen:
method: addShippingMethod
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.carts.addShippingMethod(cartId, {
option_id
})
.then(({ cart }) => {
console.log(cart.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAddShippingMethodToCart } from "medusa-react"
type Props = {
cartId: string
}
const Cart = ({ cartId }: Props) => {
const addShippingMethod = useAddShippingMethodToCart(cartId)
const handleAddShippingMethod = (
optionId: string
) => {
addShippingMethod.mutate({
option_id: optionId,
}, {
onSuccess: ({ cart }) => {
console.log(cart.shipping_methods)
}
})
}
// ...
}
export default Cart
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/store/carts/{id}/shipping-methods' \
-H 'Content-Type: application/json' \
--data-raw '{
"option_id": "{option_id}",
}'
tags:
- Carts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreCartsRes'
'400':
$ref: '#/components/responses/400_error'
'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'
/store/carts/{id}/taxes:
post:
operationId: PostCartsCartTaxes
summary: Calculate Cart Taxes
description: Calculate the taxes for a cart. This is useful if the `automatic_taxes` field of the cart's region is set to `false`. If the cart's region uses a tax provider other than Medusa's system provider, this may lead to sending requests to third-party services.
externalDocs:
description: How to calculate taxes manually during checkout
url: https://docs.medusajs.com/modules/taxes/storefront/manual-calculation
parameters:
- in: path
name: id
required: true
description: The Cart ID.
schema:
type: string
x-codegen:
method: calculateTaxes
x-codeSamples:
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/store/carts/{id}/taxes'
tags:
- Carts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreCartsRes'
'400':
$ref: '#/components/responses/400_error'
'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'
/store/collections:
get:
operationId: GetCollections
summary: List Collections
description: Retrieve a list of product collections. The product collections can be filtered by fields such as `handle` or `created_at`. The product collections can also be paginated.
parameters:
- in: query
name: offset
description: The number of product collections to skip when retrieving the product collections.
schema:
type: integer
default: 0
- in: query
name: limit
description: Limit the number of product collections returned.
schema:
type: integer
default: 10
- in: query
name: handle
style: form
explode: false
description: Filter by handles
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: StoreGetCollectionsParams
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.collections.list()
.then(({ collections, limit, offset, count }) => {
console.log(collections.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useCollections } from "medusa-react"
const ProductCollections = () => {
const { collections, isLoading } = useCollections()
return (
{isLoading &&
Loading...}
{collections && collections.length === 0 && (
No Product Collections
)}
{collections && collections.length > 0 && (
{collections.map((collection) => (
- {collection.title}
))}
)}
{isLoading && Loading...}
{collection && {collection.title}}
)
}
export default ProductCollection
- lang: Shell
label: cURL
source: |
curl '{backend_url}/store/collections/{id}'
tags:
- Product Collections
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreCollectionsRes'
'400':
$ref: '#/components/responses/400_error'
'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'
/store/customers:
post:
operationId: PostCustomers
summary: Create a Customer
description: Register a new customer. This will also automatically authenticate the customer and set their login session in the response Cookie header. The cookie session can be used in subsequent requests to authenticate the customer. 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/StorePostCustomersReq'
x-codegen:
method: create
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.customers.create({
first_name: "Alec",
last_name: "Reynolds",
email: "user@example.com",
password: "supersecret"
})
.then(({ customer }) => {
console.log(customer.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useCreateCustomer } from "medusa-react"
const RegisterCustomer = () => {
const createCustomer = useCreateCustomer()
// ...
const handleCreate = (
customerData: {
first_name: string
last_name: string
email: string
password: string
}
) => {
// ...
createCustomer.mutate(customerData, {
onSuccess: ({ customer }) => {
console.log(customer.id)
}
})
}
// ...
}
export default RegisterCustomer
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/store/customers' \
-H 'Content-Type: application/json' \
--data-raw '{
"first_name": "Alec",
"last_name": "Reynolds",
"email": "user@example.com",
"password": "supersecret"
}'
tags:
- Customers
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreCustomersRes'
'400':
$ref: '#/components/responses/400_error'
'404':
$ref: '#/components/responses/not_found_error'
'409':
$ref: '#/components/responses/invalid_state_error'
'422':
description: A customer with the same email exists
content:
application/json:
schema:
type: object
properties:
code:
type: string
description: The error code
type:
type: string
description: The type of error
message:
type: string
description: Human-readable message with details about the error
example:
code: invalid_request_error
type: duplicate_error
message: A customer with the given email already has an account. Log in instead
'500':
$ref: '#/components/responses/500_error'
/store/customers/me:
get:
operationId: GetCustomersCustomer
summary: Get a Customer
description: Retrieve the logged-in Customer'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
medusa.customers.retrieve()
.then(({ customer }) => {
console.log(customer.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useMeCustomer } from "medusa-react"
const Customer = () => {
const { customer, isLoading } = useMeCustomer()
return (
{isLoading && Loading...}
{customer && (
{customer.first_name} {customer.last_name}
)}
)
}
export default Customer
- lang: Shell
label: cURL
source: |
curl '{backend_url}/store/customers/me' \
-H 'Authorization: Bearer {access_token}'
security:
- cookie_auth: []
- jwt_token: []
tags:
- Customers
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreCustomersRes'
'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 Customer
description: Update the logged-in customer's details.
x-authenticated: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StorePostCustomersCustomerReq'
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
medusa.customers.update({
first_name: "Laury"
})
.then(({ customer }) => {
console.log(customer.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useUpdateMe } from "medusa-react"
type Props = {
customerId: string
}
const Customer = ({ customerId }: Props) => {
const updateCustomer = useUpdateMe()
// ...
const handleUpdate = (
firstName: string
) => {
// ...
updateCustomer.mutate({
id: customerId,
first_name: firstName,
}, {
onSuccess: ({ customer }) => {
console.log(customer.first_name)
}
})
}
// ...
}
export default Customer
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/store/customers/me' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"first_name": "Laury"
}'
security:
- cookie_auth: []
- jwt_token: []
tags:
- Customers
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreCustomersRes'
'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'
/store/customers/me/addresses:
post:
operationId: PostCustomersCustomerAddresses
summary: Add a Shipping Address
description: Add a Shipping Address to a Customer's saved addresses.
x-authenticated: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StorePostCustomersCustomerAddressesReq'
x-codegen:
method: addAddress
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
medusa.customers.addresses.addAddress({
address: {
first_name: "Celia",
last_name: "Schumm",
address_1: "225 Bednar Curve",
city: "Danielville",
country_code: "US",
postal_code: "85137",
phone: "981-596-6748 x90188",
company: "Wyman LLC",
province: "Georgia",
}
})
.then(({ customer }) => {
console.log(customer.id);
})
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/store/customers/me/addresses' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"address": {
"first_name": "Celia",
"last_name": "Schumm",
"address_1": "225 Bednar Curve",
"city": "Danielville",
"country_code": "US",
"postal_code": "85137"
}
}'
security:
- cookie_auth: []
- jwt_token: []
tags:
- Customers
responses:
'200':
description: A successful response
content:
application/json:
schema:
$ref: '#/components/schemas/StoreCustomersRes'
'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'
/store/customers/me/addresses/{address_id}:
post:
operationId: PostCustomersCustomerAddressesAddress
summary: Update a Shipping Address
description: Update the logged-in customer's saved Shipping Address's details.
x-authenticated: true
parameters:
- in: path
name: address_id
required: true
description: The ID of the Address.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StorePostCustomersCustomerAddressesAddressReq'
x-codegen:
method: updateAddress
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
medusa.customers.addresses.updateAddress(addressId, {
first_name: "Gina"
})
.then(({ customer }) => {
console.log(customer.id);
})
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/store/customers/me/addresses/{address_id}' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
--data-raw '{
"first_name": "Gina"
}'
security:
- cookie_auth: []
- jwt_token: []
tags:
- Customers
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreCustomersRes'
'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: DeleteCustomersCustomerAddressesAddress
summary: Delete an Address
description: Delete an Address from the Customer's saved addresses.
x-authenticated: true
parameters:
- in: path
name: address_id
required: true
description: The id of the Address to remove.
schema:
type: string
x-codegen:
method: deleteAddress
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
medusa.customers.addresses.deleteAddress(addressId)
.then(({ customer }) => {
console.log(customer.id);
})
- lang: Shell
label: cURL
source: |
curl -X DELETE '{backend_url}/store/customers/me/addresses/{address_id}' \
-H 'Authorization: Bearer {access_token}'
security:
- cookie_auth: []
- jwt_token: []
tags:
- Customers
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreCustomersRes'
'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'
/store/customers/me/orders:
get:
operationId: GetCustomersCustomerOrders
summary: List Orders
description: Retrieve a list of the logged-in Customer's Orders. The orders can be filtered by fields such as `status` or `fulfillment_status`. The orders can also be paginated.
x-authenticated: true
parameters:
- in: query
name: q
description: term to search orders' display ID, email, shipping address's first name, customer's first name, customer's last name, and customer's phone number.
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: Fulfillment status to search for.
schema:
type: array
items:
type: string
enum:
- not_fulfilled
- partially_fulfilled
- fulfilled
- partially_shipped
- shipped
- partially_returned
- returned
- canceled
- requires_action
- in: query
name: payment_status
style: form
explode: false
description: Payment status to search for.
schema:
type: array
items:
type: string
enum:
- not_paid
- awaiting
- captured
- partially_refunded
- 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: email
description: Filter by email.
schema:
type: string
- in: query
name: region_id
description: Filter by region ID.
schema:
type: string
- in: query
name: currency_code
style: form
explode: false
description: Filter by the 3 character ISO currency code of the order.
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: limit
description: Limit the number of orders returned.
schema:
type: integer
default: 10
- in: query
name: offset
description: The number of orders to skip when retrieving the orders.
schema:
type: integer
default: 0
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned orders.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned orders.
schema:
type: string
x-codegen:
method: listOrders
queryParams: StoreGetCustomersCustomerOrdersParams
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
medusa.customers.listOrders()
.then(({ orders, limit, offset, count }) => {
console.log(orders);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useCustomerOrders } from "medusa-react"
const Orders = () => {
// refetch a function that can be used to
// re-retrieve orders after the customer logs in
const { orders, isLoading } = useCustomerOrders()
return (
{isLoading &&
Loading orders...}
{orders?.length && (
{orders.map((order) => (
- {order.display_id}
))}
)}
{isLoading && Loading...}
{gift_card && {gift_card.value}}
{isError && Gift Card does not exist}
)
}
export default GiftCard
- lang: Shell
label: cURL
source: |
curl '{backend_url}/store/gift-cards/{code}'
tags:
- Gift Cards
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreGiftCardsRes'
'400':
$ref: '#/components/responses/400_error'
'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'
/store/order-edits/{id}:
get:
operationId: GetOrderEditsOrderEdit
summary: Retrieve an Order Edit
description: Retrieve an Order Edit's details.
parameters:
- in: path
name: id
required: true
description: The ID of the OrderEdit.
schema:
type: string
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 })
medusa.orderEdits.retrieve(orderEditId)
.then(({ order_edit }) => {
console.log(order_edit.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useOrderEdit } from "medusa-react"
type Props = {
orderEditId: string
}
const OrderEdit = ({ orderEditId }: Props) => {
const { order_edit, isLoading } = useOrderEdit(orderEditId)
return (
{isLoading &&
Loading...}
{order_edit && (
{order_edit.changes.map((change) => (
- {change.type}
))}
)}
{isLoading && Loading...}
{order && {order.display_id}}
)
}
export default Order
- lang: Shell
label: cURL
source: |
curl '{backend_url}/store/orders?display_id=1&email=user@example.com'
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'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'
/store/orders/batch/customer/token:
post:
operationId: PostOrdersCustomerOrderClaim
summary: Claim Order
description: Allow the logged-in customer to claim ownership of one or more orders. This generates a token that can be used later on to verify the claim using the Verify Order Claim API Route. This also emits the event `order-update-token.created`. So, if you have a notification provider installed that handles this event and sends the customer a notification, such as an email, the customer should receive instructions on how to finalize their claim ownership.
externalDocs:
description: How to implement claim-order flow in a storefront
url: https://docs.medusajs.com/modules/orders/storefront/implement-claim-order
x-authenticated: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StorePostCustomersCustomerOrderClaimReq'
x-codegen:
method: requestCustomerOrders
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.orders.requestCustomerOrders({
order_ids,
})
.then(() => {
// successful
})
.catch(() => {
// an error occurred
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useRequestOrderAccess } from "medusa-react"
const ClaimOrder = () => {
const claimOrder = useRequestOrderAccess()
const handleClaimOrder = (
orderIds: string[]
) => {
claimOrder.mutate({
order_ids: orderIds
}, {
onSuccess: () => {
// successful
},
onError: () => {
// an error occurred.
}
})
}
// ...
}
export default ClaimOrder
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/store/batch/customer/token' \
-H 'Content-Type: application/json' \
--data-raw '{
"order_ids": ["id"],
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
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'
/store/orders/cart/{cart_id}:
get:
operationId: GetOrdersOrderCartId
summary: Get by Cart ID
description: Retrieve an Order's details by the ID of the Cart that was used to create the Order.
parameters:
- in: path
name: cart_id
required: true
description: The ID of Cart.
schema:
type: string
x-codegen:
method: retrieveByCartId
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.orders.retrieveByCartId(cartId)
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useCartOrder } from "medusa-react"
type Props = {
cartId: string
}
const Order = ({ cartId }: Props) => {
const {
order,
isLoading,
} = useCartOrder(cartId)
return (
{isLoading && Loading...}
{order && {order.display_id}}
)
}
export default Order
- lang: Shell
label: cURL
source: |
curl '{backend_url}/store/orders/cart/{cart_id}'
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'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'
/store/orders/customer/confirm:
post:
operationId: PostOrdersCustomerOrderClaimsCustomerOrderClaimAccept
summary: Verify Order Claim
description: Verify the claim order token provided to the customer when they request ownership of an order.
externalDocs:
description: How to implement claim-order flow in a storefront
url: https://docs.medusajs.com/modules/orders/storefront/implement-claim-order
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StorePostCustomersCustomerAcceptClaimReq'
x-codegen:
method: confirmRequest
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.orders.confirmRequest(
token,
)
.then(() => {
// successful
})
.catch(() => {
// an error occurred
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useGrantOrderAccess } from "medusa-react"
const ClaimOrder = () => {
const confirmOrderRequest = useGrantOrderAccess()
const handleOrderRequestConfirmation = (
token: string
) => {
confirmOrderRequest.mutate({
token
}, {
onSuccess: () => {
// successful
},
onError: () => {
// an error occurred.
}
})
}
// ...
}
export default ClaimOrder
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/store/orders/customer/confirm' \
-H 'Content-Type: application/json' \
--data-raw '{
"token": "{token}",
}'
security:
- api_token: []
- cookie_auth: []
- jwt_token: []
tags:
- Orders
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'
/store/orders/{id}:
get:
operationId: GetOrdersOrder
summary: Get an Order
description: Retrieve an Order's details.
parameters:
- in: path
name: id
required: true
description: The ID of the Order.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be expanded in the returned order.
schema:
type: string
- in: query
name: expand
description: Comma-separated relations that should be included in the returned order.
schema:
type: string
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 })
medusa.orders.retrieve(orderId)
.then(({ order }) => {
console.log(order.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useOrder } from "medusa-react"
type Props = {
orderId: string
}
const Order = ({ orderId }: Props) => {
const {
order,
isLoading,
} = useOrder(orderId)
return (
{isLoading && Loading...}
{order && {order.display_id}}
)
}
export default Order
- lang: Shell
label: cURL
source: |
curl '{backend_url}/store/orders/{id}'
tags:
- Orders
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreOrdersRes'
'400':
$ref: '#/components/responses/400_error'
'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'
/store/payment-collections/{id}:
get:
operationId: GetPaymentCollectionsPaymentCollection
summary: Get a PaymentCollection
description: Retrieve a Payment Collection's details.
x-authenticated: false
parameters:
- in: path
name: id
required: true
description: The ID of the PaymentCollection.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be expanded in the returned 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
x-codegen:
method: retrieve
queryParams: StoreGetPaymentCollectionsParams
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.paymentCollections.retrieve(paymentCollectionId)
.then(({ payment_collection }) => {
console.log(payment_collection.id)
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { usePaymentCollection } from "medusa-react"
type Props = {
paymentCollectionId: string
}
const PaymentCollection = ({
paymentCollectionId
}: Props) => {
const {
payment_collection,
isLoading
} = usePaymentCollection(
paymentCollectionId
)
return (
{isLoading && Loading...}
{payment_collection && (
{payment_collection.status}
)}
)
}
export default PaymentCollection
- lang: Shell
label: cURL
source: |
curl '{backend_url}/store/payment-collections/{id}'
security:
- cookie_auth: []
- jwt_token: []
tags:
- Payment Collections
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StorePaymentCollectionsRes'
'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'
/store/payment-collections/{id}/sessions:
post:
operationId: PostPaymentCollectionsSessions
summary: Create a Payment Session
description: Create a Payment Session for a payment provider in a Payment Collection.
x-authenticated: false
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/StorePaymentCollectionSessionsReq'
x-codegen:
method: managePaymentSession
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.paymentCollections.managePaymentSession(payment_id, { provider_id: "stripe" })
.then(({ payment_collection }) => {
console.log(payment_collection.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useManagePaymentSession } from "medusa-react"
type Props = {
paymentCollectionId: string
}
const PaymentCollection = ({
paymentCollectionId
}: Props) => {
const managePaymentSession = useManagePaymentSession(
paymentCollectionId
)
const handleManagePaymentSession = (
providerId: string
) => {
managePaymentSession.mutate({
provider_id: providerId
}, {
onSuccess: ({ payment_collection }) => {
console.log(payment_collection.payment_sessions)
}
})
}
// ...
}
export default PaymentCollection
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/store/payment-collections/{id}/sessions' \
-H 'Content-Type: application/json' \
--data-raw '{
"provider_id": "stripe"
}'
security:
- cookie_auth: []
- jwt_token: []
tags:
- Payment Collections
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StorePaymentCollectionsRes'
'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'
/store/payment-collections/{id}/sessions/batch:
post:
operationId: PostPaymentCollectionsPaymentCollectionSessionsBatch
summary: Manage Payment Sessions
description: Create, update, or delete a list of payment sessions of a Payment Collections. If a payment session is not provided in the `sessions` array, it's deleted.
x-authenticated: false
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/StorePostPaymentCollectionsBatchSessionsReq'
x-codegen:
method: managePaymentSessionsBatch
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
// Total amount = 10000
// Example 1: Adding two new sessions
medusa.paymentCollections.managePaymentSessionsBatch(paymentId, {
sessions: [
{
provider_id: "stripe",
amount: 5000,
},
{
provider_id: "manual",
amount: 5000,
},
]
})
.then(({ payment_collection }) => {
console.log(payment_collection.id);
})
// Example 2: Updating one session and removing the other
medusa.paymentCollections.managePaymentSessionsBatch(paymentId, {
sessions: [
{
provider_id: "stripe",
amount: 10000,
session_id: "ps_123456"
},
]
})
.then(({ payment_collection }) => {
console.log(payment_collection.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useManageMultiplePaymentSessions } from "medusa-react"
type Props = {
paymentCollectionId: string
}
const PaymentCollection = ({
paymentCollectionId
}: Props) => {
const managePaymentSessions = useManageMultiplePaymentSessions(
paymentCollectionId
)
const handleManagePaymentSessions = () => {
// Total amount = 10000
// Example 1: Adding two new sessions
managePaymentSessions.mutate({
sessions: [
{
provider_id: "stripe",
amount: 5000,
},
{
provider_id: "manual",
amount: 5000,
},
]
}, {
onSuccess: ({ payment_collection }) => {
console.log(payment_collection.payment_sessions)
}
})
// Example 2: Updating one session and removing the other
managePaymentSessions.mutate({
sessions: [
{
provider_id: "stripe",
amount: 10000,
session_id: "ps_123456"
},
]
}, {
onSuccess: ({ payment_collection }) => {
console.log(payment_collection.payment_sessions)
}
})
}
// ...
}
export default PaymentCollection
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/store/payment-collections/{id}/sessions/batch' \
-H 'Content-Type: application/json' \
--data-raw '{
"sessions": [
{
"provider_id": "stripe",
"amount": 5000
},
{
"provider_id": "manual",
"amount": 5000
}
]
}'
security:
- cookie_auth: []
- jwt_token: []
tags:
- Payment Collections
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StorePaymentCollectionsRes'
'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'
/store/payment-collections/{id}/sessions/batch/authorize:
post:
operationId: PostPaymentCollectionsSessionsBatchAuthorize
summary: Authorize Payment Sessions
description: Authorize the Payment Sessions of a Payment Collection.
x-authenticated: false
parameters:
- in: path
name: id
required: true
description: The ID of the Payment Collections.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StorePostPaymentCollectionsBatchSessionsAuthorizeReq'
x-codegen:
method: authorizePaymentSessionsBatch
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.paymentCollections.authorize(paymentId)
.then(({ payment_collection }) => {
console.log(payment_collection.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAuthorizePaymentSessionsBatch } from "medusa-react"
type Props = {
paymentCollectionId: string
}
const PaymentCollection = ({
paymentCollectionId
}: Props) => {
const authorizePaymentSessions = useAuthorizePaymentSessionsBatch(
paymentCollectionId
)
// ...
const handleAuthorizePayments = (paymentSessionIds: string[]) => {
authorizePaymentSessions.mutate({
session_ids: paymentSessionIds
}, {
onSuccess: ({ payment_collection }) => {
console.log(payment_collection.payment_sessions)
}
})
}
// ...
}
export default PaymentCollection
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/store/payment-collections/{id}/sessions/batch/authorize'
security:
- cookie_auth: []
- jwt_token: []
tags:
- Payment Collections
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StorePaymentCollectionsRes'
'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'
/store/payment-collections/{id}/sessions/{session_id}:
post:
operationId: PostPaymentCollectionsPaymentCollectionPaymentSessionsSession
summary: Refresh a Payment Session
description: Refresh a Payment Session's data to ensure that it is in sync with the Payment Collection.
x-authenticated: false
parameters:
- in: path
name: id
required: true
description: The id of the PaymentCollection.
schema:
type: string
- in: path
name: session_id
required: true
description: The id of the Payment Session to be refreshed.
schema:
type: string
x-codegen:
method: refreshPaymentSession
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.paymentCollections.refreshPaymentSession(paymentCollectionId, sessionId)
.then(({ payment_session }) => {
console.log(payment_session.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { usePaymentCollectionRefreshPaymentSession } from "medusa-react"
type Props = {
paymentCollectionId: string
}
const PaymentCollection = ({
paymentCollectionId
}: Props) => {
const refreshPaymentSession = usePaymentCollectionRefreshPaymentSession(
paymentCollectionId
)
// ...
const handleRefreshPaymentSession = (paymentSessionId: string) => {
refreshPaymentSession.mutate(paymentSessionId, {
onSuccess: ({ payment_session }) => {
console.log(payment_session.status)
}
})
}
// ...
}
export default PaymentCollection
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/store/payment-collections/{id}/sessions/{session_id}'
security:
- cookie_auth: []
- jwt_token: []
tags:
- Payment Collections
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StorePaymentCollectionsSessionRes'
'400':
$ref: '#/components/responses/400_error'
'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'
/store/payment-collections/{id}/sessions/{session_id}/authorize:
post:
operationId: PostPaymentCollectionsSessionsSessionAuthorize
summary: Authorize Payment Session
description: Authorize a Payment Session of a Payment Collection.
x-authenticated: false
parameters:
- in: path
name: id
required: true
description: The ID of the Payment Collection.
schema:
type: string
- in: path
name: session_id
required: true
description: The ID of the Payment Session.
schema:
type: string
x-codegen:
method: authorizePaymentSession
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.paymentCollections.authorize(paymentId, sessionId)
.then(({ payment_collection }) => {
console.log(payment_collection.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useAuthorizePaymentSession } from "medusa-react"
type Props = {
paymentCollectionId: string
}
const PaymentCollection = ({
paymentCollectionId
}: Props) => {
const authorizePaymentSession = useAuthorizePaymentSession(
paymentCollectionId
)
// ...
const handleAuthorizePayment = (paymentSessionId: string) => {
authorizePaymentSession.mutate(paymentSessionId, {
onSuccess: ({ payment_collection }) => {
console.log(payment_collection.payment_sessions)
}
})
}
// ...
}
export default PaymentCollection
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/store/payment-collections/{id}/sessions/{session_id}/authorize'
security:
- cookie_auth: []
- jwt_token: []
tags:
- Payment Collections
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StorePaymentCollectionsSessionRes'
'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'
/store/product-categories:
get:
operationId: GetProductCategories
summary: List Product Categories
description: Retrieve a list of product categories. The product categories can be filtered by fields such as `handle` or `q`. The product categories can also be paginated. This API Route can also be used to retrieve a product category by its handle.
x-featureFlag: product_categories
externalDocs:
description: How to retrieve a product category by its handle
url: https://docs.medusajs.com/modules/products/storefront/use-categories#get-a-category-by-its-handle
parameters:
- in: query
name: q
description: term used to search product category's names and handles.
schema:
type: string
- in: query
name: handle
description: Filter by handle.
schema:
type: string
- in: query
name: parent_category_id
description: Filter by the ID of a parent category. Only children of the provided parent category are retrieved.
schema:
type: string
- in: query
name: include_descendants_tree
description: Whether all nested categories inside a category should be retrieved.
schema:
type: boolean
- in: query
name: offset
description: The number of product categories to skip when retrieving the product categories.
schema:
type: integer
default: 0
- in: query
name: limit
description: Limit the number of product categories returned.
schema:
type: integer
default: 100
- in: query
name: expand
description: Comma-separated relations that should be expanded in the returned product categories.
schema:
type: string
- in: query
name: fields
description: Comma-separated fields that should be included in the returned product categories.
schema:
type: string
x-codegen:
method: list
queryParams: StoreGetProductCategoriesParams
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.productCategories.list()
.then(({ product_categories, limit, offset, count }) => {
console.log(product_categories.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useProductCategories } from "medusa-react"
function Categories() {
const {
product_categories,
isLoading,
} = useProductCategories()
return (
{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}/store/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/StoreGetProductCategoriesCategoryRes'
'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'
/store/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 `id` or `q`. The product tags can also be sorted or paginated.
x-authenticated: true
x-codegen:
method: list
queryParams: StoreGetProductTagsParams
parameters:
- in: query
name: limit
description: Limit the number of product tags returned.
schema:
type: integer
default: 20
- 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. When provided, only tags that the discount condition applies for will be retrieved.
schema:
type: string
- in: query
name: value
style: form
explode: false
description: Filter by tag values.
schema:
type: array
items:
type: string
- in: query
name: id
style: form
explode: false
description: Filter by IDs.
schema:
type: array
items:
type: string
- in: query
name: q
description: term to search product tag's value.
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-codeSamples:
- lang: JavaScript
label: JS Client
source: |
import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
medusa.productTags.list()
.then(({ product_tags }) => {
console.log(product_tags.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useProductTags } from "medusa-react"
function Tags() {
const {
product_tags,
isLoading,
} = useProductTags()
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 Types
)}
{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...}
{product && {product.title}}
)
}
export default Product
- lang: Shell
label: cURL
source: |
curl '{backend_url}/store/products/{id}'
tags:
- Products
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreProductsRes'
'400':
$ref: '#/components/responses/400_error'
'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'
/store/regions:
get:
operationId: GetRegions
summary: List Regions
description: Retrieve a list of regions. The regions can be filtered by fields such as `created_at`. The regions can also be paginated. This API Route is useful to show the customer all available regions to choose from.
externalDocs:
description: How to use regions in a storefront
url: https://docs.medusajs.com/modules/regions-and-currencies/storefront/use-regions
parameters:
- in: query
name: offset
description: The number of regions to skip when retrieving the regions.
schema:
type: integer
default: 0
- in: query
name: limit
description: Limit the number of regions returned.
schema:
type: integer
default: 100
- 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: StoreGetRegionsParams
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.regions.list()
.then(({ regions, count, limit, offset }) => {
console.log(regions.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useRegions } from "medusa-react"
const Regions = () => {
const { regions, isLoading } = useRegions()
return (
{isLoading &&
Loading...}
{regions?.length && (
{regions.map((region) => (
-
{region.name}
))}
)}
{isLoading && Loading...}
{region && {region.name}}
)
}
export default Region
- lang: Shell
label: cURL
source: |
curl '{backend_url}/store/regions/{id}'
tags:
- Regions
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreRegionsRes'
'400':
$ref: '#/components/responses/400_error'
'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'
/store/return-reasons:
get:
operationId: GetReturnReasons
summary: List Return Reasons
description: Retrieve a list of Return Reasons. This is useful when implementing a Create Return flow in the storefront.
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 })
medusa.returnReasons.list()
.then(({ return_reasons }) => {
console.log(return_reasons.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useReturnReasons } from "medusa-react"
const ReturnReasons = () => {
const {
return_reasons,
isLoading
} = useReturnReasons()
return (
{isLoading &&
Loading...}
{return_reasons?.length && (
{return_reasons.map((returnReason) => (
-
{returnReason.label}
))}
)}
{isLoading && Loading...}
{return_reason && {return_reason.label}}
)
}
export default ReturnReason
- lang: Shell
label: cURL
source: |
curl '{backend_url}/store/return-reasons/{id}'
tags:
- Return Reasons
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreReturnReasonsRes'
'400':
$ref: '#/components/responses/400_error'
'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'
/store/returns:
post:
operationId: PostReturns
summary: Create Return
description: Create a Return for an Order. If a return shipping method is specified, the return is automatically fulfilled.
externalDocs:
description: How to create a return in a storefront
url: https://docs.medusajs.com/modules/orders/storefront/create-return
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StorePostReturnsReq'
x-codegen:
method: create
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.returns.create({
order_id,
items: [
{
item_id,
quantity: 1
}
]
})
.then((data) => {
console.log(data.return.id);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useCreateReturn } from "medusa-react"
type CreateReturnData = {
items: {
item_id: string,
quantity: number
}[]
return_shipping: {
option_id: string
}
}
type Props = {
orderId: string
}
const CreateReturn = ({ orderId }: Props) => {
const createReturn = useCreateReturn()
// ...
const handleCreate = (data: CreateReturnData) => {
createReturn.mutate({
...data,
order_id: orderId
}, {
onSuccess: ({ return: returnData }) => {
console.log(returnData.id)
}
})
}
// ...
}
export default CreateReturn
- lang: Shell
label: cURL
source: |
curl -X POST '{backend_url}/store/returns' \
-H 'Content-Type: application/json' \
--data-raw '{
"order_id": "asfasf",
"items": [
{
"item_id": "assfasf",
"quantity": 1
}
]
}'
tags:
- Returns
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreReturnsRes'
'400':
$ref: '#/components/responses/400_error'
'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'
/store/shipping-options:
get:
operationId: GetShippingOptions
summary: Get Shipping Options
description: Retrieve a list of Shipping Options.
parameters:
- in: query
name: is_return
description: Whether return shipping options should be included. By default, all shipping options are returned.
schema:
type: boolean
- in: query
name: product_ids
description: '"Comma-separated list of Product IDs to filter Shipping Options by. If provided, only shipping options that can be used with the provided products are retrieved."'
schema:
type: string
- in: query
name: region_id
description: '"The ID of the region that the shipping options belong to. If not provided, all shipping options are retrieved."'
schema:
type: string
x-codegen:
method: list
queryParams: StoreGetShippingOptionsParams
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.shippingOptions.list()
.then(({ shipping_options }) => {
console.log(shipping_options.length);
})
- lang: tsx
label: Medusa React
source: |
import React from "react"
import { useShippingOptions } from "medusa-react"
const ShippingOptions = () => {
const {
shipping_options,
isLoading,
} = useShippingOptions()
return (
{isLoading &&
Loading...}
{shipping_options?.length &&
shipping_options?.length > 0 && (
{shipping_options?.map((shipping_option) => (
-
{shipping_option.id}
))}
)}
{isLoading &&
Loading...}
{shipping_options && !shipping_options.length && (
No shipping options
)}
{shipping_options && (
{shipping_options.map(
(shipping_option) => (
-
{shipping_option.name}
)
)}
)}
{isLoading && Loading...}
{swap && {swap.id}}
)
}
export default Swap
- lang: Shell
label: cURL
source: |
curl '{backend_url}/store/swaps/{cart_id}'
tags:
- Swaps
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreSwapsRes'
'400':
$ref: '#/components/responses/400_error'
'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'
/store/variants:
get:
operationId: GetVariants
summary: Get Product Variants
description: |
Retrieves a list of product variants. The product variants can be filtered by fields such as `id` or `title`. The product variants can also be paginated.
For accurate and correct pricing of the product variants based on the customer's context, it's highly recommended to pass fields such as
`region_id`, `currency_code`, and `cart_id` when available.
Passing `sales_channel_id` ensures retrieving only variants of products available in the specified sales channel.
You can alternatively use a publishable API key in the request header instead of passing a `sales_channel_id`.
externalDocs:
description: How to pass product pricing parameters
url: https://docs.medusajs.com/modules/products/storefront/show-products#product-pricing-parameters
parameters:
- in: query
name: ids
description: Filter by a comma-separated list of IDs. If supplied, it overrides the `id` parameter.
schema:
type: string
- in: query
name: id
style: form
explode: false
description: Filter by one or more IDs. If `ids` is supplied, it's overrides the value of this parameter.
schema:
oneOf:
- type: string
description: Filter by an ID.
- type: array
description: Filter by IDs.
items:
type: string
- in: query
name: sales_channel_id
description: '"Filter by sales channel IDs. When provided, only products available in the selected sales channels are retrieved. Alternatively, you can pass a publishable API key in the request header and this will have the same effect."'
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: 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 products 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
description: The ID of the cart. This is useful for accurate pricing based on the cart's context.
schema:
type: string
- in: query
name: region_id
description: The ID of the region. This is useful for accurate pricing based on the selected region.
schema:
type: string
- in: query
name: currency_code
style: form
explode: false
description: A 3 character ISO currency code. This is useful for accurate pricing based on the selected currency.
schema:
type: string
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
description: See a list of codes.
- 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: StoreGetVariantsParams
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.product.variants.list()
.then(({ variants }) => {
console.log(variants.length);
})
- lang: Shell
label: cURL
source: |
curl '{backend_url}/store/variants'
tags:
- Product Variants
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreVariantsListRes'
'400':
$ref: '#/components/responses/400_error'
'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'
/store/variants/{id}:
get:
operationId: GetVariantsVariant
summary: Get a Product Variant
description: |
Retrieve a Product Variant's details. For accurate and correct pricing of the product variant based on the customer's context, it's highly recommended to pass fields such as
`region_id`, `currency_code`, and `cart_id` when available.
Passing `sales_channel_id` ensures retrieving only variants of products available in the current sales channel.
You can alternatively use a publishable API key in the request header instead of passing a `sales_channel_id`.
externalDocs:
description: How to pass product pricing parameters
url: https://docs.medusajs.com/modules/products/storefront/show-products#product-pricing-parameters
parameters:
- in: path
name: id
required: true
description: The ID of the Product Variant.
schema:
type: string
- in: query
name: sales_channel_id
description: The ID of the sales channel the customer is viewing the product variant from.
schema:
type: string
- in: query
name: cart_id
description: The ID of the cart. This is useful for accurate pricing based on the cart's context.
schema:
type: string
- in: query
name: region_id
description: The ID of the region. This is useful for accurate pricing based on the selected region.
schema:
type: string
- in: query
name: currency_code
style: form
explode: false
description: A 3 character ISO currency code. This is useful for accurate pricing based on the selected currency.
schema:
type: string
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
description: See a list of codes.
x-codegen:
method: retrieve
queryParams: StoreGetVariantsVariantParams
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.product.variants.retrieve(productVariantId)
.then(({ variant }) => {
console.log(variant.id);
})
- lang: Shell
label: cURL
source: |
curl '{backend_url}/store/variants/{id}'
tags:
- Product Variants
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreVariantsRes'
'400':
$ref: '#/components/responses/400_error'
'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'
components:
responses:
default_error:
description: Default Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: unknown_error
message: An unknown error occurred.
type: unknown_error
invalid_state_error:
description: Invalid State Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: unknown_error
message: The request conflicted with another request. You may retry the request with the provided Idempotency-Key.
type: QueryRunnerAlreadyReleasedError
invalid_request_error:
description: Invalid Request Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: invalid_request_error
message: Discount with code TEST already exists.
type: duplicate_error
not_found_error:
description: Not Found Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Entity with id 1 was not found
type: not_found
400_error:
description: Client Error or Multiple Errors
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/MultipleErrors'
examples:
not_allowed:
$ref: '#/components/examples/not_allowed_error'
invalid_data:
$ref: '#/components/examples/invalid_data_error'
MultipleErrors:
$ref: '#/components/examples/multiple_errors'
500_error:
description: Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
database:
$ref: '#/components/examples/database_error'
unexpected_state:
$ref: '#/components/examples/unexpected_state_error'
invalid_argument:
$ref: '#/components/examples/invalid_argument_error'
default_error:
$ref: '#/components/examples/default_error'
unauthorized:
description: User is not authorized. Must log in first
content:
text/plain:
schema:
type: string
default: Unauthorized
example: Unauthorized
incorrect_credentials:
description: User does not exist or incorrect credentials
content:
text/plain:
schema:
type: string
default: Unauthorized
example: Unauthorized
examples:
not_allowed_error:
summary: Not Allowed Error
value:
message: Discount must be set to dynamic
type: not_allowed
invalid_data_error:
summary: Invalid Data Error
value:
message: first_name must be a string
type: invalid_data
multiple_errors:
summary: Multiple Errors
value:
message: Provided request body contains errors. Please check the data and retry the request
errors:
- message: first_name must be a string
type: invalid_data
- message: Discount must be set to dynamic
type: not_allowed
database_error:
summary: Database Error
value:
code: api_error
message: An error occured while hashing password
type: database_error
unexpected_state_error:
summary: Unexpected State Error
value:
message: cart.total must be defined
type: unexpected_state
invalid_argument_error:
summary: Invalid Argument Error
value:
message: cart.total must be defined
type: unexpected_state
default_error:
summary: Default Error
value:
code: unknown_error
message: An unknown error occurred.
type: unknown_error
securitySchemes:
jwt_token:
type: http
x-displayName: JWT Token
scheme: bearer
cookie_auth:
type: apiKey
x-displayName: Cookie Session ID
in: cookie
name: connect.sid
description: |
Use a cookie session to send authenticated requests.
### How to Obtain the Cookie Session
If you're sending requests through a browser, using JS Client, or using tools like Postman, the cookie session should be automatically set when the customer is logged in.
If you're sending requests using cURL, you must set the Session ID in the cookie manually.
To do that, send a request to [authenticate the customer](#tag/Auth/operation/PostAuth) and pass the cURL option `-v`:
```bash
curl -v --location --request POST 'https://medusa-url.com/store/auth' \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "user@example.com",
"password": "supersecret"
}'
```
The headers will be logged in the terminal as well as the response. You should find in the headers a Cookie header similar to this:
```bash
Set-Cookie: connect.sid=s%3A2Bu8BkaP9JUfHu9rG59G16Ma0QZf6Gj1.WT549XqX37PN8n0OecqnMCq798eLjZC5IT7yiDCBHPM;
```
Copy the value after `connect.sid` (without the `;` at the end) and pass it as a cookie in subsequent requests as the following:
```bash
curl --location --request GET 'https://medusa-url.com/store/customers/me/orders' \
--header 'Cookie: connect.sid={sid}'
```
Where `{sid}` is the value of `connect.sid` that you copied.
schemas:
Address:
title: Address
description: An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
type: object
required:
- address_1
- address_2
- city
- company
- country_code
- created_at
- customer_id
- deleted_at
- first_name
- id
- last_name
- metadata
- phone
- postal_code
- province
- updated_at
properties:
id:
type: string
description: ID of the address
example: addr_01G8ZC9VS1XVE149MGH2J7QSSH
customer_id:
description: ID of the customer this address belongs to
nullable: true
type: string
example: cus_01G2SG30J8C85S4A5CHM2S1NS2
customer:
description: Available if the relation `customer` is expanded.
nullable: true
type: object
company:
description: Company name
nullable: true
type: string
example: Acme
first_name:
description: First name
nullable: true
type: string
example: Arno
last_name:
description: Last name
nullable: true
type: string
example: Willms
address_1:
description: Address line 1
nullable: true
type: string
example: 14433 Kemmer Court
address_2:
description: Address line 2
nullable: true
type: string
example: Suite 369
city:
description: City
nullable: true
type: string
example: South Geoffreyview
country_code:
description: The 2 character ISO code of the country in lower case
nullable: true
type: string
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
description: See a list of codes.
example: st
country:
description: A country object.
x-expandable: country
nullable: true
$ref: '#/components/schemas/Country'
province:
description: Province
nullable: true
type: string
example: Kentucky
postal_code:
description: Postal Code
nullable: true
type: string
example: 72093
phone:
description: Phone Number
nullable: true
type: string
example: 16128234334802
created_at:
type: string
description: The date with timezone at which the resource was created.
format: date-time
updated_at:
type: string
description: The date with timezone at which the resource was updated.
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
AddressCreatePayload:
type: object
description: Address fields used when creating an address.
required:
- first_name
- last_name
- address_1
- city
- country_code
- postal_code
properties:
first_name:
description: First name
type: string
example: Arno
last_name:
description: Last name
type: string
example: Willms
phone:
type: string
description: Phone Number
example: 16128234334802
company:
type: string
address_1:
description: Address line 1
type: string
example: 14433 Kemmer Court
address_2:
description: Address line 2
type: string
example: Suite 369
city:
description: City
type: string
example: South Geoffreyview
country_code:
description: The 2 character ISO code of the country in lower case
type: string
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
description: See a list of codes.
example: st
province:
description: Province
type: string
example: Kentucky
postal_code:
description: Postal Code
type: string
example: 72093
metadata:
type: object
example:
car: white
description: An optional key-value map with additional details
AddressPayload:
type: object
description: Address fields used when creating/updating an address.
properties:
first_name:
description: First name
type: string
example: Arno
last_name:
description: Last name
type: string
example: Willms
phone:
type: string
description: Phone Number
example: 16128234334802
company:
type: string
description: Company
address_1:
description: Address line 1
type: string
example: 14433 Kemmer Court
address_2:
description: Address line 2
type: string
example: Suite 369
city:
description: City
type: string
example: South Geoffreyview
country_code:
description: The 2 character ISO code of the country in lower case
type: string
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
description: See a list of codes.
example: st
province:
description: Province
type: string
example: Kentucky
postal_code:
description: Postal Code
type: string
example: 72093
metadata:
type: object
example:
car: white
description: An optional key-value map with additional details
BatchJob:
title: Batch Job
description: A Batch Job indicates an asynchronus task stored in the Medusa backend. Its status determines whether it has been executed or not.
type: object
required:
- canceled_at
- completed_at
- confirmed_at
- context
- created_at
- created_by
- deleted_at
- dry_run
- failed_at
- id
- pre_processed_at
- processing_at
- result
- status
- type
- updated_at
properties:
id:
description: The unique identifier for the batch job.
type: string
example: batch_01G8T782965PYFG0751G0Z38B4
type:
description: The type of batch job.
type: string
enum:
- product-import
- product-export
status:
description: The status of the batch job.
type: string
enum:
- created
- pre_processed
- confirmed
- processing
- completed
- canceled
- failed
default: created
created_by:
description: The unique identifier of the user that created the batch job.
nullable: true
type: string
example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V
created_by_user:
description: The details of the user that created the batch job.
x-expandable: created_by_user
nullable: true
$ref: '#/components/schemas/User'
context:
description: The context of the batch job, the type of the batch job determines what the context should contain.
nullable: true
type: object
example:
shape:
prices:
- region: null
currency_code: eur
dynamicImageColumnCount: 4
dynamicOptionColumnCount: 2
list_config:
skip: 0
take: 50
order:
created_at: DESC
relations:
- variants
- variant.prices
- images
dry_run:
description: Specify if the job must apply the modifications or not.
type: boolean
default: false
result:
description: The result of the batch job.
nullable: true
allOf:
- type: object
example: {}
- type: object
properties:
count:
type: number
advancement_count:
type: number
progress:
type: number
errors:
type: object
properties:
message:
type: string
code:
oneOf:
- type: string
- type: number
err:
type: array
stat_descriptors:
type: object
properties:
key:
type: string
name:
type: string
message:
type: string
file_key:
type: string
file_size:
type: number
example:
errors:
- err: []
code: unknown
message: Method not implemented.
stat_descriptors:
- key: product-export-count
name: Product count to export
message: There will be 8 products exported by this action
pre_processed_at:
description: The date from which the job has been pre-processed.
nullable: true
type: string
format: date-time
processing_at:
description: The date the job is processing at.
nullable: true
type: string
format: date-time
confirmed_at:
description: The date when the confirmation has been done.
nullable: true
type: string
format: date-time
completed_at:
description: The date of the completion.
nullable: true
type: string
format: date-time
canceled_at:
description: The date of the concellation.
nullable: true
type: string
format: date-time
failed_at:
description: The date when the job failed.
nullable: true
type: string
format: date-time
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was last updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
Cart:
title: Cart
description: A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.
type: object
required:
- billing_address_id
- completed_at
- context
- created_at
- customer_id
- deleted_at
- email
- id
- idempotency_key
- metadata
- payment_authorized_at
- payment_id
- payment_session
- region_id
- shipping_address_id
- type
- updated_at
properties:
id:
description: The cart's ID
type: string
example: cart_01G8ZH853Y6TFXWPG5EYE81X63
email:
description: The email associated with the cart
nullable: true
type: string
format: email
billing_address_id:
description: The billing address's ID
nullable: true
type: string
example: addr_01G8ZH853YPY9B94857DY91YGW
billing_address:
description: The details of the billing address associated with the cart.
x-expandable: billing_address
nullable: true
$ref: '#/components/schemas/Address'
shipping_address_id:
description: The shipping address's ID
nullable: true
type: string
example: addr_01G8ZH853YPY9B94857DY91YGW
shipping_address:
description: The details of the shipping address associated with the cart.
x-expandable: shipping_address
nullable: true
$ref: '#/components/schemas/Address'
items:
description: The line items added to the cart.
type: array
x-expandable: items
items:
$ref: '#/components/schemas/LineItem'
region_id:
description: The region's ID
type: string
example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
region:
description: The details of the region associated with the cart.
x-expandable: region
nullable: true
$ref: '#/components/schemas/Region'
discounts:
description: An array of details of all discounts applied to the cart.
type: array
x-expandable: discounts
items:
$ref: '#/components/schemas/Discount'
gift_cards:
description: An array of details of all gift cards applied to the cart.
type: array
x-expandable: gift_cards
items:
$ref: '#/components/schemas/GiftCard'
customer_id:
description: The customer's ID
nullable: true
type: string
example: cus_01G2SG30J8C85S4A5CHM2S1NS2
customer:
description: The details of the customer the cart belongs to.
x-expandable: customer
nullable: true
type: object
payment_session:
description: The details of the selected payment session in the cart.
x-expandable: payment_session
nullable: true
type: object
payment_sessions:
description: The details of all payment sessions created on the cart.
type: array
x-expandable: payment_sessions
items:
type: object
payment_id:
description: The payment's ID if available
nullable: true
type: string
example: pay_01G8ZCC5W42ZNY842124G7P5R9
payment:
description: The details of the payment associated with the cart.
nullable: true
x-expandable: payment
type: object
shipping_methods:
description: The details of the shipping methods added to the cart.
type: array
x-expandable: shipping_methods
items:
$ref: '#/components/schemas/ShippingMethod'
type:
description: The cart's type.
type: string
enum:
- default
- swap
- draft_order
- payment_link
- claim
default: default
completed_at:
description: The date with timezone at which the cart was completed.
nullable: true
type: string
format: date-time
payment_authorized_at:
description: The date with timezone at which the payment was authorized.
nullable: true
type: string
format: date-time
idempotency_key:
description: Randomly generated key used to continue the completion of a cart in case of failure.
nullable: true
type: string
externalDocs:
url: https://docs.medusajs.com/development/idempotency-key/overview.md
description: Learn more how to use the idempotency key.
context:
description: The context of the cart which can include info like IP or user agent.
nullable: true
type: object
example:
ip: '::1'
user_agent: PostmanRuntime/7.29.2
sales_channel_id:
description: The sales channel ID the cart is associated with.
nullable: true
type: string
example: null
sales_channel:
description: The details of the sales channel associated with the cart.
nullable: true
x-expandable: sales_channel
$ref: '#/components/schemas/SalesChannel'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
shipping_total:
description: The total of shipping
type: integer
example: 1000
discount_total:
description: The total of discount rounded
type: integer
example: 800
raw_discount_total:
description: The total of discount
type: integer
example: 800
item_tax_total:
description: The total of items with taxes
type: integer
example: 8000
shipping_tax_total:
description: The total of shipping with taxes
type: integer
example: 1000
tax_total:
description: The total of tax
type: integer
example: 0
refunded_total:
description: The total amount refunded if the order associated with this cart is returned.
type: integer
example: 0
total:
description: The total amount of the cart
type: integer
example: 8200
subtotal:
description: The subtotal of the cart
type: integer
example: 8000
refundable_amount:
description: The amount that can be refunded
type: integer
example: 8200
gift_card_total:
description: The total of gift cards
type: integer
example: 0
gift_card_tax_total:
description: The total of gift cards with taxes
type: integer
example: 0
sales_channels:
description: The associated sales channels.
type: array
nullable: true
x-expandable: sales_channels
items:
$ref: '#/components/schemas/SalesChannel'
ClaimImage:
title: Claim Image
description: The details of an image attached to a claim.
type: object
required:
- claim_item_id
- created_at
- deleted_at
- id
- metadata
- updated_at
- url
properties:
id:
description: The claim image's ID
type: string
example: cimg_01G8ZH853Y6TFXWPG5EYE81X63
claim_item_id:
description: The ID of the claim item associated with the image
type: string
claim_item:
description: The details of the claim item this image is associated with.
nullable: true
x-expandable: claim_item
type: object
url:
description: The URL of the image
type: string
format: uri
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
ClaimItem:
title: Claim Item
description: A claim item is an item created as part of a claim. It references an item in the order that should be exchanged or refunded.
type: object
required:
- claim_order_id
- created_at
- deleted_at
- id
- item_id
- metadata
- note
- quantity
- reason
- updated_at
- variant_id
properties:
id:
description: The claim item's ID
type: string
example: citm_01G8ZH853Y6TFXWPG5EYE81X63
images:
description: The claim images that are attached to the claim item.
type: array
x-expandable: images
items:
$ref: '#/components/schemas/ClaimImage'
claim_order_id:
description: The ID of the claim this item is associated with.
type: string
claim_order:
description: The details of the claim this item belongs to.
x-expandable: claim_order
nullable: true
type: object
item_id:
description: The ID of the line item that the claim item refers to.
type: string
example: item_01G8ZM25TN49YV9EQBE2NC27KC
item:
description: The details of the line item in the original order that this claim item refers to.
x-expandable: item
nullable: true
$ref: '#/components/schemas/LineItem'
variant_id:
description: The ID of the product variant that is claimed.
type: string
example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6
variant:
description: The details of the product variant to potentially replace the item in the original order.
x-expandable: variant
nullable: true
$ref: '#/components/schemas/ProductVariant'
reason:
description: The reason for the claim
type: string
enum:
- missing_item
- wrong_item
- production_failure
- other
note:
description: An optional note about the claim, for additional information
nullable: true
type: string
example: I don't like it.
quantity:
description: The quantity of the item that is being claimed; must be less than or equal to the amount purchased in the original order.
type: integer
example: 1
tags:
description: User defined tags for easy filtering and grouping.
type: array
x-expandable: tags
items:
$ref: '#/components/schemas/ClaimTag'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
ClaimOrder:
title: Claim
description: A Claim represents a group of faulty or missing items. It consists of claim items that refer to items in the original order that should be replaced or refunded. It also includes details related to shipping and fulfillment.
type: object
required:
- canceled_at
- created_at
- deleted_at
- fulfillment_status
- id
- idempotency_key
- metadata
- no_notification
- order_id
- payment_status
- refund_amount
- shipping_address_id
- type
- updated_at
properties:
id:
description: The claim's ID
type: string
example: claim_01G8ZH853Y6TFXWPG5EYE81X63
type:
description: The claim's type
type: string
enum:
- refund
- replace
payment_status:
description: The status of the claim's payment
type: string
enum:
- na
- not_refunded
- refunded
default: na
fulfillment_status:
description: The claim's fulfillment status
type: string
enum:
- not_fulfilled
- partially_fulfilled
- fulfilled
- partially_shipped
- shipped
- partially_returned
- returned
- canceled
- requires_action
default: not_fulfilled
claim_items:
description: The details of the items that should be replaced or refunded.
type: array
x-expandable: claim_items
items:
$ref: '#/components/schemas/ClaimItem'
additional_items:
description: The details of the new items to be shipped when the claim's type is `replace`
type: array
x-expandable: additional_items
items:
$ref: '#/components/schemas/LineItem'
order_id:
description: The ID of the order that the claim comes from.
type: string
example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
order:
description: The details of the order that this claim was created for.
x-expandable: order
nullable: true
type: object
return_order:
description: The details of the return associated with the claim if the claim's type is `replace`.
x-expandable: return_order
nullable: true
type: object
shipping_address_id:
description: The ID of the address that the new items should be shipped to
nullable: true
type: string
example: addr_01G8ZH853YPY9B94857DY91YGW
shipping_address:
description: The details of the address that new items should be shipped to.
x-expandable: shipping_address
nullable: true
$ref: '#/components/schemas/Address'
shipping_methods:
description: The details of the shipping methods that the claim order will be shipped with.
type: array
x-expandable: shipping_methods
items:
$ref: '#/components/schemas/ShippingMethod'
fulfillments:
description: The fulfillments of the new items to be shipped
type: array
x-expandable: fulfillments
items:
type: object
refund_amount:
description: The amount that will be refunded in conjunction with the claim
nullable: true
type: integer
example: 1000
canceled_at:
description: The date with timezone at which the claim was canceled.
nullable: true
type: string
format: date-time
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
no_notification:
description: Flag for describing whether or not notifications related to this should be send.
nullable: true
type: boolean
example: false
idempotency_key:
description: Randomly generated key used to continue the completion of the cart associated with the claim in case of failure.
nullable: true
type: string
externalDocs:
url: https://docs.medusajs.com/development/idempotency-key/overview.md
description: Learn more how to use the idempotency key.
ClaimTag:
title: Claim Tag
description: Claim Tags are user defined tags that can be assigned to claim items for easy filtering and grouping.
type: object
required:
- created_at
- deleted_at
- id
- metadata
- updated_at
- value
properties:
id:
description: The claim tag's ID
type: string
example: ctag_01G8ZCC5Y63B95V6B5SHBZ91S4
value:
description: The value that the claim tag holds
type: string
example: Damaged
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
Country:
title: Country
description: Country details
type: object
required:
- display_name
- id
- iso_2
- iso_3
- name
- num_code
- region_id
properties:
id:
description: The country's ID
type: string
example: 109
iso_2:
description: The 2 character ISO code of the country in lower case
type: string
example: it
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
description: See a list of codes.
iso_3:
description: The 2 character ISO code of the country in lower case
type: string
example: ita
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements
description: See a list of codes.
num_code:
description: The numerical ISO code for the country.
type: string
example: 380
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_3166-1_numeric#Officially_assigned_code_elements
description: See a list of codes.
name:
description: The normalized country name in upper case.
type: string
example: ITALY
display_name:
description: The country name appropriate for display.
type: string
example: Italy
region_id:
description: The region ID this country is associated with.
nullable: true
type: string
example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
region:
description: The details of the region the country is associated with.
x-expandable: region
nullable: true
type: object
CreateStockLocationInput:
title: Create Stock Location Input
description: Represents the Input to create a Stock Location
type: object
required:
- name
properties:
name:
type: string
description: The stock location name
address_id:
type: string
description: The Stock location address ID
address:
description: Stock location address object
allOf:
- $ref: '#/components/schemas/StockLocationAddressInput'
- type: object
metadata:
type: object
description: An optional key-value map with additional details
example:
car: white
Currency:
title: Currency
description: Currency
type: object
required:
- code
- name
- symbol
- symbol_native
properties:
code:
description: The 3 character ISO code for the currency.
type: string
example: usd
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
description: See a list of codes.
symbol:
description: The symbol used to indicate the currency.
type: string
example: $
symbol_native:
description: The native symbol used to indicate the currency.
type: string
example: $
name:
description: The written name of the currency
type: string
example: US Dollar
includes_tax:
description: Whether the currency prices include tax
type: boolean
x-featureFlag: tax_inclusive_pricing
default: false
CustomShippingOption:
title: Custom Shipping Option
description: Custom Shipping Options are overridden Shipping Options. Admins can attach a Custom Shipping Option to a cart in order to set a custom price for a particular Shipping Option.
type: object
required:
- cart_id
- created_at
- deleted_at
- id
- metadata
- price
- shipping_option_id
- updated_at
properties:
id:
description: The custom shipping option's ID
type: string
example: cso_01G8X99XNB77DMFBJFWX6DN9V9
price:
description: The custom price set that will override the shipping option's original price
type: integer
example: 1000
shipping_option_id:
description: The ID of the Shipping Option that the custom shipping option overrides
type: string
example: so_01G1G5V27GYX4QXNARRQCW1N8T
shipping_option:
description: The details of the overridden shipping options.
x-expandable: shipping_option
nullable: true
$ref: '#/components/schemas/ShippingOption'
cart_id:
description: The ID of the Cart that the custom shipping option is attached to
nullable: true
type: string
example: cart_01G8ZH853Y6TFXWPG5EYE81X63
cart:
description: The details of the cart this shipping option belongs to.
x-expandable: cart
nullable: true
$ref: '#/components/schemas/Cart'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
Customer:
title: Customer
description: A customer can make purchases in your store and manage their profile.
type: object
required:
- billing_address_id
- created_at
- deleted_at
- email
- first_name
- has_account
- id
- last_name
- metadata
- phone
- updated_at
properties:
id:
description: The customer's ID
type: string
example: cus_01G2SG30J8C85S4A5CHM2S1NS2
email:
description: The customer's email
type: string
format: email
first_name:
description: The customer's first name
nullable: true
type: string
example: Arno
last_name:
description: The customer's last name
nullable: true
type: string
example: Willms
billing_address_id:
description: The customer's billing address ID
nullable: true
type: string
example: addr_01G8ZH853YPY9B94857DY91YGW
billing_address:
description: The details of the billing address associated with the customer.
x-expandable: billing_address
nullable: true
$ref: '#/components/schemas/Address'
shipping_addresses:
description: The details of the shipping addresses associated with the customer.
type: array
x-expandable: shipping_addresses
items:
$ref: '#/components/schemas/Address'
phone:
description: The customer's phone number
nullable: true
type: string
example: 16128234334802
has_account:
description: Whether the customer has an account or not
type: boolean
default: false
orders:
description: The details of the orders this customer placed.
type: array
x-expandable: orders
items:
type: object
groups:
description: The customer groups the customer belongs to.
type: array
x-expandable: groups
items:
$ref: '#/components/schemas/CustomerGroup'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
CustomerGroup:
title: Customer Group
description: A customer group that can be used to organize customers into groups of similar traits.
type: object
required:
- created_at
- deleted_at
- id
- metadata
- name
- updated_at
properties:
id:
description: The customer group's ID
type: string
example: cgrp_01G8ZH853Y6TFXWPG5EYE81X63
name:
description: The name of the customer group
type: string
example: VIP
customers:
description: The details of the customers that belong to the customer group.
type: array
x-expandable: customers
items:
type: object
price_lists:
description: The price lists that are associated with the customer group.
type: array
x-expandable: price_lists
items:
type: object
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
Discount:
title: Discount
description: A discount can be applied to a cart for promotional purposes.
type: object
required:
- code
- created_at
- deleted_at
- ends_at
- id
- is_disabled
- is_dynamic
- metadata
- parent_discount_id
- rule_id
- starts_at
- updated_at
- usage_count
- usage_limit
- valid_duration
properties:
id:
description: The discount's ID
type: string
example: disc_01F0YESMW10MGHWJKZSDDMN0VN
code:
description: A unique code for the discount - this will be used by the customer to apply the discount
type: string
example: 10DISC
is_dynamic:
description: A flag to indicate if multiple instances of the discount can be generated. I.e. for newsletter discounts
type: boolean
example: false
rule_id:
description: The ID of the discount rule that defines how the discount will be applied to a cart.
nullable: true
type: string
example: dru_01F0YESMVK96HVX7N419E3CJ7C
rule:
description: The details of the discount rule that defines how the discount will be applied to a cart..
x-expandable: rule
nullable: true
$ref: '#/components/schemas/DiscountRule'
is_disabled:
description: Whether the Discount has been disabled. Disabled discounts cannot be applied to carts
type: boolean
example: false
parent_discount_id:
description: The Discount that the discount was created from. This will always be a dynamic discount
nullable: true
type: string
example: disc_01G8ZH853YPY9B94857DY91YGW
parent_discount:
description: The details of the parent discount that this discount was created from.
x-expandable: parent_discount
nullable: true
type: object
starts_at:
description: The time at which the discount can be used.
type: string
format: date-time
ends_at:
description: The time at which the discount can no longer be used.
nullable: true
type: string
format: date-time
valid_duration:
description: Duration the discount runs between
nullable: true
type: string
example: P3Y6M4DT12H30M5S
regions:
description: The details of the regions in which the Discount can be used.
type: array
x-expandable: regions
items:
$ref: '#/components/schemas/Region'
usage_limit:
description: The maximum number of times that a discount can be used.
nullable: true
type: integer
example: 100
usage_count:
description: The number of times a discount has been used.
type: integer
example: 50
default: 0
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
DiscountCondition:
title: Discount Condition
description: Holds rule conditions for when a discount is applicable
type: object
required:
- created_at
- deleted_at
- discount_rule_id
- id
- metadata
- operator
- type
- updated_at
properties:
id:
description: The discount condition's ID
type: string
example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
type:
description: The type of the condition. The type affects the available resources associated with the condition. For example, if the type is `products`, that means the `products` relation will hold the products associated with this condition and other relations will be empty.
type: string
enum:
- products
- product_types
- product_collections
- product_tags
- customer_groups
operator:
description: The operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that discountable resources are everything but the specified resources.
type: string
enum:
- in
- not_in
discount_rule_id:
description: The ID of the discount rule associated with the condition
type: string
example: dru_01F0YESMVK96HVX7N419E3CJ7C
discount_rule:
description: The details of the discount rule associated with the condition.
x-expandable: discount_rule
nullable: true
$ref: '#/components/schemas/DiscountRule'
products:
description: products associated with this condition if `type` is `products`.
type: array
x-expandable: products
items:
$ref: '#/components/schemas/Product'
product_types:
description: Product types associated with this condition if `type` is `product_types`.
type: array
x-expandable: product_types
items:
$ref: '#/components/schemas/ProductType'
product_tags:
description: Product tags associated with this condition if `type` is `product_tags`.
type: array
x-expandable: product_tags
items:
$ref: '#/components/schemas/ProductTag'
product_collections:
description: Product collections associated with this condition if `type` is `product_collections`.
type: array
x-expandable: product_collections
items:
$ref: '#/components/schemas/ProductCollection'
customer_groups:
description: Customer groups associated with this condition if `type` is `customer_groups`.
type: array
x-expandable: customer_groups
items:
$ref: '#/components/schemas/CustomerGroup'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
DiscountConditionCustomerGroup:
title: Product Tag Discount Condition
description: Associates a discount condition with a customer group
type: object
required:
- condition_id
- created_at
- customer_group_id
- metadata
- updated_at
properties:
customer_group_id:
description: The ID of the Product Tag
type: string
example: cgrp_01G8ZH853Y6TFXWPG5EYE81X63
condition_id:
description: The ID of the Discount Condition
type: string
example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
customer_group:
description: Available if the relation `customer_group` is expanded.
nullable: true
$ref: '#/components/schemas/CustomerGroup'
discount_condition:
description: Available if the relation `discount_condition` is expanded.
nullable: true
$ref: '#/components/schemas/DiscountCondition'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
DiscountConditionProduct:
title: Product Discount Condition
description: This represents the association between a discount condition and a product
type: object
required:
- condition_id
- created_at
- metadata
- product_id
- updated_at
properties:
product_id:
description: The ID of the Product Tag
type: string
example: prod_01G1G5V2MBA328390B5AXJ610F
condition_id:
description: The ID of the Discount Condition
type: string
example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
product:
description: The details of the product.
x-expandable: product
nullable: true
$ref: '#/components/schemas/Product'
discount_condition:
description: The details of the discount condition.
x-expandable: discount_condition
nullable: true
$ref: '#/components/schemas/DiscountCondition'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
DiscountConditionProductCollection:
title: Product Collection Discount Condition
description: This represents the association between a discount condition and a product collection
type: object
required:
- condition_id
- created_at
- metadata
- product_collection_id
- updated_at
properties:
product_collection_id:
description: The ID of the Product Collection
type: string
example: pcol_01F0YESBFAZ0DV6V831JXWH0BG
condition_id:
description: The ID of the Discount Condition
type: string
example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
product_collection:
description: The details of the product collection.
x-expandable: product_collection
nullable: true
$ref: '#/components/schemas/ProductCollection'
discount_condition:
description: The details of the discount condition.
x-expandable: discount_condition
nullable: true
$ref: '#/components/schemas/DiscountCondition'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
DiscountConditionProductTag:
title: Product Tag Discount Condition
description: This represents the association between a discount condition and a product tag
type: object
required:
- condition_id
- created_at
- metadata
- product_tag_id
- updated_at
properties:
product_tag_id:
description: The ID of the Product Tag
type: string
example: ptag_01F0YESHPZYY3H4SJ3A5918SBN
condition_id:
description: The ID of the Discount Condition
type: string
example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
product_tag:
description: The details of the product tag.
x-expandable: product_tag
nullable: true
$ref: '#/components/schemas/ProductTag'
discount_condition:
description: The details of the discount condition.
x-expandable: discount_condition
nullable: true
$ref: '#/components/schemas/DiscountCondition'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
DiscountConditionProductType:
title: Product Type Discount Condition
description: This represents the association between a discount condition and a product type
type: object
required:
- condition_id
- created_at
- metadata
- product_type_id
- updated_at
properties:
product_type_id:
description: The ID of the Product Tag
type: string
example: ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A
condition_id:
description: The ID of the Discount Condition
type: string
example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
product_type:
description: The details of the product type.
x-expandable: product_type
nullable: true
$ref: '#/components/schemas/ProductType'
discount_condition:
description: The details of the discount condition.
x-expandable: discount_condition
nullable: true
$ref: '#/components/schemas/DiscountCondition'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
DiscountRule:
title: Discount Rule
description: A discount rule defines how a Discount is calculated when applied to a Cart.
type: object
required:
- allocation
- created_at
- deleted_at
- description
- id
- metadata
- type
- updated_at
- value
properties:
id:
description: The discount rule's ID
type: string
example: dru_01F0YESMVK96HVX7N419E3CJ7C
type:
description: The type of the Discount, can be `fixed` for discounts that reduce the price by a fixed amount, `percentage` for percentage reductions or `free_shipping` for shipping vouchers.
type: string
enum:
- fixed
- percentage
- free_shipping
example: percentage
description:
description: A short description of the discount
nullable: true
type: string
example: 10 Percent
value:
description: The value that the discount represents; this will depend on the type of the discount
type: integer
example: 10
allocation:
description: The scope that the discount should apply to.
nullable: true
type: string
enum:
- total
- item
example: total
conditions:
description: The details of the discount conditions associated with the rule. They can be used to limit when the discount can be used.
type: array
x-expandable: conditions
items:
type: object
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
DraftOrder:
title: DraftOrder
description: A draft order is created by an admin without direct involvement of the customer. Once its payment is marked as captured, it is transformed into an order.
type: object
required:
- canceled_at
- cart_id
- completed_at
- created_at
- display_id
- id
- idempotency_key
- metadata
- no_notification_order
- order_id
- status
- updated_at
properties:
id:
description: The draft order's ID
type: string
example: dorder_01G8TJFKBG38YYFQ035MSVG03C
status:
description: The status of the draft order. It's changed to `completed` when it's transformed to an order.
type: string
enum:
- open
- completed
default: open
display_id:
description: The draft order's display ID
type: string
example: 2
cart_id:
description: The ID of the cart associated with the draft order.
nullable: true
type: string
example: cart_01G8ZH853Y6TFXWPG5EYE81X63
cart:
description: The details of the cart associated with the draft order.
x-expandable: cart
nullable: true
type: object
order_id:
description: The ID of the order created from the draft order when its payment is captured.
nullable: true
type: string
example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
order:
description: The details of the order created from the draft order when its payment is captured.
x-expandable: order
nullable: true
type: object
canceled_at:
description: The date the draft order was canceled at.
nullable: true
type: string
format: date-time
completed_at:
description: The date the draft order was completed at.
nullable: true
type: string
format: date-time
no_notification_order:
description: Whether to send the customer notifications regarding order updates.
nullable: true
type: boolean
example: false
idempotency_key:
description: Randomly generated key used to continue the completion of the cart associated with the draft order in case of failure.
nullable: true
type: string
externalDocs:
url: https://docs.medusajs.com/development/idempotency-key/overview.md
description: Learn more how to use the idempotency key.
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
Error:
title: Response Error
type: object
properties:
code:
type: string
description: A slug code to indicate the type of the error.
enum:
- invalid_state_error
- invalid_request_error
- api_error
- unknown_error
message:
type: string
description: Description of the error that occurred.
example: first_name must be a string
type:
type: string
description: A slug indicating the type of the error.
enum:
- QueryRunnerAlreadyReleasedError
- TransactionAlreadyStartedError
- TransactionNotStartedError
- conflict
- unauthorized
- payment_authorization_error
- duplicate_error
- not_allowed
- invalid_data
- not_found
- database_error
- unexpected_state
- invalid_argument
- unknown_error
ExtendedStoreDTO:
allOf:
- $ref: '#/components/schemas/Store'
- type: object
required:
- payment_providers
- fulfillment_providers
- feature_flags
- modules
properties:
payment_providers:
description: The store's payment providers.
$ref: '#/components/schemas/PaymentProvider'
fulfillment_providers:
description: The store's fulfillment providers.
$ref: '#/components/schemas/FulfillmentProvider'
feature_flags:
description: The feature flags enabled in the store's backend.
$ref: '#/components/schemas/FeatureFlagsResponse'
modules:
description: The modules installed in the store's backend.
$ref: '#/components/schemas/ModulesResponse'
FeatureFlagsResponse:
type: array
items:
type: object
required:
- key
- value
properties:
key:
description: The key of the feature flag.
type: string
value:
description: The value of the feature flag.
type: boolean
Fulfillment:
title: Fulfillment
description: A Fulfillment is created once an admin can prepare the purchased goods. Fulfillments will eventually be shipped and hold information about how to track shipments. Fulfillments are created through a fulfillment provider, which typically integrates a third-party shipping service. Fulfillments can be associated with orders, claims, swaps, and returns.
type: object
required:
- canceled_at
- claim_order_id
- created_at
- data
- id
- idempotency_key
- location_id
- metadata
- no_notification
- order_id
- provider_id
- shipped_at
- swap_id
- tracking_numbers
- updated_at
properties:
id:
description: The fulfillment's ID
type: string
example: ful_01G8ZRTMQCA76TXNAT81KPJZRF
claim_order_id:
description: The ID of the Claim that the Fulfillment belongs to.
nullable: true
type: string
example: null
claim_order:
description: The details of the claim that the fulfillment may belong to.
x-expandable: claim_order
nullable: true
type: object
swap_id:
description: The ID of the Swap that the Fulfillment belongs to.
nullable: true
type: string
example: null
swap:
description: The details of the swap that the fulfillment may belong to.
x-expandable: swap
nullable: true
type: object
order_id:
description: The ID of the Order that the Fulfillment belongs to.
nullable: true
type: string
example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
order:
description: The details of the order that the fulfillment may belong to.
x-expandable: order
nullable: true
type: object
provider_id:
description: The ID of the Fulfillment Provider responsible for handling the fulfillment.
type: string
example: manual
provider:
description: The details of the fulfillment provider responsible for handling the fulfillment.
x-expandable: provider
nullable: true
$ref: '#/components/schemas/FulfillmentProvider'
location_id:
description: The ID of the stock location the fulfillment will be shipped from
nullable: true
type: string
example: sloc_01G8TJSYT9M6AVS5N4EMNFS1EK
items:
description: The Fulfillment Items in the Fulfillment. These hold information about how many of each Line Item has been fulfilled.
type: array
x-expandable: items
items:
$ref: '#/components/schemas/FulfillmentItem'
tracking_links:
description: The Tracking Links that can be used to track the status of the Fulfillment. These will usually be provided by the Fulfillment Provider.
type: array
x-expandable: tracking_links
items:
$ref: '#/components/schemas/TrackingLink'
tracking_numbers:
description: The tracking numbers that can be used to track the status of the fulfillment.
deprecated: true
type: array
items:
type: string
data:
description: This contains all the data necessary for the Fulfillment provider to handle the fulfillment.
type: object
example: {}
shipped_at:
description: The date with timezone at which the Fulfillment was shipped.
nullable: true
type: string
format: date-time
no_notification:
description: Flag for describing whether or not notifications related to this should be sent.
nullable: true
type: boolean
example: false
canceled_at:
description: The date with timezone at which the Fulfillment was canceled.
nullable: true
type: string
format: date-time
idempotency_key:
description: Randomly generated key used to continue the completion of the fulfillment in case of failure.
nullable: true
type: string
externalDocs:
url: https://docs.medusajs.com/development/idempotency-key/overview.md
description: Learn more how to use the idempotency key.
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
FulfillmentItem:
title: Fulfillment Item
description: This represents the association between a Line Item and a Fulfillment.
type: object
required:
- fulfillment_id
- item_id
- quantity
properties:
fulfillment_id:
description: The ID of the Fulfillment that the Fulfillment Item belongs to.
type: string
example: ful_01G8ZRTMQCA76TXNAT81KPJZRF
item_id:
description: The ID of the Line Item that the Fulfillment Item references.
type: string
example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
fulfillment:
description: The details of the fulfillment.
x-expandable: fulfillment
nullable: true
type: object
item:
description: The details of the line item.
x-expandable: item
nullable: true
$ref: '#/components/schemas/LineItem'
quantity:
description: The quantity of the Line Item that is included in the Fulfillment.
type: integer
example: 1
FulfillmentProvider:
title: Fulfillment Provider
description: A fulfillment provider represents a fulfillment service installed in the Medusa backend, either through a plugin or backend customizations. It holds the fulfillment service's installation status.
type: object
required:
- id
- is_installed
properties:
id:
description: The ID of the fulfillment provider as given by the fulfillment service.
type: string
example: manual
is_installed:
description: Whether the fulfillment service is installed in the current version. If a fulfillment service is no longer installed, the `is_installed` attribute is set to `false`.
type: boolean
default: true
GiftCard:
title: Gift Card
description: Gift Cards are redeemable and represent a value that can be used towards the payment of an Order.
type: object
required:
- balance
- code
- created_at
- deleted_at
- ends_at
- id
- is_disabled
- metadata
- order_id
- region_id
- tax_rate
- updated_at
- value
properties:
id:
description: The gift card's ID
type: string
example: gift_01G8XKBPBQY2R7RBET4J7E0XQZ
code:
description: The unique code that identifies the Gift Card. This is used by the Customer to redeem the value of the Gift Card.
type: string
example: 3RFT-MH2C-Y4YZ-XMN4
value:
description: The value that the Gift Card represents.
type: integer
example: 10
balance:
description: The remaining value on the Gift Card.
type: integer
example: 10
region_id:
description: The ID of the region this gift card is available in.
type: string
example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
region:
description: The details of the region this gift card is available in.
x-expandable: region
nullable: true
$ref: '#/components/schemas/Region'
order_id:
description: The ID of the order that the gift card was purchased in.
nullable: true
type: string
example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
order:
description: The details of the order that the gift card was purchased in.
x-expandable: region
nullable: true
type: object
is_disabled:
description: Whether the Gift Card has been disabled. Disabled Gift Cards cannot be applied to carts.
type: boolean
default: false
ends_at:
description: The time at which the Gift Card can no longer be used.
nullable: true
type: string
format: date-time
tax_rate:
description: The gift card's tax rate that will be applied on calculating totals
nullable: true
type: number
example: 0
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
GiftCardTransaction:
title: Gift Card Transaction
description: Gift Card Transactions are created once a Customer uses a Gift Card to pay for their Order.
type: object
required:
- amount
- created_at
- gift_card_id
- id
- is_taxable
- order_id
- tax_rate
properties:
id:
description: The gift card transaction's ID
type: string
example: gct_01G8X9A7ESKAJXG2H0E6F1MW7A
gift_card_id:
description: The ID of the Gift Card that was used in the transaction.
type: string
example: gift_01G8XKBPBQY2R7RBET4J7E0XQZ
gift_card:
description: The details of the gift card associated used in this transaction.
x-expandable: gift_card
nullable: true
type: object
order_id:
description: The ID of the order that the gift card was used for payment.
type: string
example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
order:
description: The details of the order that the gift card was used for payment.
x-expandable: order
nullable: true
type: object
amount:
description: The amount that was used from the Gift Card.
type: integer
example: 10
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
is_taxable:
description: Whether the transaction is taxable or not.
nullable: true
type: boolean
example: false
tax_rate:
description: The tax rate of the transaction
nullable: true
type: number
example: 0
IdempotencyKey:
title: Idempotency Key
description: Idempotency Key is used to continue a process in case of any failure that might occur.
type: object
required:
- created_at
- id
- idempotency_key
- locked_at
- recovery_point
- response_code
- response_body
- request_method
- request_params
- request_path
properties:
id:
description: The idempotency key's ID
type: string
example: ikey_01G8X9A7ESKAJXG2H0E6F1MW7A
idempotency_key:
description: The unique randomly generated key used to determine the state of a process.
type: string
externalDocs:
url: https://docs.medusajs.com/development/idempotency-key/overview.md
description: Learn more how to use the idempotency key.
created_at:
description: Date which the idempotency key was locked.
type: string
format: date-time
locked_at:
description: Date which the idempotency key was locked.
nullable: true
type: string
format: date-time
request_method:
description: The method of the request
nullable: true
type: string
example: POST
request_params:
description: The parameters passed to the request
nullable: true
type: object
example:
id: cart_01G8ZH853Y6TFXWPG5EYE81X63
request_path:
description: The request's path
nullable: true
type: string
example: /store/carts/cart_01G8ZH853Y6TFXWPG5EYE81X63/complete
response_code:
description: The response's code.
nullable: true
type: string
example: 200
response_body:
description: The response's body
nullable: true
type: object
example:
id: cart_01G8ZH853Y6TFXWPG5EYE81X63
recovery_point:
description: Where to continue from.
type: string
default: started
Image:
title: Image
description: An Image is used to store details about uploaded images. Images are uploaded by the File Service, and the URL is provided by the File Service.
type: object
required:
- created_at
- deleted_at
- id
- metadata
- updated_at
- url
properties:
id:
type: string
description: The image's ID
example: img_01G749BFYR6T8JTVW6SGW3K3E6
url:
description: The URL at which the image file can be found.
type: string
format: uri
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
InventoryItemDTO:
type: object
required:
- sku
properties:
id:
description: The inventory item's ID.
type: string
example: iitem_12334
sku:
description: The Stock Keeping Unit (SKU) code of the Inventory Item.
type: string
hs_code:
description: The Harmonized System code of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.
type: string
origin_country:
description: The country in which the Inventory Item was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.
type: string
mid_code:
description: The Manufacturers Identification code that identifies the manufacturer of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.
type: string
title:
description: Title of the inventory item
type: string
description:
description: Description of the inventory item
type: string
thumbnail:
description: Thumbnail for the inventory item
type: string
material:
description: The material and composition that the Inventory Item is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.
type: string
weight:
description: The weight of the Inventory Item. May be used in shipping rate calculations.
type: number
height:
description: The height of the Inventory Item. May be used in shipping rate calculations.
type: number
width:
description: The width of the Inventory Item. May be used in shipping rate calculations.
type: number
length:
description: The length of the Inventory Item. May be used in shipping rate calculations.
type: number
requires_shipping:
description: Whether the item requires shipping.
type: boolean
metadata:
type: object
description: An optional key-value map with additional details
example:
car: white
created_at:
type: string
description: The date with timezone at which the resource was created.
format: date-time
updated_at:
type: string
description: The date with timezone at which the resource was updated.
format: date-time
deleted_at:
type: string
description: The date with timezone at which the resource was deleted.
format: date-time
InventoryLevelDTO:
type: object
required:
- inventory_item_id
- location_id
- stocked_quantity
- reserved_quantity
- incoming_quantity
properties:
location_id:
description: the item location ID
type: string
stocked_quantity:
description: the total stock quantity of an inventory item at the given location ID
type: number
reserved_quantity:
description: the reserved stock quantity of an inventory item at the given location ID
type: number
incoming_quantity:
description: the incoming stock quantity of an inventory item at the given location ID
type: number
metadata:
type: object
description: An optional key-value map with additional details
example:
car: white
created_at:
type: string
description: The date with timezone at which the resource was created.
format: date-time
updated_at:
type: string
description: The date with timezone at which the resource was updated.
format: date-time
deleted_at:
type: string
description: The date with timezone at which the resource was deleted.
format: date-time
Invite:
title: Invite
description: An invite is created when an admin user invites a new user to join the store's team. Once the invite is accepted, it's deleted.
type: object
required:
- accepted
- created_at
- deleted_at
- expires_at
- id
- metadata
- role
- token
- updated_at
- user_email
properties:
id:
type: string
description: The invite's ID
example: invite_01G8TKE4XYCTHSCK2GDEP47RE1
user_email:
description: The email of the user being invited.
type: string
format: email
role:
description: The user's role. These roles don't change the privileges of the user.
nullable: true
type: string
enum:
- admin
- member
- developer
default: member
accepted:
description: Whether the invite was accepted or not.
type: boolean
default: false
token:
description: The token used to accept the invite.
type: string
expires_at:
description: The date the invite expires at.
type: string
format: date-time
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
LineItem:
title: Line Item
description: Line Items are created when a product is added to a Cart. When Line Items are purchased they will get copied to the resulting order, swap, or claim, and can eventually be referenced in Fulfillments and Returns. Line items may also be used for order edits.
type: object
required:
- allow_discounts
- cart_id
- claim_order_id
- created_at
- description
- fulfilled_quantity
- has_shipping
- id
- is_giftcard
- is_return
- metadata
- order_edit_id
- order_id
- original_item_id
- quantity
- returned_quantity
- shipped_quantity
- should_merge
- swap_id
- thumbnail
- title
- unit_price
- updated_at
- variant_id
properties:
id:
description: The line item's ID
type: string
example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
cart_id:
description: The ID of the cart that the line item may belongs to.
nullable: true
type: string
example: cart_01G8ZH853Y6TFXWPG5EYE81X63
cart:
description: The details of the cart that the line item may belongs to.
x-expandable: cart
nullable: true
type: object
order_id:
description: The ID of the order that the line item may belongs to.
nullable: true
type: string
example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
order:
description: The details of the order that the line item may belongs to.
x-expandable: order
nullable: true
type: object
swap_id:
description: The ID of the swap that the line item may belong to.
nullable: true
type: string
example: null
swap:
description: The details of the swap that the line item may belong to.
x-expandable: swap
nullable: true
type: object
claim_order_id:
description: The ID of the claim that the line item may belong to.
nullable: true
type: string
example: null
claim_order:
description: The details of the claim that the line item may belong to.
x-expandable: claim_order
nullable: true
type: object
tax_lines:
description: The details of the item's tax lines.
x-expandable: tax_lines
type: array
items:
$ref: '#/components/schemas/LineItemTaxLine'
adjustments:
description: The details of the item's adjustments, which are available when a discount is applied on the item.
x-expandable: adjustments
type: array
items:
$ref: '#/components/schemas/LineItemAdjustment'
original_item_id:
description: The ID of the original line item. This is useful if the line item belongs to a resource that references an order, such as a return or an order edit.
nullable: true
type: string
order_edit_id:
description: The ID of the order edit that the item may belong to.
nullable: true
type: string
order_edit:
description: The details of the order edit.
x-expandable: order_edit
nullable: true
type: object
title:
description: The title of the Line Item.
type: string
example: Medusa Coffee Mug
description:
description: A more detailed description of the contents of the Line Item.
nullable: true
type: string
example: One Size
thumbnail:
description: A URL string to a small image of the contents of the Line Item.
nullable: true
type: string
format: uri
example: https://medusa-public-images.s3.eu-west-1.amazonaws.com/coffee-mug.png
is_return:
description: Is the item being returned
type: boolean
default: false
is_giftcard:
description: Flag to indicate if the Line Item is a Gift Card.
type: boolean
default: false
should_merge:
description: Flag to indicate if new Line Items with the same variant should be merged or added as an additional Line Item.
type: boolean
default: true
allow_discounts:
description: Flag to indicate if the Line Item should be included when doing discount calculations.
type: boolean
default: true
has_shipping:
description: Flag to indicate if the Line Item has fulfillment associated with it.
nullable: true
type: boolean
example: false
unit_price:
description: The price of one unit of the content in the Line Item. This should be in the currency defined by the Cart/Order/Swap/Claim that the Line Item belongs to.
type: integer
example: 8000
variant_id:
description: The id of the Product Variant contained in the Line Item.
nullable: true
type: string
example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6
variant:
description: The details of the product variant that this item was created from.
x-expandable: variant
nullable: true
$ref: '#/components/schemas/ProductVariant'
quantity:
description: The quantity of the content in the Line Item.
type: integer
example: 1
fulfilled_quantity:
description: The quantity of the Line Item that has been fulfilled.
nullable: true
type: integer
example: 0
returned_quantity:
description: The quantity of the Line Item that has been returned.
nullable: true
type: integer
example: 0
shipped_quantity:
description: The quantity of the Line Item that has been shipped.
nullable: true
type: integer
example: 0
refundable:
description: The amount that can be refunded from the given Line Item. Takes taxes and discounts into consideration.
type: integer
example: 0
subtotal:
description: The subtotal of the line item
type: integer
example: 8000
tax_total:
description: The total of tax of the line item
type: integer
example: 0
total:
description: The total amount of the line item
type: integer
example: 8000
original_total:
description: The original total amount of the line item
type: integer
example: 8000
original_tax_total:
description: The original tax total amount of the line item
type: integer
example: 0
discount_total:
description: The total of discount of the line item rounded
type: integer
example: 0
raw_discount_total:
description: The total of discount of the line item
type: integer
example: 0
gift_card_total:
description: The total of the gift card of the line item
type: integer
example: 0
includes_tax:
description: Indicates if the line item unit_price include tax
x-featureFlag: tax_inclusive_pricing
type: boolean
default: false
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
LineItemAdjustment:
title: Line Item Adjustment
description: A Line Item Adjustment includes details on discounts applied on a line item.
type: object
required:
- amount
- description
- discount_id
- id
- item_id
- metadata
properties:
id:
description: The Line Item Adjustment's ID
type: string
example: lia_01G8TKE4XYCTHSCK2GDEP47RE1
item_id:
description: The ID of the line item
type: string
example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
item:
description: The details of the line item.
x-expandable: item
nullable: true
type: object
description:
description: The line item's adjustment description
type: string
example: Adjusted item's price.
discount_id:
description: The ID of the discount associated with the adjustment
nullable: true
type: string
example: disc_01F0YESMW10MGHWJKZSDDMN0VN
discount:
description: The details of the discount associated with the adjustment.
x-expandable: discount
nullable: true
$ref: '#/components/schemas/Discount'
amount:
description: The adjustment amount
type: number
example: 1000
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
LineItemTaxLine:
title: Line Item Tax Line
description: A Line Item Tax Line represents the taxes applied on a line item.
type: object
required:
- code
- created_at
- id
- item_id
- metadata
- name
- rate
- updated_at
properties:
id:
description: The line item tax line's ID
type: string
example: litl_01G1G5V2DRX1SK6NQQ8VVX4HQ8
code:
description: A code to identify the tax type by
nullable: true
type: string
example: tax01
name:
description: A human friendly name for the tax
type: string
example: Tax Example
rate:
description: The numeric rate to charge tax by
type: number
example: 10
item_id:
description: The ID of the line item
type: string
example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
item:
description: The details of the line item.
x-expandable: item
nullable: true
type: object
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
ModulesResponse:
type: array
items:
type: object
required:
- module
- resolution
properties:
module:
description: The key of the module.
type: string
resolution:
description: The resolution path of the module or false if module is not installed.
type: string
MoneyAmount:
title: Money Amount
description: A Money Amount represent a price amount, for example, a product variant's price or a price in a price list. Each Money Amount either has a Currency or Region associated with it to indicate the pricing in a given Currency or, for fully region-based pricing, the given price in a specific Region. If region-based pricing is used, the amount will be in the currency defined for the Region.
type: object
required:
- amount
- created_at
- currency_code
- deleted_at
- id
- max_quantity
- min_quantity
- price_list_id
- region_id
- updated_at
- variant_id
properties:
id:
description: The money amount's ID
type: string
example: ma_01F0YESHRFQNH5S8Q0PK84YYZN
currency_code:
description: The 3 character currency code that the money amount may belong to.
type: string
example: usd
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
description: See a list of codes.
currency:
description: The details of the currency that the money amount may belong to.
x-expandable: currency
nullable: true
$ref: '#/components/schemas/Currency'
amount:
description: The amount in the smallest currecny unit (e.g. cents 100 cents to charge $1) that the Product Variant will cost.
type: integer
example: 100
min_quantity:
description: The minimum quantity that the Money Amount applies to. If this value is not set, the Money Amount applies to all quantities.
nullable: true
type: integer
example: 1
max_quantity:
description: The maximum quantity that the Money Amount applies to. If this value is not set, the Money Amount applies to all quantities.
nullable: true
type: integer
example: 1
price_list_id:
description: The ID of the price list that the money amount may belong to.
nullable: true
type: string
example: pl_01G8X3CKJXCG5VXVZ87H9KC09W
price_list:
description: The details of the price list that the money amount may belong to.
x-expandable: price_list
nullable: true
type: object
variant_id:
description: The ID of the Product Variant contained in the Line Item.
nullable: true
type: string
example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6
variant:
description: The details of the product variant that the money amount may belong to.
x-expandable: variant
nullable: true
type: object
region_id:
description: The region's ID
nullable: true
type: string
example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
region:
description: The details of the region that the money amount may belong to.
x-expandable: region
nullable: true
type: object
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
MultipleErrors:
title: Multiple Errors
type: object
properties:
errors:
type: array
description: Array of errors
items:
$ref: '#/components/schemas/Error'
message:
type: string
default: Provided request body contains errors. Please check the data and retry the request
Note:
title: Note
description: A Note is an element that can be used in association with different resources to allow admin users to describe additional information. For example, they can be used to add additional information about orders.
type: object
required:
- author_id
- created_at
- deleted_at
- id
- metadata
- resource_id
- resource_type
- updated_at
- value
properties:
id:
description: The note's ID
type: string
example: note_01G8TM8ENBMC7R90XRR1G6H26Q
resource_type:
description: The type of resource that the Note refers to.
type: string
example: order
resource_id:
description: The ID of the resource that the Note refers to.
type: string
example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
value:
description: The contents of the note.
type: string
example: This order must be fulfilled on Monday
author_id:
description: The ID of the user that created the note.
nullable: true
type: string
example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V
author:
description: The details of the user that created the note.
x-expandable: author
nullable: true
$ref: '#/components/schemas/User'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
Notification:
title: Notification
description: A notification is an alert sent, typically to customers, using the installed Notification Provider as a reaction to internal events such as `order.placed`. Notifications can be resent.
type: object
required:
- created_at
- customer_id
- data
- event_name
- id
- parent_id
- provider_id
- resource_type
- resource_id
- to
- updated_at
properties:
id:
description: The notification's ID
type: string
example: noti_01G53V9Y6CKMCGBM1P0X7C28RX
event_name:
description: The name of the event that the notification was sent for.
nullable: true
type: string
example: order.placed
resource_type:
description: The type of resource that the Notification refers to.
type: string
example: order
resource_id:
description: The ID of the resource that the Notification refers to.
type: string
example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
customer_id:
description: The ID of the customer that this notification was sent to.
nullable: true
type: string
example: cus_01G2SG30J8C85S4A5CHM2S1NS2
customer:
description: The details of the customer that this notification was sent to.
x-expandable: customer
nullable: true
$ref: '#/components/schemas/Customer'
to:
description: The address that the Notification was sent to. This will usually be an email address, but can represent other addresses such as a chat bot user ID.
type: string
example: user@example.com
data:
description: The data that the Notification was sent with. This contains all the data necessary for the Notification Provider to initiate a resend.
type: object
example: {}
parent_id:
description: The notification's parent ID
nullable: true
type: string
example: noti_01G53V9Y6CKMCGBM1P0X7C28RX
parent_notification:
description: The details of the parent notification.
x-expandable: parent_notification
nullable: true
type: object
resends:
description: The details of all resends of the notification.
type: array
x-expandable: resends
items:
type: object
provider_id:
description: The ID of the notification provider used to send the notification.
nullable: true
type: string
example: sengrid
provider:
description: The notification provider used to send the notification.
x-expandable: provider
nullable: true
$ref: '#/components/schemas/NotificationProvider'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
NotificationProvider:
title: Notification Provider
description: A notification provider represents a notification service installed in the Medusa backend, either through a plugin or backend customizations. It holds the notification service's installation status.
type: object
required:
- id
- is_installed
properties:
id:
description: The ID of the notification provider as given by the notification service.
type: string
example: sendgrid
is_installed:
description: Whether the notification service is installed in the current version. If a notification service is no longer installed, the `is_installed` attribute is set to `false`.
type: boolean
default: true
OAuth:
title: OAuth
description: An Oauth app is typically created by a plugin to handle authentication to third-party services.
type: object
required:
- application_name
- data
- display_name
- id
- install_url
- uninstall_url
properties:
id:
description: The app's ID
type: string
example: example_app
display_name:
description: The app's display name
type: string
example: Example app
application_name:
description: The app's name
type: string
example: example
install_url:
description: The URL to install the app
nullable: true
type: string
format: uri
uninstall_url:
description: The URL to uninstall the app
nullable: true
type: string
format: uri
data:
description: Any data necessary to the app.
nullable: true
type: object
example: {}
Order:
title: Order
description: An order is a purchase made by a customer. It holds details about payment and fulfillment of the order. An order may also be created from a draft order, which is created by an admin user.
type: object
required:
- billing_address_id
- canceled_at
- cart_id
- created_at
- currency_code
- customer_id
- draft_order_id
- display_id
- email
- external_id
- fulfillment_status
- id
- idempotency_key
- metadata
- no_notification
- object
- payment_status
- region_id
- shipping_address_id
- status
- tax_rate
- updated_at
properties:
id:
description: The order's ID
type: string
example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
status:
description: The order's status
type: string
enum:
- pending
- completed
- archived
- canceled
- requires_action
default: pending
fulfillment_status:
description: The order's fulfillment status
type: string
enum:
- not_fulfilled
- partially_fulfilled
- fulfilled
- partially_shipped
- shipped
- partially_returned
- returned
- canceled
- requires_action
default: not_fulfilled
payment_status:
description: The order's payment status
type: string
enum:
- not_paid
- awaiting
- captured
- partially_refunded
- refunded
- canceled
- requires_action
default: not_paid
display_id:
description: The order's display ID
type: integer
example: 2
cart_id:
description: The ID of the cart associated with the order
nullable: true
type: string
example: cart_01G8ZH853Y6TFXWPG5EYE81X63
cart:
description: The details of the cart associated with the order.
x-expandable: cart
nullable: true
type: object
customer_id:
description: The ID of the customer associated with the order
type: string
example: cus_01G2SG30J8C85S4A5CHM2S1NS2
customer:
description: The details of the customer associated with the order.
x-expandable: customer
nullable: true
type: object
email:
description: The email associated with the order
type: string
format: email
billing_address_id:
description: The ID of the billing address associated with the order
nullable: true
type: string
example: addr_01G8ZH853YPY9B94857DY91YGW
billing_address:
description: The details of the billing address associated with the order.
x-expandable: billing_address
nullable: true
$ref: '#/components/schemas/Address'
shipping_address_id:
description: The ID of the shipping address associated with the order
nullable: true
type: string
example: addr_01G8ZH853YPY9B94857DY91YGW
shipping_address:
description: The details of the shipping address associated with the order.
x-expandable: shipping_address
nullable: true
$ref: '#/components/schemas/Address'
region_id:
description: The ID of the region this order was created in.
type: string
example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
region:
description: The details of the region this order was created in.
x-expandable: region
nullable: true
$ref: '#/components/schemas/Region'
currency_code:
description: The 3 character currency code that is used in the order
type: string
example: usd
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
description: See a list of codes.
currency:
description: The details of the currency used in the order.
x-expandable: currency
nullable: true
$ref: '#/components/schemas/Currency'
tax_rate:
description: The order's tax rate
nullable: true
type: number
example: 0
discounts:
description: The details of the discounts applied on the order.
type: array
x-expandable: discounts
items:
$ref: '#/components/schemas/Discount'
gift_cards:
description: The details of the gift card used in the order.
type: array
x-expandable: gift_cards
items:
$ref: '#/components/schemas/GiftCard'
shipping_methods:
description: The details of the shipping methods used in the order.
type: array
x-expandable: shipping_methods
items:
$ref: '#/components/schemas/ShippingMethod'
payments:
description: The details of the payments used in the order.
type: array
x-expandable: payments
items:
type: object
fulfillments:
description: The details of the fulfillments created for the order.
type: array
x-expandable: fulfillments
items:
type: object
returns:
description: The details of the returns created for the order.
type: array
x-expandable: returns
items:
type: object
claims:
description: The details of the claims created for the order.
type: array
x-expandable: claims
items:
type: object
refunds:
description: The details of the refunds created for the order.
type: array
x-expandable: refunds
items:
type: object
swaps:
description: The details of the swaps created for the order.
type: array
x-expandable: swaps
items:
type: object
draft_order_id:
description: The ID of the draft order this order was created from.
nullable: true
type: string
example: null
draft_order:
description: The details of the draft order this order was created from.
x-expandable: draft_order
nullable: true
type: object
items:
description: The details of the line items that belong to the order.
x-expandable: items
type: array
items:
$ref: '#/components/schemas/LineItem'
edits:
description: The details of the order edits done on the order.
type: array
x-expandable: edits
items:
type: object
gift_card_transactions:
description: The gift card transactions made in the order.
type: array
x-expandable: gift_card_transactions
items:
$ref: '#/components/schemas/GiftCardTransaction'
canceled_at:
description: The date the order was canceled on.
nullable: true
type: string
format: date-time
no_notification:
description: Flag for describing whether or not notifications related to this should be send.
nullable: true
type: boolean
example: false
idempotency_key:
description: Randomly generated key used to continue the processing of the order in case of failure.
nullable: true
type: string
externalDocs:
url: https://docs.medusajs.com/development/idempotency-key/overview.md
description: Learn more how to use the idempotency key.
external_id:
description: The ID of an external order.
nullable: true
type: string
example: null
sales_channel_id:
description: The ID of the sales channel this order belongs to.
nullable: true
type: string
example: null
sales_channel:
description: The details of the sales channel this order belongs to.
x-expandable: sales_channel
nullable: true
$ref: '#/components/schemas/SalesChannel'
shipping_total:
type: integer
description: The total of shipping
example: 1000
nullable: true
shipping_tax_total:
type: integer
description: The tax total applied on shipping
example: 1000
raw_discount_total:
description: The total of discount
type: integer
example: 800
discount_total:
description: The total of discount rounded
type: integer
example: 800
tax_total:
description: The total of tax
type: integer
example: 0
item_tax_total:
description: The tax total applied on items
type: integer
example: 0
nullable: true
refunded_total:
description: The total amount refunded if the order is returned.
type: integer
example: 0
total:
description: The total amount of the order
type: integer
example: 8200
subtotal:
description: The subtotal of the order
type: integer
example: 8000
paid_total:
description: The total amount paid
type: integer
example: 8000
refundable_amount:
description: The amount that can be refunded
type: integer
example: 8200
gift_card_total:
description: The total of gift cards
type: integer
example: 0
gift_card_tax_total:
description: The total of gift cards with taxes
type: integer
example: 0
returnable_items:
description: The details of the line items that are returnable as part of the order, swaps, or claims
type: array
x-expandable: returnable_items
items:
$ref: '#/components/schemas/LineItem'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
sales_channels:
description: The associated sales channels.
type: array
nullable: true
x-expandable: sales_channels
x-featureFlag: medusa_v2
items:
$ref: '#/components/schemas/SalesChannel'
OrderEdit:
title: Order Edit
description: Order edit allows modifying items in an order, such as adding, updating, or deleting items from the original order. Once the order edit is confirmed, the changes are reflected on the original order.
type: object
required:
- canceled_at
- canceled_by
- confirmed_by
- confirmed_at
- created_at
- created_by
- declined_at
- declined_by
- declined_reason
- id
- internal_note
- order_id
- payment_collection_id
- requested_at
- requested_by
- status
- updated_at
properties:
id:
description: The order edit's ID
type: string
example: oe_01G8TJSYT9M6AVS5N4EMNFS1EK
order_id:
description: The ID of the order that is edited
type: string
example: order_01G2SG30J8C85S4A5CHM2S1NS2
order:
description: The details of the order that this order edit was created for.
x-expandable: order
nullable: true
type: object
changes:
description: The details of all the changes on the original order's line items.
x-expandable: changes
type: array
items:
$ref: '#/components/schemas/OrderItemChange'
internal_note:
description: An optional note with additional details about the order edit.
nullable: true
type: string
example: Included two more items B to the order.
created_by:
description: The unique identifier of the user or customer who created the order edit.
type: string
requested_by:
description: The unique identifier of the user or customer who requested the order edit.
nullable: true
type: string
requested_at:
description: The date with timezone at which the edit was requested.
nullable: true
type: string
format: date-time
confirmed_by:
description: The unique identifier of the user or customer who confirmed the order edit.
nullable: true
type: string
confirmed_at:
description: The date with timezone at which the edit was confirmed.
nullable: true
type: string
format: date-time
declined_by:
description: The unique identifier of the user or customer who declined the order edit.
nullable: true
type: string
declined_at:
description: The date with timezone at which the edit was declined.
nullable: true
type: string
format: date-time
declined_reason:
description: An optional note why the order edit is declined.
nullable: true
type: string
canceled_by:
description: The unique identifier of the user or customer who cancelled the order edit.
nullable: true
type: string
canceled_at:
description: The date with timezone at which the edit was cancelled.
nullable: true
type: string
format: date-time
subtotal:
description: The total of subtotal
type: integer
example: 8000
discount_total:
description: The total of discount
type: integer
example: 800
shipping_total:
description: The total of the shipping amount
type: integer
example: 800
gift_card_total:
description: The total of the gift card amount
type: integer
example: 800
gift_card_tax_total:
description: The total of the gift card tax amount
type: integer
example: 800
tax_total:
description: The total of tax
type: integer
example: 0
total:
description: The total amount of the edited order.
type: integer
example: 8200
difference_due:
description: The difference between the total amount of the order and total amount of edited order.
type: integer
example: 8200
status:
description: The status of the order edit.
type: string
enum:
- confirmed
- declined
- requested
- created
- canceled
items:
description: The details of the cloned items from the original order with the new changes. Once the order edit is confirmed, these line items are associated with the original order.
type: array
x-expandable: items
items:
$ref: '#/components/schemas/LineItem'
payment_collection_id:
description: The ID of the payment collection
nullable: true
type: string
example: paycol_01G8TJSYT9M6AVS5N4EMNFS1EK
payment_collection:
description: The details of the payment collection used to authorize additional payment if necessary.
x-expandable: payment_collection
nullable: true
$ref: '#/components/schemas/PaymentCollection'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
OrderItemChange:
title: Order Item Change
description: An order item change is a change made within an order edit to an order's items. These changes are not reflected on the original order until the order edit is confirmed.
type: object
required:
- created_at
- deleted_at
- id
- line_item_id
- order_edit_id
- original_line_item_id
- type
- updated_at
properties:
id:
description: The order item change's ID
type: string
example: oic_01G8TJSYT9M6AVS5N4EMNFS1EK
type:
description: The order item change's status
type: string
enum:
- item_add
- item_remove
- item_update
order_edit_id:
description: The ID of the order edit
type: string
example: oe_01G2SG30J8C85S4A5CHM2S1NS2
order_edit:
description: The details of the order edit the item change is associated with.
x-expandable: order_edit
nullable: true
type: object
original_line_item_id:
description: The ID of the original line item in the order
nullable: true
type: string
example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
original_line_item:
description: The details of the original line item this item change references. This is used if the item change updates or deletes the original item.
x-expandable: original_line_item
nullable: true
$ref: '#/components/schemas/LineItem'
line_item_id:
description: The ID of the cloned line item.
nullable: true
type: string
example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
line_item:
description: The details of the resulting line item after the item change. This line item is then used in the original order once the order edit is confirmed.
x-expandable: line_item
nullable: true
$ref: '#/components/schemas/LineItem'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
Payment:
title: Payment
description: A payment is originally created from a payment session. Once a payment session is authorized, the payment is created to represent the authorized amount with a given payment method. Payments can be captured, canceled or refunded. Payments can be made towards orders, swaps, order edits, or other resources.
type: object
required:
- amount
- amount_refunded
- canceled_at
- captured_at
- cart_id
- created_at
- currency_code
- data
- id
- idempotency_key
- metadata
- order_id
- provider_id
- swap_id
- updated_at
properties:
id:
description: The payment's ID
type: string
example: pay_01G2SJNT6DEEWDFNAJ4XWDTHKE
swap_id:
description: The ID of the swap that this payment was potentially created for.
nullable: true
type: string
example: null
swap:
description: The details of the swap that this payment was potentially created for.
x-expandable: swap
nullable: true
type: object
cart_id:
description: The ID of the cart that the payment session was potentially created for.
nullable: true
type: string
cart:
description: The details of the cart that the payment session was potentially created for.
x-expandable: cart
nullable: true
type: object
order_id:
description: The ID of the order that the payment session was potentially created for.
nullable: true
type: string
example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
order:
description: The details of the order that the payment session was potentially created for.
x-expandable: order
nullable: true
type: object
amount:
description: The amount that the Payment has been authorized for.
type: integer
example: 100
currency_code:
description: The 3 character ISO currency code of the payment.
type: string
example: usd
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
description: See a list of codes.
currency:
description: The details of the currency of the payment.
x-expandable: currency
nullable: true
$ref: '#/components/schemas/Currency'
amount_refunded:
description: The amount of the original Payment amount that has been refunded back to the Customer.
type: integer
default: 0
example: 0
provider_id:
description: The id of the Payment Provider that is responsible for the Payment
type: string
example: manual
data:
description: The data required for the Payment Provider to identify, modify and process the Payment. Typically this will be an object that holds an id to the external payment session, but can be an empty object if the Payment Provider doesn't hold any state.
type: object
example: {}
captured_at:
description: The date with timezone at which the Payment was captured.
nullable: true
type: string
format: date-time
canceled_at:
description: The date with timezone at which the Payment was canceled.
nullable: true
type: string
format: date-time
idempotency_key:
description: Randomly generated key used to continue the completion of a payment in case of failure.
nullable: true
type: string
externalDocs:
url: https://docs.medusajs.com/development/idempotency-key/overview.md
description: Learn more how to use the idempotency key.
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
PaymentCollection:
title: Payment Collection
description: A payment collection allows grouping and managing a list of payments at one. This can be helpful when making additional payment for order edits or integrating installment payments.
type: object
required:
- amount
- authorized_amount
- created_at
- created_by
- currency_code
- deleted_at
- description
- id
- metadata
- region_id
- status
- type
- updated_at
properties:
id:
description: The payment collection's ID
type: string
example: paycol_01G8TJSYT9M6AVS5N4EMNFS1EK
type:
description: The type of the payment collection
type: string
enum:
- order_edit
status:
description: The type of the payment collection
type: string
enum:
- not_paid
- awaiting
- authorized
- partially_authorized
- canceled
description:
description: Description of the payment collection
nullable: true
type: string
amount:
description: Amount of the payment collection.
type: integer
authorized_amount:
description: Authorized amount of the payment collection.
nullable: true
type: integer
region_id:
description: The ID of the region this payment collection is associated with.
type: string
example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
region:
description: The details of the region this payment collection is associated with.
x-expandable: region
nullable: true
$ref: '#/components/schemas/Region'
currency_code:
description: The three character ISO code for the currency this payment collection is associated with.
type: string
example: usd
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
description: See a list of codes.
currency:
description: The details of the currency this payment collection is associated with.
x-expandable: currency
nullable: true
$ref: '#/components/schemas/Currency'
payment_sessions:
description: The details of the payment sessions created as part of the payment collection.
type: array
x-expandable: payment_sessions
items:
$ref: '#/components/schemas/PaymentSession'
payments:
description: The details of the payments created as part of the payment collection.
type: array
x-expandable: payments
items:
$ref: '#/components/schemas/Payment'
created_by:
description: The ID of the user that created the payment collection.
type: string
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
PaymentProvider:
title: Payment Provider
description: A payment provider represents a payment service installed in the Medusa backend, either through a plugin or backend customizations. It holds the payment service's installation status.
type: object
required:
- id
- is_installed
properties:
id:
description: The ID of the payment provider as given by the payment service.
type: string
example: manual
is_installed:
description: Whether the payment service is installed in the current version. If a payment service is no longer installed, the `is_installed` attribute is set to `false`.
type: boolean
default: true
PaymentSession:
title: Payment Session
description: A Payment Session is created when a Customer initilizes the checkout flow, and can be used to hold the state of a payment flow. Each Payment Session is controlled by a Payment Provider, which is responsible for the communication with external payment services. Authorized Payment Sessions will eventually get promoted to Payments to indicate that they are authorized for payment processing such as capture or refund. Payment sessions can also be used as part of payment collections.
type: object
required:
- amount
- cart_id
- created_at
- data
- id
- is_initiated
- is_selected
- idempotency_key
- payment_authorized_at
- provider_id
- status
- updated_at
properties:
id:
description: The payment session's ID
type: string
example: ps_01G901XNSRM2YS3ASN9H5KG3FZ
cart_id:
description: The ID of the cart that the payment session was created for.
nullable: true
type: string
example: cart_01G8ZH853Y6TFXWPG5EYE81X63
cart:
description: The details of the cart that the payment session was created for.
x-expandable: cart
nullable: true
$ref: '#/components/schemas/Cart'
provider_id:
description: The ID of the Payment Provider that is responsible for the Payment Session
type: string
example: manual
is_selected:
description: A flag to indicate if the Payment Session has been selected as the method that will be used to complete the purchase.
nullable: true
type: boolean
example: true
is_initiated:
description: A flag to indicate if a communication with the third party provider has been initiated.
type: boolean
default: false
example: true
status:
description: Indicates the status of the Payment Session. Will default to `pending`, and will eventually become `authorized`. Payment Sessions may have the status of `requires_more` to indicate that further actions are to be completed by the Customer.
type: string
enum:
- authorized
- pending
- requires_more
- error
- canceled
example: pending
data:
description: The data required for the Payment Provider to identify, modify and process the Payment Session. Typically this will be an object that holds an id to the external payment session, but can be an empty object if the Payment Provider doesn't hold any state.
type: object
example: {}
idempotency_key:
description: Randomly generated key used to continue the completion of a cart in case of failure.
nullable: true
type: string
externalDocs:
url: https://docs.medusajs.com/development/idempotency-key/overview.md
description: Learn more how to use the idempotency key.
amount:
description: The amount that the Payment Session has been authorized for.
nullable: true
type: integer
example: 100
payment_authorized_at:
description: The date with timezone at which the Payment Session was authorized.
nullable: true
type: string
format: date-time
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
PriceList:
title: Price List
description: A Price List represents a set of prices that override the default price for one or more product variants.
type: object
required:
- created_at
- deleted_at
- description
- ends_at
- id
- name
- starts_at
- status
- type
- updated_at
properties:
id:
description: The price list's ID
type: string
example: pl_01G8X3CKJXCG5VXVZ87H9KC09W
name:
description: The price list's name
type: string
example: VIP Prices
description:
description: The price list's description
type: string
example: Prices for VIP customers
type:
description: The type of Price List. This can be one of either `sale` or `override`.
type: string
enum:
- sale
- override
default: sale
status:
description: The status of the Price List
type: string
enum:
- active
- draft
default: draft
starts_at:
description: The date with timezone that the Price List starts being valid.
nullable: true
type: string
format: date-time
ends_at:
description: The date with timezone that the Price List stops being valid.
nullable: true
type: string
format: date-time
customer_groups:
description: The details of the customer groups that the Price List can apply to.
type: array
x-expandable: customer_groups
items:
$ref: '#/components/schemas/CustomerGroup'
prices:
description: The prices that belong to the price list, represented as a Money Amount.
type: array
x-expandable: prices
items:
$ref: '#/components/schemas/MoneyAmount'
includes_tax:
description: Whether the price list prices include tax
type: boolean
x-featureFlag: tax_inclusive_pricing
default: false
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
PricedProduct:
title: Priced Product
type: object
allOf:
- $ref: '#/components/schemas/Product'
- type: object
properties:
variants:
description: The product variants and their prices.
type: array
items:
$ref: '#/components/schemas/PricedVariant'
PricedShippingOption:
title: Priced Shipping Option
type: object
allOf:
- $ref: '#/components/schemas/ShippingOption'
- type: object
properties:
price_incl_tax:
type: number
description: Price including taxes
tax_rates:
type: array
description: An array of applied tax rates
items:
type: object
properties:
rate:
type: number
description: The tax rate value
name:
type: string
description: The name of the tax rate
code:
type: string
description: The code of the tax rate
tax_amount:
type: number
description: The taxes applied.
PricedVariant:
title: Priced Product Variant
type: object
allOf:
- $ref: '#/components/schemas/ProductVariant'
- type: object
properties:
original_price:
type: number
description: The original price of the variant without any discounted prices applied.
calculated_price:
type: number
description: The calculated price of the variant. Can be a discounted price.
original_price_incl_tax:
type: number
description: The original price of the variant including taxes.
calculated_price_incl_tax:
type: number
description: The calculated price of the variant including taxes.
original_tax:
type: number
description: The taxes applied on the original price.
calculated_tax:
type: number
description: The taxes applied on the calculated price.
tax_rates:
type: array
description: An array of applied tax rates
items:
type: object
properties:
rate:
type: number
description: The tax rate value
name:
type: string
description: The name of the tax rate
code:
type: string
description: The code of the tax rate
Product:
title: Product
description: A product is a saleable item that holds general information such as name or description. It must include at least one Product Variant, where each product variant defines different options to purchase the product with (for example, different sizes or colors). The prices and inventory of the product are defined on the variant level.
type: object
required:
- collection_id
- created_at
- deleted_at
- description
- discountable
- external_id
- handle
- height
- hs_code
- id
- is_giftcard
- length
- material
- metadata
- mid_code
- origin_country
- profile_id
- status
- subtitle
- type_id
- thumbnail
- title
- updated_at
- weight
- width
properties:
id:
description: The product's ID
type: string
example: prod_01G1G5V2MBA328390B5AXJ610F
title:
description: A title that can be displayed for easy identification of the Product.
type: string
example: Medusa Coffee Mug
subtitle:
description: An optional subtitle that can be used to further specify the Product.
nullable: true
type: string
description:
description: A short description of the Product.
nullable: true
type: string
example: Every programmer's best friend.
handle:
description: A unique identifier for the Product (e.g. for slug structure).
nullable: true
type: string
example: coffee-mug
is_giftcard:
description: Whether the Product represents a Gift Card. Products that represent Gift Cards will automatically generate a redeemable Gift Card code once they are purchased.
type: boolean
default: false
status:
description: The status of the product
type: string
enum:
- draft
- proposed
- published
- rejected
default: draft
images:
description: The details of the product's images.
type: array
x-expandable: images
items:
$ref: '#/components/schemas/Image'
thumbnail:
description: A URL to an image file that can be used to identify the Product.
nullable: true
type: string
format: uri
options:
description: The details of the Product Options that are defined for the Product. The product's variants will have a unique combination of values of the product's options.
type: array
x-expandable: options
items:
$ref: '#/components/schemas/ProductOption'
variants:
description: The details of the Product Variants that belong to the Product. Each will have a unique combination of values of the product's options.
type: array
x-expandable: variants
items:
$ref: '#/components/schemas/ProductVariant'
categories:
description: The details of the product categories that this product belongs to.
type: array
x-expandable: categories
x-featureFlag: product_categories
items:
$ref: '#/components/schemas/ProductCategory'
profile_id:
description: The ID of the shipping profile that the product belongs to. The shipping profile has a set of defined shipping options that can be used to fulfill the product.
type: string
example: sp_01G1G5V239ENSZ5MV4JAR737BM
profile:
description: The details of the shipping profile that the product belongs to. The shipping profile has a set of defined shipping options that can be used to fulfill the product.
x-expandable: profile
nullable: true
$ref: '#/components/schemas/ShippingProfile'
profiles:
description: Available if the relation `profiles` is expanded.
nullable: true
type: array
items:
$ref: '#/components/schemas/ShippingProfile'
weight:
description: The weight of the Product Variant. May be used in shipping rate calculations.
nullable: true
type: number
example: null
length:
description: The length of the Product Variant. May be used in shipping rate calculations.
nullable: true
type: number
example: null
height:
description: The height of the Product Variant. May be used in shipping rate calculations.
nullable: true
type: number
example: null
width:
description: The width of the Product Variant. May be used in shipping rate calculations.
nullable: true
type: number
example: null
hs_code:
description: The Harmonized System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.
nullable: true
type: string
example: null
origin_country:
description: The country in which the Product Variant was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.
nullable: true
type: string
example: null
mid_code:
description: The Manufacturers Identification code that identifies the manufacturer of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.
nullable: true
type: string
example: null
material:
description: The material and composition that the Product Variant is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.
nullable: true
type: string
example: null
collection_id:
description: The ID of the product collection that the product belongs to.
nullable: true
type: string
example: pcol_01F0YESBFAZ0DV6V831JXWH0BG
collection:
description: The details of the product collection that the product belongs to.
x-expandable: collection
nullable: true
$ref: '#/components/schemas/ProductCollection'
type_id:
description: The ID of the product type that the product belongs to.
nullable: true
type: string
example: ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A
type:
description: The details of the product type that the product belongs to.
x-expandable: type
nullable: true
$ref: '#/components/schemas/ProductType'
tags:
description: The details of the product tags used in this product.
type: array
x-expandable: type
items:
$ref: '#/components/schemas/ProductTag'
discountable:
description: Whether the Product can be discounted. Discounts will not apply to Line Items of this Product when this flag is set to `false`.
type: boolean
default: true
external_id:
description: The external ID of the product
nullable: true
type: string
example: null
sales_channels:
description: The details of the sales channels this product is available in.
type: array
x-expandable: sales_channels
items:
$ref: '#/components/schemas/SalesChannel'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
ProductCategory:
title: Product Category
description: A product category can be used to categorize products into a hierarchy of categories.
x-resourceId: ProductCategory
x-featureFlag: product_categories
type: object
required:
- category_children
- created_at
- handle
- id
- is_active
- is_internal
- metadata
- mpath
- name
- parent_category_id
- updated_at
properties:
id:
description: The product category's ID
type: string
example: pcat_01G2SG30J8C85S4A5CHM2S1NS2
name:
description: The product category's name
type: string
example: Regular Fit
description:
description: The product category's description.
type: string
default: ''
handle:
description: A unique string that identifies the Product Category - can for example be used in slug structures.
type: string
example: regular-fit
mpath:
description: A string for Materialized Paths - used for finding ancestors and descendents
nullable: true
type: string
example: pcat_id1.pcat_id2.pcat_id3
is_internal:
type: boolean
description: A flag to make product category an internal category for admins
default: false
is_active:
type: boolean
description: A flag to make product category visible/hidden in the store front
default: false
rank:
type: integer
description: An integer that depicts the rank of category in a tree node
default: 0
category_children:
description: The details of the category's children.
type: array
x-expandable: category_children
items:
type: object
parent_category_id:
description: The ID of the parent category.
nullable: true
type: string
default: null
parent_category:
description: The details of the parent of this category.
x-expandable: parent_category
nullable: true
type: object
products:
description: The details of the products that belong to this category.
type: array
x-expandable: products
items:
type: object
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
ProductCollection:
title: Product Collection
description: A Product Collection allows grouping together products for promotional purposes. For example, an admin can create a Summer collection, add products to it, and showcase it on the storefront.
type: object
required:
- created_at
- deleted_at
- handle
- id
- metadata
- title
- updated_at
properties:
id:
description: The product collection's ID
type: string
example: pcol_01F0YESBFAZ0DV6V831JXWH0BG
title:
description: The title that the Product Collection is identified by.
type: string
example: Summer Collection
handle:
description: A unique string that identifies the Product Collection - can for example be used in slug structures.
nullable: true
type: string
example: summer-collection
products:
description: The details of the products that belong to this product collection.
type: array
x-expandable: products
items:
type: object
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
ProductOption:
title: Product Option
description: A Product Option defines properties that may vary between different variants of a Product. Common Product Options are "Size" and "Color". Admins are free to create any product options.
type: object
required:
- created_at
- deleted_at
- id
- metadata
- product_id
- title
- updated_at
properties:
id:
description: The product option's ID
type: string
example: opt_01F0YESHQBZVKCEXJ24BS6PCX3
title:
description: The title that the Product Option is defined by (e.g. `Size`).
type: string
example: Size
values:
description: The details of the values of the product option.
type: array
x-expandable: values
items:
$ref: '#/components/schemas/ProductOptionValue'
product_id:
description: The ID of the product that this product option belongs to.
type: string
example: prod_01G1G5V2MBA328390B5AXJ610F
product:
description: The details of the product that this product option belongs to.
x-expandable: product
nullable: true
type: object
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
ProductOptionValue:
title: Product Option Value
description: An option value is one of the possible values of a Product Option. Product Variants specify a unique combination of product option values.
type: object
required:
- created_at
- deleted_at
- id
- metadata
- option_id
- updated_at
- value
- variant_id
properties:
id:
description: The product option value's ID
type: string
example: optval_01F0YESHR7S6ECD03RF6W12DSJ
value:
description: The value that the Product Variant has defined for the specific Product Option (e.g. if the Product Option is "Size" this value could be `Small`, `Medium` or `Large`).
type: string
example: large
option_id:
description: The ID of the Product Option that the Product Option Value belongs to.
type: string
example: opt_01F0YESHQBZVKCEXJ24BS6PCX3
option:
description: The details of the product option that the Product Option Value belongs to.
x-expandable: option
nullable: true
type: object
variant_id:
description: The ID of the product variant that uses this product option value.
type: string
example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6
variant:
description: The details of the product variant that uses this product option value.
x-expandable: variant
nullable: true
type: object
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
ProductTag:
title: Product Tag
description: A Product Tag can be added to Products for easy filtering and grouping.
type: object
required:
- created_at
- deleted_at
- id
- metadata
- updated_at
- value
properties:
id:
description: The product tag's ID
type: string
example: ptag_01G8K2MTMG9168F2B70S1TAVK3
value:
description: The value that the Product Tag represents
type: string
example: Pants
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
ProductTaxRate:
title: Product Tax Rate
description: This represents the association between a tax rate and a product to indicate that the product is taxed in a way different than the default.
type: object
required:
- created_at
- metadata
- product_id
- rate_id
- updated_at
properties:
product_id:
description: The ID of the Product
type: string
example: prod_01G1G5V2MBA328390B5AXJ610F
product:
description: The details of the product.
x-expandable: product
nullable: true
$ref: '#/components/schemas/Product'
rate_id:
description: The ID of the Tax Rate
type: string
example: txr_01G8XDBAWKBHHJRKH0AV02KXBR
tax_rate:
description: The details of the tax rate.
x-expandable: tax_rate
nullable: true
$ref: '#/components/schemas/TaxRate'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
ProductType:
title: Product Type
description: A Product Type can be added to Products for filtering and reporting purposes.
type: object
required:
- created_at
- deleted_at
- id
- metadata
- updated_at
- value
properties:
id:
description: The product type's ID
type: string
example: ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A
value:
description: The value that the Product Type represents.
type: string
example: Clothing
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
ProductTypeTaxRate:
title: Product Type Tax Rate
description: This represents the association between a tax rate and a product type to indicate that the product type is taxed in a different way than the default.
type: object
required:
- created_at
- metadata
- product_type_id
- rate_id
- updated_at
properties:
product_type_id:
description: The ID of the Product type
type: string
example: ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A
product_type:
description: The details of the product type.
x-expandable: product_type
nullable: true
$ref: '#/components/schemas/ProductType'
rate_id:
description: The id of the Tax Rate
type: string
example: txr_01G8XDBAWKBHHJRKH0AV02KXBR
tax_rate:
description: The details of the tax rate.
x-expandable: tax_rate
nullable: true
$ref: '#/components/schemas/TaxRate'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
ProductVariant:
title: Product Variant
description: A Product Variant represents a Product with a specific set of Product Option configurations. The maximum number of Product Variants that a Product can have is given by the number of available Product Option combinations. A product must at least have one product variant.
type: object
required:
- allow_backorder
- barcode
- created_at
- deleted_at
- ean
- height
- hs_code
- id
- inventory_quantity
- length
- manage_inventory
- material
- metadata
- mid_code
- origin_country
- product_id
- sku
- title
- upc
- updated_at
- weight
- width
properties:
id:
description: The product variant's ID
type: string
example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6
title:
description: A title that can be displayed for easy identification of the Product Variant.
type: string
example: Small
product_id:
description: The ID of the product that the product variant belongs to.
type: string
example: prod_01G1G5V2MBA328390B5AXJ610F
product:
description: The details of the product that the product variant belongs to.
x-expandable: product
nullable: true
type: object
prices:
description: The details of the prices of the Product Variant, each represented as a Money Amount. Each Money Amount represents a price in a given currency or a specific Region.
type: array
x-expandable: prices
items:
$ref: '#/components/schemas/MoneyAmount'
sku:
description: The unique stock keeping unit used to identify the Product Variant. This will usually be a unique identifer for the item that is to be shipped, and can be referenced across multiple systems.
nullable: true
type: string
example: shirt-123
barcode:
description: A generic field for a GTIN number that can be used to identify the Product Variant.
nullable: true
type: string
example: null
ean:
description: An EAN barcode number that can be used to identify the Product Variant.
nullable: true
type: string
example: null
upc:
description: A UPC barcode number that can be used to identify the Product Variant.
nullable: true
type: string
example: null
variant_rank:
description: The ranking of this variant
nullable: true
type: number
default: 0
inventory_quantity:
description: The current quantity of the item that is stocked.
type: integer
example: 100
allow_backorder:
description: Whether the Product Variant should be purchasable when `inventory_quantity` is 0.
type: boolean
default: false
manage_inventory:
description: Whether Medusa should manage inventory for the Product Variant.
type: boolean
default: true
hs_code:
description: The Harmonized System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.
nullable: true
type: string
example: null
origin_country:
description: The country in which the Product Variant was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.
nullable: true
type: string
example: null
mid_code:
description: The Manufacturers Identification code that identifies the manufacturer of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.
nullable: true
type: string
example: null
material:
description: The material and composition that the Product Variant is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.
nullable: true
type: string
example: null
weight:
description: The weight of the Product Variant. May be used in shipping rate calculations.
nullable: true
type: number
example: null
length:
description: The length of the Product Variant. May be used in shipping rate calculations.
nullable: true
type: number
example: null
height:
description: The height of the Product Variant. May be used in shipping rate calculations.
nullable: true
type: number
example: null
width:
description: The width of the Product Variant. May be used in shipping rate calculations.
nullable: true
type: number
example: null
options:
description: The details of the product options that this product variant defines values for.
type: array
x-expandable: options
items:
$ref: '#/components/schemas/ProductOptionValue'
inventory_items:
description: The details inventory items of the product variant.
type: array
x-expandable: inventory_items
items:
$ref: '#/components/schemas/ProductVariantInventoryItem'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
purchasable:
description: |
Only used with the inventory modules.
A boolean value indicating whether the Product Variant is purchasable.
A variant is purchasable if:
- inventory is not managed
- it has no inventory items
- it is in stock
- it is backorderable.
type: boolean
ProductVariantInventoryItem:
title: Product Variant Inventory Item
description: A Product Variant Inventory Item links variants with inventory items and denotes the required quantity of the variant.
type: object
required:
- created_at
- deleted_at
- id
- inventory_item_id
- required_quantity
- updated_at
- variant_id
properties:
id:
description: The product variant inventory item's ID
type: string
example: pvitem_01G8X9A7ESKAJXG2H0E6F1MW7A
inventory_item_id:
description: The id of the inventory item
type: string
variant_id:
description: The id of the variant.
type: string
variant:
description: The details of the product variant.
x-expandable: variant
nullable: true
type: object
required_quantity:
description: The quantity of an inventory item required for the variant.
type: integer
default: 1
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
PublishableApiKey:
title: Publishable API key
description: A Publishable API key defines scopes that resources are available in. Then, it can be used in request to infer the resources without having to directly pass them. For example, a publishable API key can be associated with one or more sales channels. Then, when the publishable API key is passed in the header of a request, it is inferred what sales channel is being used without having to pass the sales channel as a query or body parameter of the request. Publishable API keys can only be used with sales channels, at the moment.
type: object
required:
- created_at
- created_by
- id
- revoked_by
- revoked_at
- title
- updated_at
properties:
id:
description: The key's ID
type: string
example: pk_01G1G5V27GYX4QXNARRQCW1N8T
created_by:
description: The unique identifier of the user that created the key.
nullable: true
type: string
example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V
revoked_by:
description: The unique identifier of the user that revoked the key.
nullable: true
type: string
example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V
revoked_at:
description: The date with timezone at which the key was revoked.
nullable: true
type: string
format: date-time
title:
description: The key's title.
type: string
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
PublishableApiKeySalesChannel:
title: Publishable API Key Sales Channel
description: This represents the association between the Publishable API keys and Sales Channels
type: object
required:
- publishable_key_id
- sales_channel_id
- created_at
- updated_at
- deleted_at
properties:
id:
description: The relation's ID
type: string
example: pksc_01G8X9A7ESKAJXG2H0E6F1MW7A
sales_channel_id:
description: The sales channel's ID
type: string
example: sc_01G1G5V21KADXNGH29BJMAJ4B4
publishable_key_id:
description: The publishable API key's ID
type: string
example: pak_01G1G5V21KADXNGH29BJMAJ4B4
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
Refund:
title: Refund
description: A refund represents an amount of money transfered back to the customer for a given reason. Refunds may occur in relation to Returns, Swaps and Claims, but can also be initiated by an admin for an order.
type: object
required:
- amount
- created_at
- id
- idempotency_key
- metadata
- note
- order_id
- payment_id
- reason
- updated_at
properties:
id:
description: The refund's ID
type: string
example: ref_01G1G5V27GYX4QXNARRQCW1N8T
order_id:
description: The ID of the order this refund was created for.
nullable: true
type: string
example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
order:
description: The details of the order this refund was created for.
x-expandable: order
nullable: true
type: object
payment_id:
description: The payment's ID, if available.
nullable: true
type: string
example: pay_01G8ZCC5W42ZNY842124G7P5R9
payment:
description: The details of the payment associated with the refund.
x-expandable: payment
nullable: true
type: object
amount:
description: The amount that has be refunded to the Customer.
type: integer
example: 1000
note:
description: An optional note explaining why the amount was refunded.
nullable: true
type: string
example: I didn't like it
reason:
description: The reason given for the Refund, will automatically be set when processed as part of a Swap, Claim or Return.
type: string
enum:
- discount
- return
- swap
- claim
- other
example: return
idempotency_key:
description: Randomly generated key used to continue the completion of the refund in case of failure.
nullable: true
type: string
externalDocs:
url: https://docs.medusajs.com/development/idempotency-key/overview.md
description: Learn more how to use the idempotency key.
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
Region:
title: Region
description: A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
type: object
required:
- automatic_taxes
- created_at
- currency_code
- deleted_at
- gift_cards_taxable
- id
- metadata
- name
- tax_code
- tax_provider_id
- tax_rate
- updated_at
properties:
id:
description: The region's ID
type: string
example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
name:
description: The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name.
type: string
example: EU
currency_code:
description: The three character currency code used in the region.
type: string
example: usd
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
description: See a list of codes.
currency:
description: The details of the currency used in the region.
x-expandable: currency
nullable: true
$ref: '#/components/schemas/Currency'
tax_rate:
description: The tax rate that should be charged on purchases in the Region.
type: number
example: 0
tax_rates:
description: The details of the tax rates used in the region, aside from the default rate.
type: array
x-expandable: tax_rates
items:
$ref: '#/components/schemas/TaxRate'
tax_code:
description: The tax code used on purchases in the Region. This may be used by other systems for accounting purposes.
nullable: true
type: string
example: null
gift_cards_taxable:
description: Whether the gift cards are taxable or not in this region.
type: boolean
default: true
automatic_taxes:
description: Whether taxes should be automated in this region.
type: boolean
default: true
countries:
description: The details of the countries included in this region.
type: array
x-expandable: countries
items:
$ref: '#/components/schemas/Country'
tax_provider_id:
description: The ID of the tax provider used in this region
nullable: true
type: string
example: null
tax_provider:
description: The details of the tax provider used in the region.
x-expandable: tax_provider
nullable: true
$ref: '#/components/schemas/TaxProvider'
payment_providers:
description: The details of the payment providers that can be used to process payments in the region.
type: array
x-expandable: payment_providers
items:
$ref: '#/components/schemas/PaymentProvider'
fulfillment_providers:
description: The details of the fulfillment providers that can be used to fulfill items of orders and similar resources in the region.
type: array
x-expandable: fulfillment_providers
items:
$ref: '#/components/schemas/FulfillmentProvider'
includes_tax:
description: Whether the prices for the region include tax
type: boolean
x-featureFlag: tax_inclusive_pricing
default: false
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
ReservationItemDTO:
title: Reservation item
description: Represents a reservation of an inventory item at a stock location
type: object
required:
- id
- location_id
- inventory_item_id
- quantity
properties:
id:
description: The id of the reservation item
type: string
location_id:
description: The id of the location of the reservation
type: string
inventory_item_id:
description: The id of the inventory item the reservation relates to
type: string
description:
description: Description of the reservation item
type: string
created_by:
description: UserId of user who created the reservation item
type: string
quantity:
description: The id of the reservation item
type: number
metadata:
type: object
description: An optional key-value map with additional details
example:
car: white
created_at:
type: string
description: The date with timezone at which the resource was created.
format: date-time
updated_at:
type: string
description: The date with timezone at which the resource was updated.
format: date-time
deleted_at:
type: string
description: The date with timezone at which the resource was deleted.
format: date-time
Return:
title: Return
description: A Return holds information about Line Items that a Customer wishes to send back, along with how the items will be returned. Returns can also be used as part of a Swap or a Claim.
type: object
required:
- claim_order_id
- created_at
- id
- idempotency_key
- location_id
- metadata
- no_notification
- order_id
- received_at
- refund_amount
- shipping_data
- status
- swap_id
- updated_at
properties:
id:
description: The return's ID
type: string
example: ret_01F0YET7XPCMF8RZ0Y151NZV2V
status:
description: Status of the Return.
type: string
enum:
- requested
- received
- requires_action
- canceled
default: requested
items:
description: The details of the items that the customer is returning.
type: array
x-expandable: items
items:
$ref: '#/components/schemas/ReturnItem'
swap_id:
description: The ID of the swap that the return may belong to.
nullable: true
type: string
example: null
swap:
description: The details of the swap that the return may belong to.
x-expandable: swap
nullable: true
type: object
claim_order_id:
description: The ID of the claim that the return may belong to.
nullable: true
type: string
example: null
claim_order:
description: The details of the claim that the return may belong to.
x-expandable: claim_order
nullable: true
type: object
order_id:
description: The ID of the order that the return was created for.
nullable: true
type: string
example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
order:
description: The details of the order that the return was created for.
x-expandable: order
nullable: true
type: object
shipping_method:
description: The details of the Shipping Method that will be used to send the Return back. Can be null if the Customer will handle the return shipment themselves.
x-expandable: shipping_method
nullable: true
$ref: '#/components/schemas/ShippingMethod'
shipping_data:
description: Data about the return shipment as provided by the Fulfilment Provider that handles the return shipment.
nullable: true
type: object
example: {}
location_id:
description: The ID of the stock location the return will be added back.
nullable: true
type: string
example: sloc_01G8TJSYT9M6AVS5N4EMNFS1EK
refund_amount:
description: The amount that should be refunded as a result of the return.
type: integer
example: 1000
no_notification:
description: When set to true, no notification will be sent related to this return.
nullable: true
type: boolean
example: false
idempotency_key:
description: Randomly generated key used to continue the completion of the return in case of failure.
nullable: true
type: string
externalDocs:
url: https://docs.medusajs.com/development/idempotency-key/overview.md
description: Learn more how to use the idempotency key.
received_at:
description: The date with timezone at which the return was received.
nullable: true
type: string
format: date-time
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
ReturnItem:
title: Return Item
description: A return item represents a line item in an order that is to be returned. It includes details related to the return and the reason behind it.
type: object
required:
- is_requested
- item_id
- metadata
- note
- quantity
- reason_id
- received_quantity
- requested_quantity
- return_id
properties:
return_id:
description: The ID of the Return that the Return Item belongs to.
type: string
example: ret_01F0YET7XPCMF8RZ0Y151NZV2V
item_id:
description: The ID of the Line Item that the Return Item references.
type: string
example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
return_order:
description: Details of the Return that the Return Item belongs to.
x-expandable: return_order
nullable: true
type: object
item:
description: The details of the line item in the original order to be returned.
x-expandable: item
nullable: true
$ref: '#/components/schemas/LineItem'
quantity:
description: The quantity of the Line Item to be returned.
type: integer
example: 1
is_requested:
description: Whether the Return Item was requested initially or received unexpectedly in the warehouse.
type: boolean
default: true
requested_quantity:
description: The quantity that was originally requested to be returned.
nullable: true
type: integer
example: 1
received_quantity:
description: The quantity that was received in the warehouse.
nullable: true
type: integer
example: 1
reason_id:
description: The ID of the reason for returning the item.
nullable: true
type: string
example: rr_01G8X82GCCV2KSQHDBHSSAH5TQ
reason:
description: The details of the reason for returning the item.
x-expandable: reason
nullable: true
$ref: '#/components/schemas/ReturnReason'
note:
description: An optional note with additional details about the Return.
nullable: true
type: string
example: I didn't like it.
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
ReturnReason:
title: Return Reason
description: A Return Reason is a value defined by an admin. It can be used on Return Items in order to indicate why a Line Item was returned.
type: object
required:
- created_at
- deleted_at
- description
- id
- label
- metadata
- parent_return_reason_id
- updated_at
- value
properties:
id:
description: The return reason's ID
type: string
example: rr_01G8X82GCCV2KSQHDBHSSAH5TQ
value:
description: The value to identify the reason by.
type: string
example: damaged
label:
description: A text that can be displayed to the Customer as a reason.
type: string
example: Damaged goods
description:
description: A description of the Reason.
nullable: true
type: string
example: Items that are damaged
parent_return_reason_id:
description: The ID of the parent reason.
nullable: true
type: string
example: null
parent_return_reason:
description: The details of the parent reason.
x-expandable: parent_return_reason
nullable: true
type: object
return_reason_children:
description: The details of the child reasons.
x-expandable: return_reason_children
type: object
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
SalesChannel:
title: Sales Channel
description: A Sales Channel is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
type: object
required:
- created_at
- deleted_at
- description
- id
- is_disabled
- name
- updated_at
properties:
id:
description: The sales channel's ID
type: string
example: sc_01G8X9A7ESKAJXG2H0E6F1MW7A
name:
description: The name of the sales channel.
type: string
example: Market
description:
description: The description of the sales channel.
nullable: true
type: string
example: Multi-vendor market
is_disabled:
description: Specify if the sales channel is enabled or disabled.
type: boolean
default: false
locations:
description: The details of the stock locations related to the sales channel.
type: array
x-expandable: locations
items:
$ref: '#/components/schemas/SalesChannelLocation'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
carts:
description: The associated carts.
type: array
nullable: true
x-expandable: carts
x-featureFlag: medusa_v2
items:
type: object
orders:
description: The associated orders.
type: array
nullable: true
x-expandable: orders
x-featureFlag: medusa_v2
items:
type: object
publishableKeys:
description: The associated publishable API keys.
type: array
nullable: true
x-expandable: publishableKeys
items:
type: object
SalesChannelLocation:
title: Sales Channel Stock Location
description: This represents the association between a sales channel and a stock locations.
type: object
required:
- created_at
- deleted_at
- id
- location_id
- sales_channel_id
- updated_at
properties:
id:
description: The Sales Channel Stock Location's ID
type: string
example: scloc_01G8X9A7ESKAJXG2H0E6F1MW7A
sales_channel_id:
description: The ID of the Sales Channel
type: string
example: sc_01G8X9A7ESKAJXG2H0E6F1MW7A
location_id:
description: The ID of the Location Stock.
type: string
sales_channel:
description: The details of the sales channel the location is associated with.
x-expandable: sales_channel
nullable: true
type: object
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
ShippingMethod:
title: Shipping Method
description: A Shipping Method represents a way in which an Order or Return can be shipped. Shipping Methods are created from a Shipping Option, but may contain additional details that can be necessary for the Fulfillment Provider to handle the shipment. If the shipping method is created for a return, it may be associated with a claim or a swap that the return is part of.
type: object
required:
- cart_id
- claim_order_id
- data
- id
- order_id
- price
- return_id
- shipping_option_id
- swap_id
properties:
id:
description: The shipping method's ID
type: string
example: sm_01F0YET7DR2E7CYVSDHM593QG2
shipping_option_id:
description: The ID of the Shipping Option that the Shipping Method is built from.
type: string
example: so_01G1G5V27GYX4QXNARRQCW1N8T
order_id:
description: The ID of the order that the shipping method is used in.
nullable: true
type: string
example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
order:
description: The details of the order that the shipping method is used in.
x-expandable: order
nullable: true
type: object
claim_order_id:
description: The ID of the claim that the shipping method is used in.
nullable: true
type: string
example: null
claim_order:
description: The details of the claim that the shipping method is used in.
x-expandable: claim_order
nullable: true
type: object
cart_id:
description: The ID of the cart that the shipping method is used in.
nullable: true
type: string
example: cart_01G8ZH853Y6TFXWPG5EYE81X63
cart:
description: The details of the cart that the shipping method is used in.
x-expandable: cart
nullable: true
type: object
swap_id:
description: The ID of the swap that the shipping method is used in.
nullable: true
type: string
example: null
swap:
description: The details of the swap that the shipping method is used in.
x-expandable: swap
nullable: true
type: object
return_id:
description: The ID of the return that the shipping method is used in.
nullable: true
type: string
example: null
return_order:
description: The details of the return that the shipping method is used in.
x-expandable: return_order
nullable: true
type: object
shipping_option:
description: The details of the shipping option the method was created from.
x-expandable: shipping_option
nullable: true
$ref: '#/components/schemas/ShippingOption'
tax_lines:
description: The details of the tax lines applied on the shipping method.
type: array
x-expandable: tax_lines
items:
$ref: '#/components/schemas/ShippingMethodTaxLine'
price:
description: The amount to charge for the Shipping Method. The currency of the price is defined by the Region that the Order that the Shipping Method belongs to is a part of.
type: integer
example: 200
data:
description: Additional data that the Fulfillment Provider needs to fulfill the shipment. This is used in combination with the Shipping Options data, and may contain information such as a drop point id.
type: object
example: {}
includes_tax:
description: Whether the shipping method price include tax
type: boolean
x-featureFlag: tax_inclusive_pricing
default: false
subtotal:
description: The subtotal of the shipping
type: integer
example: 8000
total:
description: The total amount of the shipping
type: integer
example: 8200
tax_total:
description: The total of tax
type: integer
example: 0
ShippingMethodTaxLine:
title: Shipping Method Tax Line
description: A Shipping Method Tax Line represents the taxes applied on a shipping method in a cart.
type: object
required:
- code
- created_at
- id
- shipping_method_id
- metadata
- name
- rate
- updated_at
properties:
id:
description: The line item tax line's ID
type: string
example: smtl_01G1G5V2DRX1SK6NQQ8VVX4HQ8
code:
description: A code to identify the tax type by
nullable: true
type: string
example: tax01
name:
description: A human friendly name for the tax
type: string
example: Tax Example
rate:
description: The numeric rate to charge tax by
type: number
example: 10
shipping_method_id:
description: The ID of the line item
type: string
example: sm_01F0YET7DR2E7CYVSDHM593QG2
shipping_method:
description: The details of the associated shipping method.
x-expandable: shipping_method
nullable: true
type: object
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
ShippingOption:
title: Shipping Option
description: A Shipping Option represents a way in which an Order or Return can be shipped. Shipping Options have an associated Fulfillment Provider that will be used when the fulfillment of an Order is initiated. Shipping Options themselves cannot be added to Carts, but serve as a template for Shipping Methods. This distinction makes it possible to customize individual Shipping Methods with additional information.
type: object
required:
- admin_only
- amount
- created_at
- data
- deleted_at
- id
- is_return
- metadata
- name
- price_type
- profile_id
- provider_id
- region_id
- updated_at
properties:
id:
description: The shipping option's ID
type: string
example: so_01G1G5V27GYX4QXNARRQCW1N8T
name:
description: The name given to the Shipping Option - this may be displayed to the Customer.
type: string
example: PostFake Standard
region_id:
description: The ID of the region this shipping option can be used in.
type: string
example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
region:
description: The details of the region this shipping option can be used in.
x-expandable: region
nullable: true
type: object
profile_id:
description: The ID of the Shipping Profile that the shipping option belongs to.
type: string
example: sp_01G1G5V239ENSZ5MV4JAR737BM
profile:
description: The details of the shipping profile that the shipping option belongs to.
x-expandable: profile
nullable: true
$ref: '#/components/schemas/ShippingProfile'
provider_id:
description: The ID of the fulfillment provider that will be used to later to process the shipping method created from this shipping option and its fulfillments.
type: string
example: manual
provider:
description: The details of the fulfillment provider that will be used to later to process the shipping method created from this shipping option and its fulfillments.
x-expandable: provider
nullable: true
$ref: '#/components/schemas/FulfillmentProvider'
price_type:
description: The type of pricing calculation that is used when creatin Shipping Methods from the Shipping Option. Can be `flat_rate` for fixed prices or `calculated` if the Fulfillment Provider can provide price calulations.
type: string
enum:
- flat_rate
- calculated
example: flat_rate
amount:
description: The amount to charge for shipping when the Shipping Option price type is `flat_rate`.
nullable: true
type: integer
example: 200
is_return:
description: Flag to indicate if the Shipping Option can be used for Return shipments.
type: boolean
default: false
admin_only:
description: Flag to indicate if the Shipping Option usage is restricted to admin users.
type: boolean
default: false
requirements:
description: The details of the requirements that must be satisfied for the Shipping Option to be available for usage in a Cart.
type: array
x-expandable: requirements
items:
$ref: '#/components/schemas/ShippingOptionRequirement'
data:
description: The data needed for the Fulfillment Provider to identify the Shipping Option.
type: object
example: {}
includes_tax:
description: Whether the shipping option price include tax
type: boolean
x-featureFlag: tax_inclusive_pricing
default: false
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
ShippingOptionRequirement:
title: Shipping Option Requirement
description: A shipping option requirement defines conditions that a Cart must satisfy for the Shipping Option to be available for usage in the Cart.
type: object
required:
- amount
- deleted_at
- id
- shipping_option_id
- type
properties:
id:
description: The shipping option requirement's ID
type: string
example: sor_01G1G5V29AB4CTNDRFSRWSRKWD
shipping_option_id:
description: The ID of the shipping option that the requirements belong to.
type: string
example: so_01G1G5V27GYX4QXNARRQCW1N8T
shipping_option:
description: The details of the shipping option that the requirements belong to.
x-expandable: shipping_option
nullable: true
type: object
type:
description: The type of the requirement, this defines how the value will be compared to the Cart's total. `min_subtotal` requirements define the minimum subtotal that is needed for the Shipping Option to be available, while the `max_subtotal` defines the maximum subtotal that the Cart can have for the Shipping Option to be available.
type: string
enum:
- min_subtotal
- max_subtotal
example: min_subtotal
amount:
description: The amount to compare the Cart subtotal to.
type: integer
example: 100
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
ShippingProfile:
title: Shipping Profile
description: A Shipping Profile has a set of defined Shipping Options that can be used to fulfill a given set of Products. For example, gift cards are shipped differently than physical products, so a shipping profile with the type `gift_card` groups together the shipping options that can only be used for gift cards.
type: object
required:
- created_at
- deleted_at
- id
- metadata
- name
- type
- updated_at
properties:
id:
description: The shipping profile's ID
type: string
example: sp_01G1G5V239ENSZ5MV4JAR737BM
name:
description: The name given to the Shipping profile - this may be displayed to the Customer.
type: string
example: Default Shipping Profile
type:
description: The type of the Shipping Profile, may be `default`, `gift_card` or `custom`.
type: string
enum:
- default
- gift_card
- custom
example: default
products:
description: The details of the products that the Shipping Profile defines Shipping Options for. Available if the relation `products` is expanded.
type: array
x-expandable: products
items:
type: object
shipping_options:
description: The details of the shipping options that can be used to create shipping methods for the Products in the Shipping Profile.
type: array
x-expandable: shipping_options
items:
type: object
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
ShippingTaxRate:
title: Shipping Tax Rate
description: This represents the tax rates applied on a shipping option.
type: object
required:
- created_at
- metadata
- rate_id
- shipping_option_id
- updated_at
properties:
shipping_option_id:
description: The ID of the shipping option.
type: string
example: so_01G1G5V27GYX4QXNARRQCW1N8T
shipping_option:
description: The details of the shipping option.
x-expandable: shipping_option
nullable: true
$ref: '#/components/schemas/ShippingOption'
rate_id:
description: The ID of the associated tax rate.
type: string
example: txr_01G8XDBAWKBHHJRKH0AV02KXBR
tax_rate:
description: The details of the associated tax rate.
x-expandable: tax_rate
nullable: true
$ref: '#/components/schemas/TaxRate'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
StagedJob:
title: Staged Job
description: A staged job resource
type: object
required:
- data
- event_name
- id
- options
properties:
id:
description: The staged job's ID
type: string
example: job_01F0YET7BZTARY9MKN1SJ7AAXF
event_name:
description: The name of the event
type: string
example: order.placed
data:
description: Data necessary for the job
type: object
example: {}
option:
description: The staged job's option
type: object
example: {}
StockLocationAddressDTO:
title: Stock Location Address
description: Represents a Stock Location Address
type: object
required:
- address_1
- country_code
- created_at
- updated_at
properties:
id:
type: string
description: The stock location address' ID
example: laddr_51G4ZW853Y6TFXWPG5ENJ81X42
address_1:
type: string
description: Stock location address
example: 35, Jhon Doe Ave
address_2:
type: string
description: Stock location address' complement
example: apartment 4432
company:
type: string
description: Stock location company' name
example: Medusa
city:
type: string
description: Stock location address' city
example: Mexico city
country_code:
type: string
description: Stock location address' country
example: MX
phone:
type: string
description: Stock location address' phone number
example: +1 555 61646
postal_code:
type: string
description: Stock location address' postal code
example: HD3-1G8
province:
type: string
description: Stock location address' province
example: Sinaloa
created_at:
type: string
description: The date with timezone at which the resource was created.
format: date-time
updated_at:
type: string
description: The date with timezone at which the resource was updated.
format: date-time
deleted_at:
type: string
description: The date with timezone at which the resource was deleted.
format: date-time
metadata:
type: object
description: An optional key-value map with additional details
example:
car: white
StockLocationAddressInput:
title: Stock Location Address Input
description: Represents a Stock Location Address Input
type: object
required:
- address_1
- country_code
properties:
address_1:
type: string
description: Stock location address
example: 35, Jhon Doe Ave
address_2:
type: string
description: Stock location address' complement
example: apartment 4432
city:
type: string
description: Stock location address' city
example: Mexico city
country_code:
type: string
description: Stock location address' country
example: MX
phone:
type: string
description: Stock location address' phone number
example: +1 555 61646
postal_code:
type: string
description: Stock location address' postal code
example: HD3-1G8
province:
type: string
description: Stock location address' province
example: Sinaloa
metadata:
type: object
description: An optional key-value map with additional details
example:
car: white
StockLocationDTO:
title: Stock Location
description: Represents a Stock Location
type: object
required:
- id
- name
- address_id
- created_at
- updated_at
properties:
id:
type: string
description: The stock location's ID
example: sloc_51G4ZW853Y6TFXWPG5ENJ81X42
address_id:
type: string
description: Stock location address' ID
example: laddr_05B2ZE853Y6FTXWPW85NJ81A44
name:
type: string
description: The name of the stock location
example: Main Warehouse
address:
description: The Address of the Stock Location
allOf:
- $ref: '#/components/schemas/StockLocationAddressDTO'
- type: object
metadata:
type: object
description: An optional key-value map with additional details
example:
car: white
created_at:
type: string
description: The date with timezone at which the resource was created.
format: date-time
updated_at:
type: string
description: The date with timezone at which the resource was updated.
format: date-time
deleted_at:
type: string
description: The date with timezone at which the resource was deleted.
format: date-time
StockLocationExpandedDTO:
allOf:
- $ref: '#/components/schemas/StockLocationDTO'
- type: object
properties:
sales_channels:
description: The associated sales channels.
$ref: '#/components/schemas/SalesChannel'
Store:
title: Store
description: A store holds the main settings of the commerce shop. By default, only one store is created and used within the Medusa backend. It holds settings related to the name of the store, available currencies, and more.
type: object
required:
- created_at
- default_currency_code
- default_location_id
- id
- invite_link_template
- metadata
- name
- payment_link_template
- swap_link_template
- updated_at
properties:
id:
description: The store's ID
type: string
example: store_01G1G5V21KADXNGH29BJMAJ4B4
name:
description: The name of the Store - this may be displayed to the Customer.
type: string
example: Medusa Store
default: Medusa Store
default_currency_code:
description: The three character currency code that is the default of the store.
type: string
example: usd
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
description: See a list of codes.
default_currency:
description: The details of the store's default currency.
x-expandable: default_currency
default: usd
nullable: true
$ref: '#/components/schemas/Currency'
currencies:
description: The details of the enabled currencies in the store.
type: array
x-expandable: currencies
items:
$ref: '#/components/schemas/Currency'
swap_link_template:
description: A template to generate Swap links from. Use {{cart_id}} to include the Swap's `cart_id` in the link.
nullable: true
type: string
example: null
payment_link_template:
description: A template to generate Payment links from. Use {{cart_id}} to include the payment's `cart_id` in the link.
nullable: true
type: string
example: null
invite_link_template:
description: A template to generate Invite links from
nullable: true
type: string
example: null
default_location_id:
description: The location ID the store is associated with.
nullable: true
type: string
example: null
default_sales_channel_id:
description: The ID of the store's default sales channel.
nullable: true
type: string
example: null
default_sales_channel:
description: The details of the store's default sales channel.
x-expandable: default_sales_channel
nullable: true
$ref: '#/components/schemas/SalesChannel'
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
StoreAuthRes:
type: object
description: The customer's details.
x-expanded-relations:
field: customer
relations:
- orders
- orders.items
- shipping_addresses
required:
- customer
properties:
customer:
description: Customer's details.
$ref: '#/components/schemas/Customer'
StoreBearerAuthRes:
type: object
description: The access token details.
properties:
access_token:
description: Access token that can be used to send authenticated requests.
type: string
StoreCartShippingOptionsListRes:
type: object
x-expanded-relations:
field: shipping_options
implicit:
- profile
- requirements
required:
- shipping_options
properties:
shipping_options:
type: array
description: An array of shipping options details.
items:
$ref: '#/components/schemas/PricedShippingOption'
StoreCartsRes:
type: object
description: The cart's details.
x-expanded-relations:
field: cart
relations:
- billing_address
- discounts
- discounts.rule
- gift_cards
- items
- items.adjustments
- items.variant
- payment
- payment_sessions
- region
- region.countries
- region.payment_providers
- shipping_address
- shipping_methods
eager:
- region.fulfillment_providers
- region.payment_providers
- shipping_methods.shipping_option
implicit:
- items
- items.variant
- items.variant.product
- items.variant.product.profiles
- items.tax_lines
- items.adjustments
- gift_cards
- discounts
- discounts.rule
- shipping_methods
- shipping_methods.tax_lines
- shipping_address
- region
- region.tax_rates
totals:
- discount_total
- gift_card_tax_total
- gift_card_total
- item_tax_total
- refundable_amount
- refunded_total
- shipping_tax_total
- shipping_total
- subtotal
- tax_total
- total
- items.discount_total
- items.gift_card_total
- items.original_tax_total
- items.original_total
- items.refundable
- items.subtotal
- items.tax_total
- items.total
required:
- cart
properties:
cart:
description: Cart details.
$ref: '#/components/schemas/Cart'
StoreCollectionsListRes:
type: object
description: The list of product collections with pagination fields.
required:
- collections
- count
- offset
- limit
properties:
collections:
type: array
description: An array of product collections details
items:
$ref: '#/components/schemas/ProductCollection'
count:
type: integer
description: The total number of items available
offset:
type: integer
description: The number of product collections skipped when retrieving the product collections.
limit:
type: integer
description: The number of items per page
StoreCollectionsRes:
type: object
description: The details of the product collection.
required:
- collection
properties:
collection:
description: Product collection details.
$ref: '#/components/schemas/ProductCollection'
StoreCompleteCartRes:
type: object
description: If the cart is completed successfully, this will have the created order or the swap's details, based on the cart's type. Otherwise, it'll be the cart's details.
required:
- type
- data
properties:
type:
type: string
description: The type of the data property. If the cart completion fails, type will be `cart` and the data object will be the cart's details. If the cart completion is successful and the cart is used for checkout, type will be `order` and the data object will be the order's details. If the cart completion is successful and the cart is used for swap creation, type will be `swap` and the data object will be the swap's details.
enum:
- order
- cart
- swap
data:
type: object
description: The data of the result object. Its type depends on the type field.
oneOf:
- type: object
allOf:
- description: Cart was successfully authorized and order was placed successfully.
- $ref: '#/components/schemas/Order'
- type: object
allOf:
- description: Cart was successfully authorized but requires further actions.
- $ref: '#/components/schemas/Cart'
- type: object
allOf:
- description: Cart was used for a swap and it has been completed successfully.
- $ref: '#/components/schemas/Swap'
StoreCustomersListOrdersRes:
type: object
description: The list of the customer's orders with pagination fields.
x-expanded-relations:
field: orders
relations:
- customer
- discounts
- discounts.rule
- fulfillments
- fulfillments.tracking_links
- items
- items.variant
- payments
- region
- shipping_address
- shipping_methods
eager:
- region.fulfillment_providers
- region.payment_providers
- shipping_methods.shipping_option
implicit:
- claims
- claims.additional_items
- claims.additional_items.adjustments
- claims.additional_items.refundable
- claims.additional_items.tax_lines
- customer
- discounts
- discounts.rule
- gift_card_transactions
- gift_card_transactions.gift_card
- gift_cards
- items
- items.adjustments
- items.refundable
- items.tax_lines
- items.variant
- items.variant.product
- items.variant.product.profiles
- refunds
- region
- shipping_address
- shipping_methods
- shipping_methods.tax_lines
- swaps
- swaps.additional_items
- swaps.additional_items.adjustments
- swaps.additional_items.refundable
- swaps.additional_items.tax_lines
totals:
- discount_total
- gift_card_tax_total
- gift_card_total
- paid_total
- refundable_amount
- refunded_total
- shipping_total
- subtotal
- tax_total
- total
- claims.additional_items.discount_total
- claims.additional_items.gift_card_total
- claims.additional_items.original_tax_total
- claims.additional_items.original_total
- claims.additional_items.refundable
- claims.additional_items.subtotal
- claims.additional_items.tax_total
- claims.additional_items.total
- items.discount_total
- items.gift_card_total
- items.original_tax_total
- items.original_total
- items.refundable
- items.subtotal
- items.tax_total
- items.total
- swaps.additional_items.discount_total
- swaps.additional_items.gift_card_total
- swaps.additional_items.original_tax_total
- swaps.additional_items.original_total
- swaps.additional_items.refundable
- swaps.additional_items.subtotal
- swaps.additional_items.tax_total
- swaps.additional_items.total
required:
- orders
- count
- offset
- limit
properties:
orders:
type: array
description: An array of orders details.
items:
$ref: '#/components/schemas/Order'
count:
description: The total number of items available
type: integer
offset:
description: The number of orders skipped when retrieving the orders.
type: integer
limit:
description: The number of items per page
type: integer
StoreCustomersListPaymentMethodsRes:
type: object
description: The payment method's details.
required:
- payment_methods
properties:
payment_methods:
type: array
description: The details of the saved payment methods.
items:
type: object
required:
- provider_id
- data
properties:
provider_id:
description: The ID of the Payment Provider where the payment method is saved.
type: string
data:
description: The data needed for the Payment Provider to use the saved payment method.
type: object
StoreCustomersRes:
type: object
description: The customer's details.
x-expanded-relations:
field: customer
relations:
- billing_address
- shipping_addresses
required:
- customer
properties:
customer:
description: Customer details.
$ref: '#/components/schemas/Customer'
StoreCustomersResetPasswordRes:
type: object
required:
- customer
properties:
customer:
description: Customer details.
$ref: '#/components/schemas/Customer'
StoreGetAuthEmailRes:
type: object
description: Details on whether the email exists.
required:
- exists
properties:
exists:
description: Whether email exists or not.
type: boolean
StoreGetProductCategoriesCategoryRes:
type: object
description: The product category's details.
x-expanded-relations:
field: product_category
relations:
- category_children
- parent_category
required:
- product_category
properties:
product_category:
description: Product category details.
$ref: '#/components/schemas/ProductCategory'
StoreGetProductCategoriesRes:
type: object
description: The list of product categories with pagination fields.
x-expanded-relations:
field: product_categories
relations:
- category_children
- parent_category
required:
- product_categories
- count
- offset
- limit
properties:
product_categories:
type: array
description: An array of product categories details.
items:
$ref: '#/components/schemas/ProductCategory'
count:
type: integer
description: The total number of items available
offset:
type: integer
description: The number of product categories skipped when retrieving the product categories.
limit:
type: integer
description: The number of items per page
StoreGiftCardsRes:
description: The gift card's details.
type: object
required:
- gift_card
properties:
gift_card:
description: Gift card details.
$ref: '#/components/schemas/GiftCard'
StoreOrderEditsRes:
type: object
description: The order edit's details.
x-expanded-relations:
field: order_edit
relations:
- changes
- changes.line_item
- changes.line_item.variant
- changes.original_line_item
- changes.original_line_item.variant
- items
- items.adjustments
- items.tax_lines
- items.variant
- payment_collection
implicit:
- items
- items.tax_lines
- items.adjustments
- items.variant
totals:
- difference_due
- discount_total
- gift_card_tax_total
- gift_card_total
- shipping_total
- subtotal
- tax_total
- total
- items.discount_total
- items.gift_card_total
- items.original_tax_total
- items.original_total
- items.refundable
- items.subtotal
- items.tax_total
- items.total
required:
- order_edit
properties:
order_edit:
description: Order edit details.
$ref: '#/components/schemas/OrderEdit'
StoreOrdersRes:
type: object
description: The order's details.
required:
- order
x-expanded-relations:
field: order
relations:
- customer
- discounts
- discounts.rule
- fulfillments
- fulfillments.tracking_links
- items
- items.variant
- payments
- region
- shipping_address
- shipping_methods
eager:
- fulfillments.items
- region.fulfillment_providers
- region.payment_providers
- shipping_methods.shipping_option
implicit:
- claims
- claims.additional_items
- claims.additional_items.adjustments
- claims.additional_items.refundable
- claims.additional_items.tax_lines
- discounts
- discounts.rule
- gift_card_transactions
- gift_card_transactions.gift_card
- gift_cards
- items
- items.adjustments
- items.refundable
- items.tax_lines
- items.variant
- items.variant.product
- items.variant.product.profiles
- refunds
- region
- shipping_methods
- shipping_methods.tax_lines
- swaps
- swaps.additional_items
- swaps.additional_items.adjustments
- swaps.additional_items.refundable
- swaps.additional_items.tax_lines
totals:
- discount_total
- gift_card_tax_total
- gift_card_total
- paid_total
- refundable_amount
- refunded_total
- shipping_total
- subtotal
- tax_total
- total
- claims.additional_items.discount_total
- claims.additional_items.gift_card_total
- claims.additional_items.original_tax_total
- claims.additional_items.original_total
- claims.additional_items.refundable
- claims.additional_items.subtotal
- claims.additional_items.tax_total
- claims.additional_items.total
- items.discount_total
- items.gift_card_total
- items.original_tax_total
- items.original_total
- items.refundable
- items.subtotal
- items.tax_total
- items.total
- swaps.additional_items.discount_total
- swaps.additional_items.gift_card_total
- swaps.additional_items.original_tax_total
- swaps.additional_items.original_total
- swaps.additional_items.refundable
- swaps.additional_items.subtotal
- swaps.additional_items.tax_total
- swaps.additional_items.total
properties:
order:
description: Order details.
$ref: '#/components/schemas/Order'
StorePaymentCollectionSessionsReq:
type: object
description: The details of the payment session to manage.
required:
- provider_id
properties:
provider_id:
type: string
description: The ID of the Payment Provider.
StorePaymentCollectionsRes:
type: object
description: The payment collection's details.
x-expanded-relations:
field: payment_collection
relations:
- payment_sessions
- region
eager:
- region.fulfillment_providers
- region.payment_providers
required:
- payment_collection
properties:
payment_collection:
description: Payment collection's details.
$ref: '#/components/schemas/PaymentCollection'
StorePaymentCollectionsSessionRes:
type: object
description: The details of the payment session.
required:
- payment_session
properties:
payment_session:
description: Payment session's details.
$ref: '#/components/schemas/PaymentSession'
StorePostAuthReq:
type: object
required:
- email
- password
properties:
email:
type: string
description: The Customer's email.
password:
type: string
description: The Customer's password.
StorePostCartReq:
type: object
description: The details of the cart to be created.
properties:
region_id:
type: string
description: The ID of the Region to create the Cart in. Setting the cart's region can affect the pricing of the items in the cart as well as the used currency. If this parameter is not provided, the first region in the store is used by default.
sales_channel_id:
type: string
description: The ID of the Sales channel to create the Cart in. The cart's sales channel affects which products can be added to the cart. If a product does not exist in the cart's sales channel, it cannot be added to the cart. If you add a publishable API key in the header of this request and specify a sales channel ID, the specified sales channel must be within the scope of the publishable API key's resources. If you add a publishable API key in the header of this request, you don't specify a sales channel ID, and the publishable API key is associated with one sales channel, that sales channel will be attached to the cart. If no sales channel is passed and no publishable API key header is passed or the publishable API key isn't associated with any sales channel, the cart will not be associated with any sales channel.
country_code:
type: string
description: The two character ISO country code to create the Cart in. Setting this parameter will set the country code of the shipping address.
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
description: See a list of codes.
items:
description: An array of product variants to generate line items from.
type: array
items:
type: object
required:
- variant_id
- quantity
properties:
variant_id:
description: The ID of the Product Variant.
type: string
quantity:
description: The quantity to add into the cart.
type: integer
context:
description: An object to provide context to the Cart. The `context` field is automatically populated with `ip` and `user_agent`
type: object
example:
ip: '::1'
user_agent: Chrome
StorePostCartsCartLineItemsItemReq:
type: object
description: The details to update of the line item.
required:
- quantity
properties:
quantity:
type: number
description: The quantity of the line item in the cart.
metadata:
type: object
description: An optional key-value map with additional details about the Line Item. If omitted, the metadata will remain unchanged."
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
StorePostCartsCartLineItemsReq:
type: object
description: The details of the line item to create.
required:
- variant_id
- quantity
properties:
variant_id:
type: string
description: The id of the Product Variant to generate the Line Item from.
quantity:
type: number
description: The quantity of the Product Variant to add to the Line Item.
metadata:
type: object
description: An optional key-value map with additional details about the Line Item.
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
StorePostCartsCartPaymentSessionReq:
type: object
description: The details of the payment session to set.
required:
- provider_id
properties:
provider_id:
type: string
description: The ID of the Payment Provider.
StorePostCartsCartPaymentSessionUpdateReq:
type: object
required:
- data
properties:
data:
type: object
description: The data to update the payment session with.
StorePostCartsCartReq:
type: object
description: The details to update of the cart.
properties:
region_id:
type: string
description: The ID of the Region to create the Cart in. Setting the cart's region can affect the pricing of the items in the cart as well as the used currency.
country_code:
type: string
description: The 2 character ISO country code to create the Cart in. Setting this parameter will set the country code of the shipping address.
externalDocs:
url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
description: See a list of codes.
email:
type: string
description: An email to be used on the Cart.
format: email
sales_channel_id:
type: string
description: The ID of the Sales channel to create the Cart in. The cart's sales channel affects which products can be added to the cart. If a product does not exist in the cart's sales channel, it cannot be added to the cart. If you add a publishable API key in the header of this request and specify a sales channel ID, the specified sales channel must be within the scope of the publishable API key's resources.
billing_address:
description: The Address to be used for billing purposes.
anyOf:
- $ref: '#/components/schemas/AddressPayload'
description: A full billing address object.
- type: string
description: The billing address ID
shipping_address:
description: The Address to be used for shipping purposes.
anyOf:
- $ref: '#/components/schemas/AddressPayload'
description: A full shipping address object.
- type: string
description: The shipping address ID
gift_cards:
description: An array of Gift Card codes to add to the Cart.
type: array
items:
type: object
required:
- code
properties:
code:
description: The code of a gift card.
type: string
discounts:
description: An array of Discount codes to add to the Cart.
type: array
items:
type: object
required:
- code
properties:
code:
description: The code of the discount.
type: string
customer_id:
description: The ID of the Customer to associate the Cart with.
type: string
context:
description: An object to provide context to the Cart. The `context` field is automatically populated with `ip` and `user_agent`
type: object
example:
ip: '::1'
user_agent: Chrome
StorePostCartsCartShippingMethodReq:
type: object
description: The details of the shipping method to add to the cart.
required:
- option_id
properties:
option_id:
type: string
description: ID of the shipping option to create the method from.
data:
type: object
description: Used to hold any data that the shipping method may need to process the fulfillment of the order. This depends on the fulfillment provider you're using.
StorePostCustomersCustomerAcceptClaimReq:
type: object
description: The details necessary to grant order access.
required:
- token
properties:
token:
description: The claim token generated by previous request to the Claim Order API Route.
type: string
StorePostCustomersCustomerAddressesAddressReq:
anyOf:
- $ref: '#/components/schemas/AddressPayload'
StorePostCustomersCustomerAddressesReq:
type: object
required:
- address
properties:
address:
description: The Address to add to the Customer's saved addresses.
$ref: '#/components/schemas/AddressCreatePayload'
StorePostCustomersCustomerOrderClaimReq:
type: object
description: The details of the orders to claim.
required:
- order_ids
properties:
order_ids:
description: The ID of the orders to claim
type: array
items:
type: string
StorePostCustomersCustomerPasswordTokenReq:
type: object
required:
- email
properties:
email:
description: The customer's email.
type: string
format: email
StorePostCustomersCustomerReq:
type: object
description: The details to update of the customer.
properties:
first_name:
description: The customer's first name.
type: string
last_name:
description: The customer's last name.
type: string
billing_address:
description: The address to be used for billing purposes.
anyOf:
- $ref: '#/components/schemas/AddressPayload'
description: The full billing address object
- type: string
description: The ID of an existing billing address
password:
description: The customer's password.
type: string
phone:
description: The customer's phone number.
type: string
email:
description: The customer's email.
type: string
metadata:
description: Additional custom data about the customer.
type: object
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
StorePostCustomersReq:
type: object
description: The details of the customer to create.
required:
- first_name
- last_name
- email
- password
properties:
first_name:
description: The customer's first name.
type: string
last_name:
description: The customer's last name.
type: string
email:
description: The customer's email.
type: string
format: email
password:
description: The customer's password.
type: string
format: password
phone:
description: The customer's phone number.
type: string
StorePostCustomersResetPasswordReq:
type: object
required:
- email
- password
- token
properties:
email:
description: The customer's email.
type: string
format: email
password:
description: The customer's password.
type: string
format: password
token:
description: The reset password token
type: string
StorePostOrderEditsOrderEditDecline:
type: object
description: The details of the order edit's decline.
properties:
declined_reason:
type: string
description: The reason for declining the Order Edit.
StorePostPaymentCollectionsBatchSessionsAuthorizeReq:
type: object
description: The details of the payment sessions to authorize.
required:
- session_ids
properties:
session_ids:
description: List of Payment Session IDs to authorize.
type: array
items:
type: string
StorePostPaymentCollectionsBatchSessionsReq:
type: object
description: The details of the payment sessions to manage.
required:
- sessions
properties:
sessions:
description: Payment sessions related to the Payment Collection. Existing sessions that are not added in this array will be deleted.
type: array
items:
type: object
required:
- provider_id
- amount
properties:
provider_id:
type: string
description: The ID of the Payment Provider.
amount:
type: integer
description: The payment amount
session_id:
type: string
description: The ID of the Payment Session to be updated. If no ID is provided, a new payment session is created.
StorePostReturnsReq:
type: object
description: The details of the return to create.
required:
- order_id
- items
properties:
order_id:
type: string
description: The ID of the Order to create the return for.
items:
description: The items to include in the return.
type: array
items:
type: object
required:
- item_id
- quantity
properties:
item_id:
description: The ID of the line item to return.
type: string
quantity:
description: The quantity to return.
type: integer
reason_id:
description: The ID of the return reason. Return reasons can be retrieved from the List Return Reasons API Route.
type: string
note:
description: A note to add to the item returned.
type: string
return_shipping:
description: The return shipping method used to return the items. If provided, a fulfillment is automatically created for the return.
type: object
required:
- option_id
properties:
option_id:
type: string
description: The ID of the Shipping Option to create the Shipping Method from.
StorePostSearchReq:
type: object
properties:
q:
type: string
description: The search query.
offset:
type: number
description: The number of products to skip when retrieving the products.
limit:
type: number
description: Limit the number of products returned.
filter:
description: Pass filters based on the search service.
StorePostSearchRes:
description: The list of search results.
allOf:
- type: object
required:
- hits
properties:
hits:
description: Array of search results. The format of the items depends on the search engine installed on the Medusa backend.
type: array
- type: object
StorePostSwapsReq:
type: object
description: The details of the swap to create.
required:
- order_id
- return_items
- additional_items
properties:
order_id:
type: string
description: The ID of the Order to create the Swap for.
return_items:
description: The items to include in the Return.
type: array
items:
type: object
required:
- item_id
- quantity
properties:
item_id:
description: The ID of the order's line item to return.
type: string
quantity:
description: The quantity to return.
type: integer
reason_id:
description: The ID of the reason of this return. Return reasons can be retrieved from the List Return Reasons API Route.
type: string
note:
description: The note to add to the item being swapped.
type: string
return_shipping_option:
type: string
description: The ID of the Shipping Option to create the Shipping Method from.
additional_items:
description: The items to exchange the returned items with.
type: array
items:
type: object
required:
- variant_id
- quantity
properties:
variant_id:
description: The ID of the Product Variant.
type: string
quantity:
description: The quantity of the variant.
type: integer
StoreProductTagsListRes:
type: object
description: The list of product tags with pagination fields.
required:
- product_tags
- count
- offset
- limit
properties:
product_tags:
type: array
description: An array of product tags details.
items:
$ref: '#/components/schemas/ProductTag'
count:
type: integer
description: The total number of items available
offset:
type: integer
description: The number of product tags skipped when retrieving the product tags.
limit:
type: integer
description: The number of items per page
StoreProductTypesListRes:
type: object
required:
- product_types
- count
- offset
- limit
properties:
product_types:
type: array
description: An array of product types details.
items:
$ref: '#/components/schemas/ProductType'
count:
type: integer
description: The total number of items available
offset:
type: integer
description: The number of product types skipped when retrieving the product types.
limit:
type: integer
description: The number of items per page
StoreProductsListRes:
type: object
description: The list of products with pagination fields.
x-expanded-relations:
field: products
relations:
- collection
- images
- options
- options.values
- tags
- type
- variants
- variants.options
- variants.prices
totals:
- variants.purchasable
required:
- products
- count
- offset
- limit
properties:
products:
type: array
description: An array of products details.
items:
$ref: '#/components/schemas/PricedProduct'
count:
type: integer
description: The total number of items available
offset:
type: integer
description: The number of products skipped when retrieving the products.
limit:
type: integer
description: The number of items per page
StoreProductsRes:
type: object
x-expanded-relations:
field: product
relations:
- collection
- images
- options
- options.values
- tags
- type
- variants
- variants.options
- variants.prices
totals:
- variants.purchasable
required:
- product
properties:
product:
description: Product details.
$ref: '#/components/schemas/PricedProduct'
StoreRegionsListRes:
type: object
description: The list of regions with pagination fields.
x-expanded-relations:
field: regions
relations:
- countries
- payment_providers
- fulfillment_providers
eager:
- payment_providers
- fulfillment_providers
required:
- regions
properties:
regions:
type: array
description: An array of regions details.
items:
$ref: '#/components/schemas/Region'
count:
type: integer
description: The total number of items available
offset:
type: integer
description: The number of regions skipped when retrieving the regions.
limit:
type: integer
description: The number of items per page
StoreRegionsRes:
type: object
description: The region's details.
x-expanded-relations:
field: region
relations:
- countries
- payment_providers
- fulfillment_providers
eager:
- payment_providers
- fulfillment_providers
required:
- region
properties:
region:
description: Region details.
$ref: '#/components/schemas/Region'
StoreReturnReasonsListRes:
type: object
description: The list of return reasons.
x-expanded-relations:
field: return_reasons
relations:
- parent_return_reason
- return_reason_children
required:
- return_reasons
properties:
return_reasons:
type: array
description: An array of return reasons details.
items:
$ref: '#/components/schemas/ReturnReason'
StoreReturnReasonsRes:
type: object
description: The return reason's details.
x-expanded-relations:
field: return_reason
relations:
- parent_return_reason
- return_reason_children
required:
- return_reason
properties:
return_reason:
description: Return reason details.
$ref: '#/components/schemas/ReturnReason'
StoreReturnsRes:
type: object
description: The return's details.
x-expanded-relations:
field: return
relations:
- items
- items.reason
eager:
- items
required:
- return
properties:
return:
description: Return details.
$ref: '#/components/schemas/Return'
StoreShippingOptionsListRes:
type: object
description: The list of shipping options.
x-expanded-relations:
field: shipping_options
relations:
- requirements
required:
- shipping_options
properties:
shipping_options:
type: array
description: An array of shipping options details.
items:
$ref: '#/components/schemas/PricedShippingOption'
StoreSwapsRes:
type: object
description: The swap's details.
x-expanded-relations:
field: swap
relations:
- additional_items
- additional_items.variant
- cart
- fulfillments
- order
- payment
- return_order
- return_order.shipping_method
- shipping_address
- shipping_methods
eager:
- fulfillments.items
required:
- swap
properties:
swap:
description: Swap details.
$ref: '#/components/schemas/Swap'
StoreVariantsListRes:
type: object
description: The list of product variants.
x-expanded-relations:
field: variants
relations:
- prices
- options
- product
totals:
- purchasable
required:
- variants
properties:
variants:
type: array
description: An array of product variant descriptions.
items:
$ref: '#/components/schemas/PricedVariant'
StoreVariantsRes:
type: object
description: The product variant's details.
x-expanded-relations:
field: variant
relations:
- prices
- options
- product
totals:
- purchasable
required:
- variant
properties:
variant:
description: Product variant description.
$ref: '#/components/schemas/PricedVariant'
Swap:
title: Swap
description: A swap can be created when a Customer wishes to exchange Products that they have purchased with different Products. It consists of a Return of previously purchased Products and a Fulfillment of new Products. It also includes information on any additional payment or refund required based on the difference between the exchanged products.
type: object
required:
- allow_backorder
- canceled_at
- cart_id
- confirmed_at
- created_at
- deleted_at
- difference_due
- fulfillment_status
- id
- idempotency_key
- metadata
- no_notification
- order_id
- payment_status
- shipping_address_id
- updated_at
properties:
id:
description: The swap's ID
type: string
example: swap_01F0YET86Y9G92D3YDR9Y6V676
fulfillment_status:
description: The status of the Fulfillment of the Swap.
type: string
enum:
- not_fulfilled
- fulfilled
- shipped
- partially_shipped
- canceled
- requires_action
example: not_fulfilled
payment_status:
description: The status of the Payment of the Swap. The payment may either refer to the refund of an amount or the authorization of a new amount.
type: string
enum:
- not_paid
- awaiting
- captured
- confirmed
- canceled
- difference_refunded
- partially_refunded
- refunded
- requires_action
example: not_paid
order_id:
description: The ID of the order that the swap belongs to.
type: string
example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
order:
description: The details of the order that the swap belongs to.
x-expandable: order
nullable: true
type: object
additional_items:
description: The details of the new products to send to the customer, represented as line items.
type: array
x-expandable: additional_items
items:
$ref: '#/components/schemas/LineItem'
return_order:
description: The details of the return that belongs to the swap, which holds the details on the items being returned.
x-expandable: return_order
nullable: true
type: object
fulfillments:
description: The details of the fulfillments that are used to send the new items to the customer.
x-expandable: fulfillments
type: array
items:
type: object
payment:
description: The details of the additional payment authorized by the customer when `difference_due` is positive.
x-expandable: payment
nullable: true
type: object
difference_due:
description: The difference amount between the order’s original total and the new total imposed by the swap. If its value is negative, a refund must be issues to the customer. If it's positive, additional payment must be authorized by the customer. Otherwise, no payment processing is required.
nullable: true
type: integer
example: 0
shipping_address_id:
description: The Address to send the new Line Items to - in most cases this will be the same as the shipping address on the Order.
nullable: true
type: string
example: addr_01G8ZH853YPY9B94857DY91YGW
shipping_address:
description: The details of the shipping address that the new items should be sent to.
x-expandable: shipping_address
nullable: true
$ref: '#/components/schemas/Address'
shipping_methods:
description: The details of the shipping methods used to fulfill the additional items purchased.
type: array
x-expandable: shipping_methods
items:
$ref: '#/components/schemas/ShippingMethod'
cart_id:
description: The ID of the cart that the customer uses to complete the swap.
nullable: true
type: string
example: cart_01G8ZH853Y6TFXWPG5EYE81X63
cart:
description: The details of the cart that the customer uses to complete the swap.
x-expandable: cart
nullable: true
type: object
confirmed_at:
description: The date with timezone at which the Swap was confirmed by the Customer.
nullable: true
type: string
format: date-time
canceled_at:
description: The date with timezone at which the Swap was canceled.
nullable: true
type: string
format: date-time
no_notification:
description: If set to true, no notification will be sent related to this swap
nullable: true
type: boolean
example: false
allow_backorder:
description: If true, swaps can be completed with items out of stock
type: boolean
default: false
idempotency_key:
description: Randomly generated key used to continue the completion of the swap in case of failure.
nullable: true
type: string
externalDocs:
url: https://docs.medusajs.com/development/idempotency-key/overview.md
description: Learn more how to use the idempotency key.
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
TaxLine:
title: Tax Line
description: A tax line represents the taxes amount applied to a line item.
type: object
required:
- code
- created_at
- id
- metadata
- name
- rate
- updated_at
properties:
id:
description: The tax line's ID
type: string
example: tl_01G1G5V2DRX1SK6NQQ8VVX4HQ8
code:
description: A code to identify the tax type by
nullable: true
type: string
example: tax01
name:
description: A human friendly name for the tax
type: string
example: Tax Example
rate:
description: The numeric rate to charge tax by
type: number
example: 10
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
TaxProvider:
title: Tax Provider
description: A tax provider represents a tax service installed in the Medusa backend, either through a plugin or backend customizations. It holds the tax service's installation status.
type: object
required:
- id
- is_installed
properties:
id:
description: The ID of the tax provider as given by the tax service.
type: string
example: manual
is_installed:
description: Whether the tax service is installed in the current version. If a tax service is no longer installed, the `is_installed` attribute is set to `false`.
type: boolean
default: true
TaxRate:
title: Tax Rate
description: A Tax Rate can be used to define a custom rate to charge on specified products, product types, and shipping options within a given region.
type: object
required:
- code
- created_at
- id
- metadata
- name
- rate
- region_id
- updated_at
properties:
id:
description: The tax rate's ID
type: string
example: txr_01G8XDBAWKBHHJRKH0AV02KXBR
rate:
description: The numeric rate to charge
nullable: true
type: number
example: 10
code:
description: A code to identify the tax type by
nullable: true
type: string
example: tax01
name:
description: A human friendly name for the tax
type: string
example: Tax Example
region_id:
description: The ID of the region that the rate belongs to.
type: string
example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
region:
description: The details of the region that the rate belongs to.
x-expandable: region
nullable: true
type: object
products:
description: The details of the products that belong to this tax rate.
type: array
x-expandable: products
items:
$ref: '#/components/schemas/Product'
product_types:
description: The details of the product types that belong to this tax rate.
type: array
x-expandable: product_types
items:
$ref: '#/components/schemas/ProductType'
shipping_options:
description: The details of the shipping options that belong to this tax rate.
type: array
x-expandable: shipping_options
items:
$ref: '#/components/schemas/ShippingOption'
product_count:
description: The count of products
type: integer
example: 10
product_type_count:
description: The count of product types
type: integer
example: 2
shipping_option_count:
description: The count of shipping options
type: integer
example: 1
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
TrackingLink:
title: Tracking Link
description: A tracking link holds information about tracking numbers for a Fulfillment. Tracking Links can optionally contain a URL that can be visited to see the status of the shipment. Typically, the tracking link is provided from the third-party service integrated through the used fulfillment provider.
type: object
required:
- created_at
- deleted_at
- fulfillment_id
- id
- idempotency_key
- metadata
- tracking_number
- updated_at
- url
properties:
id:
description: The tracking link's ID
type: string
example: tlink_01G8ZH853Y6TFXWPG5EYE81X63
url:
description: The URL at which the status of the shipment can be tracked.
nullable: true
type: string
format: uri
tracking_number:
description: The tracking number given by the shipping carrier.
type: string
format: RH370168054CN
fulfillment_id:
description: The ID of the fulfillment that the tracking link belongs to.
type: string
example: ful_01G8ZRTMQCA76TXNAT81KPJZRF
fulfillment:
description: The details of the fulfillment that the tracking link belongs to.
x-expandable: fulfillment
nullable: true
type: object
idempotency_key:
description: Randomly generated key used to continue the completion of a process in case of failure.
nullable: true
type: string
externalDocs:
url: https://docs.medusajs.com/development/idempotency-key/overview.md
description: Learn more how to use the idempotency key.
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute
UpdateStockLocationInput:
title: Update Stock Location Input
description: Represents the Input to update a Stock Location
type: object
properties:
name:
type: string
description: The stock location name
address_id:
type: string
description: The Stock location address ID
address:
description: Stock location address object
allOf:
- $ref: '#/components/schemas/StockLocationAddressInput'
- type: object
metadata:
type: object
description: An optional key-value map with additional details
example:
car: white
User:
title: User
description: A User is an administrator who can manage store settings and data.
type: object
required:
- api_token
- created_at
- deleted_at
- email
- first_name
- id
- last_name
- metadata
- role
- updated_at
properties:
id:
description: The user's ID
type: string
example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V
role:
description: The user's role. These roles don't provide any different privileges.
type: string
enum:
- admin
- member
- developer
default: member
email:
description: The email of the User
type: string
format: email
first_name:
description: The first name of the User
nullable: true
type: string
example: Levi
last_name:
description: The last name of the User
nullable: true
type: string
example: Bogan
api_token:
description: An API token associated with the user.
nullable: true
type: string
example: null
created_at:
description: The date with timezone at which the resource was created.
type: string
format: date-time
updated_at:
description: The date with timezone at which the resource was updated.
type: string
format: date-time
deleted_at:
description: The date with timezone at which the resource was deleted.
nullable: true
type: string
format: date-time
metadata:
description: An optional key-value map with additional details
nullable: true
type: object
example:
car: white
externalDocs:
description: Learn about the metadata attribute, and how to delete and update it.
url: https://docs.medusajs.com/development/entities/overview#metadata-attribute