diff --git a/.changeset/yellow-pillows-cry.md b/.changeset/yellow-pillows-cry.md new file mode 100644 index 0000000000000..0baa99e1fe6ca --- /dev/null +++ b/.changeset/yellow-pillows-cry.md @@ -0,0 +1,7 @@ +--- +"@medusajs/medusa-oas-cli": patch +"@medusajs/oas-github-ci": patch +--- + +feat(medusa-oas-cli): Added `--main-file-name` option to specify output file name +feat(oas-github-ci): Added `--with-full-file"` option to output both split and full files \ No newline at end of file diff --git a/package.json b/package.json index c9d397963b613..c975593f3bc40 100644 --- a/package.json +++ b/package.json @@ -70,7 +70,7 @@ "test:integration:api": "turbo run test:integration --no-daemon --filter=integration-tests-api", "test:integration:plugins": "turbo run test:integration --no-daemon --filter=integration-tests-plugins", "test:integration:repositories": "turbo run test:integration --no-daemon --filter=integration-tests-repositories", - "openapi:generate": "yarn ./packages/oas/oas-github-ci run ci", + "openapi:generate": "yarn ./packages/oas/oas-github-ci run ci --with-full-file", "medusa-oas": "yarn ./packages/oas/medusa-oas-cli run medusa-oas", "release:snapshot": "changeset publish --no-git-tags --snapshot --tag snapshot", "develop": "ts-node --transpile-only ./integration-tests/development/server.js", diff --git a/packages/oas/medusa-oas-cli/src/command-docs.ts b/packages/oas/medusa-oas-cli/src/command-docs.ts index a82d5b0cdc9ff..e19247d84c054 100644 --- a/packages/oas/medusa-oas-cli/src/command-docs.ts +++ b/packages/oas/medusa-oas-cli/src/command-docs.ts @@ -59,6 +59,10 @@ export const commandOptions: Option[] = [ "--html", "Generate a static HTML using Redocly's build-docs command." ), + new Option( + "--main-file-name ", + "The name of the main YAML file." + ).default("openapi.yaml") ] export function getCommand(): Command { @@ -95,7 +99,6 @@ export async function execute(cliParams: OptionValues): Promise { throw new Error(`--config must be a file - ${configFileCustom}`) } if (![".json", ".yaml"].includes(path.extname(configFileCustom))) { - console.log(path.extname(configFileCustom)) throw new Error( `--config file must be of type .json or .yaml - ${configFileCustom}` ) @@ -110,7 +113,7 @@ export async function execute(cliParams: OptionValues): Promise { const tmpDir = await getTmpDirectory() const configTmpFile = path.resolve(tmpDir, "redocly-config.yaml") /** matches naming convention from `redocly split` */ - const finalOASFile = path.resolve(outDir, "openapi.yaml") + const finalOASFile = cliParams.mainFileName await createTmpConfig(configFileDefault, configTmpFile) if (configFileCustom) { @@ -143,7 +146,7 @@ export async function execute(cliParams: OptionValues): Promise { if (shouldSplit) { await generateReference(srcFileSanitized, outDir) } else { - await jsonFileToYamlFile(srcFileSanitized, finalOASFile) + await jsonFileToYamlFile(srcFileSanitized, path.join(outDir, finalOASFile)) } if (shouldBuildHTML) { const outHTMLFile = path.resolve(outDir, "index.html") diff --git a/packages/oas/oas-github-ci/scripts/build-openapi.js b/packages/oas/oas-github-ci/scripts/build-openapi.js index 0e749d76ec0ce..f55852215fb0d 100755 --- a/packages/oas/oas-github-ci/scripts/build-openapi.js +++ b/packages/oas/oas-github-ci/scripts/build-openapi.js @@ -6,6 +6,7 @@ const path = require("path") const execa = require("execa") const isDryRun = process.argv.indexOf("--dry-run") !== -1 +const withFullFile = process.argv.indexOf("--with-full-file") !== -1 const basePath = path.resolve(__dirname, `../`) const repoRootPath = path.resolve(basePath, `../../../`) const docsApiPath = path.resolve(repoRootPath, "www/apps/api-reference/specs") @@ -30,7 +31,7 @@ const generateOASSource = async (outDir, apiType) => { } const generateDocs = async (srcFile, outDir, isDryRun) => { - const params = [ + let params = [ "docs", `--src-file=${srcFile}`, `--out-dir=${outDir}`, @@ -40,6 +41,21 @@ const generateDocs = async (srcFile, outDir, isDryRun) => { if (isDryRun) { params.push("--dry-run") } + await runMedusaOasCommand(params) + if (withFullFile && !isDryRun) { + console.log("Generating full file...") + params = [ + "docs", + `--src-file=${srcFile}`, + `--out-dir=${outDir}`, + `--main-file-name=openapi.full.yaml` + ] + await runMedusaOasCommand(params) + console.log("Finished generating full file.") + } +} + +const runMedusaOasCommand = async (params) => { const { all: logs } = await execa("medusa-oas", params, { cwd: basePath, all: true, diff --git a/www/apps/api-reference/app/_mdx/client-libraries.mdx b/www/apps/api-reference/app/_mdx/client-libraries.mdx index 0e82cc6fd1e6d..92150927d19d3 100644 --- a/www/apps/api-reference/app/_mdx/client-libraries.mdx +++ b/www/apps/api-reference/app/_mdx/client-libraries.mdx @@ -1,5 +1,6 @@ import { CodeTabs } from "docs-ui" import Space from "@/components/Space" +import DownloadFull from "@/components/DownloadFull" ### Just Getting Started? @@ -28,4 +29,10 @@ Check out the [quickstart guide](https://docs.medusajs.com/create-medusa-app). } } ]} -/> \ No newline at end of file +/> + +### Download Full Reference + +Download this reference as an OpenApi YAML file. You can import this file to tools like Postman and start sending requests directly to your Medusa backend. + + \ No newline at end of file diff --git a/www/apps/api-reference/app/api/download/[area]/route.ts b/www/apps/api-reference/app/api/download/[area]/route.ts new file mode 100644 index 0000000000000..1c2b2fd6f1a35 --- /dev/null +++ b/www/apps/api-reference/app/api/download/[area]/route.ts @@ -0,0 +1,29 @@ +import { existsSync, readFileSync } from "fs" +import { NextResponse } from "next/server" +import path from "path" + +type DownloadParams = { + params: { + area: string + } +} + +export function GET(request: Request, { params }: DownloadParams) { + const { area } = params + const filePath = path.join(process.cwd(), `specs/${area}/openapi.full.yaml`) + + if (!existsSync(filePath)) { + return new NextResponse(null, { + status: 404, + }) + } + + const fileContent = readFileSync(filePath) + + return new Response(fileContent, { + headers: { + "Content-Type": "application/x-yaml", + "Content-Disposition": `attachment; filename="openapi.yaml"`, + }, + }) +} diff --git a/www/apps/api-reference/components/DownloadFull/index.tsx b/www/apps/api-reference/components/DownloadFull/index.tsx new file mode 100644 index 0000000000000..807a48db7b45c --- /dev/null +++ b/www/apps/api-reference/components/DownloadFull/index.tsx @@ -0,0 +1,19 @@ +"use client" + +import { Button } from "docs-ui" +import { useArea } from "../../providers/area" +import Link from "next/link" + +const DownloadFull = () => { + const { area } = useArea() + + return ( + + ) +} + +export default DownloadFull diff --git a/www/apps/api-reference/specs/admin/openapi.full.yaml b/www/apps/api-reference/specs/admin/openapi.full.yaml new file mode 100644 index 0000000000000..b90c192a51ae2 --- /dev/null +++ b/www/apps/api-reference/specs/admin/openapi.full.yaml @@ -0,0 +1,35603 @@ +openapi: 3.0.0 +info: + version: 1.0.0 + title: Medusa Admin API + license: + name: MIT + url: https://github.com/medusajs/medusa/blob/master/LICENSE +tags: + - name: Apps Oauth + description: > + Some plugins may require to authenticate with third-party services and + store authentication details, such as the authentication token. To do + that, they can create an Oauth provider within the plugin that handles the + authentication. + + The Apps Oauth API Routes allows admins to manage and generate token for + an app using its oauth provider. + - name: Auth + description: > + Authentication API Routes allow admin users to manage their session, such + as login or log out. + + When an admin user is logged in, the cookie header is set indicating the + admin's login session. + externalDocs: + description: How to implement user profiles + url: https://docs.medusajs.com/modules/users/admin/manage-profile + - name: Batch Jobs + description: > + A batch job is a task that is performed by the Medusa backend + asynchronusly. For example, the Import Product feature is implemented + using batch jobs. + + Batch Job API Routes allows admins to manage the batch jobs and their + state. + externalDocs: + description: How to import products + url: https://docs.medusajs.com/modules/products/admin/import-products + - name: Currencies + description: > + A store can use unlimited currencies, and each region must be associated + with at least one currency. + + Currencies are defined within the Medusa backend. Currency API Routes + allow admins to list and update currencies. + externalDocs: + description: How to manage currencies + url: >- + https://docs.medusajs.com/modules/regions-and-currencies/admin/manage-currencies + - name: Customers + description: > + Customers can either be created when they register through the Store APIs, + or created by the admin using the Admin APIs. + externalDocs: + description: How to manage customers + url: https://docs.medusajs.com/modules/customers/admin/manage-customers + - name: Customer Groups + description: > + Customer Groups can be used to organize customers that share similar data + or attributes into dedicated groups. + + This can be useful for different purposes such as setting a different + price for a specific customer group. + externalDocs: + description: How to manage customer groups + url: https://docs.medusajs.com/modules/customers/admin/manage-customer-groups + - name: Discounts + description: > + Admins can create discounts with conditions and rules, providing them with + advanced settings for variety of cases. + + The Discount API Routes can be used to manage discounts, their conditions, + resources, and more. + externalDocs: + description: How to manage discounts + url: https://docs.medusajs.com/modules/discounts/admin/manage-discounts + - name: Draft Orders + description: > + A draft order is an order created manually by the admin. It allows admins + to create orders without direct involvement from the customer. + externalDocs: + description: How to manage draft orders + url: https://docs.medusajs.com/modules/orders/admin/manage-draft-orders + - name: Gift Cards + description: > + Admins can create gift cards and send them directly to customers, + specifying options like their balance, region, and more. + + These gift cards are different than the saleable gift cards in a store, + which are created and managed through Product API Routes. + externalDocs: + description: How to manage gift cards + url: >- + https://docs.medusajs.com/modules/gift-cards/admin/manage-gift-cards#manage-custom-gift-cards + - name: Inventory Items + description: > + Inventory items, provided by the [Inventory + Module](https://docs.medusajs.com/modules/multiwarehouse/inventory-module), + can be used to manage the inventory of saleable items in your store. + externalDocs: + description: How to manage inventory items + url: >- + https://docs.medusajs.com/modules/multiwarehouse/admin/manage-inventory-items + - name: Invites + description: > + An admin can invite new users to manage their team. This would allow new + users to authenticate as admins and perform admin functionalities. + externalDocs: + description: How to manage invites + url: https://docs.medusajs.com/modules/users/admin/manage-invites + - name: Notes + description: > + Notes are created by admins and can be associated with any resource. For + example, an admin can add a note to an order for additional details or + remarks. + - name: Notifications + description: > + Notifications are sent to customers to inform them of new updates. For + example, a notification can be sent to the customer when their order is + place or its state is updated. + + The notification's type, such as an email or SMS, is determined by the + notification provider installed on the Medusa backend. + - name: Orders + description: > + Orders are purchases made by customers, typically through a storefront + using the Store API. Draft orders created by the admin are also + transformed to an Order once the payment is captured. + + Managing orders include managing fulfillment, payment, claims, + reservations, and more. + externalDocs: + description: How to manage orders + url: https://docs.medusajs.com/modules/orders/admin/manage-orders + - name: Order Edits + description: > + An admin can edit an order to remove, add, or update an item's quantity. + When an admin edits an order, they're stored as an `OrderEdit`. + externalDocs: + description: How to edit an order + url: https://docs.medusajs.com/modules/orders/admin/edit-order + - name: Payments + description: > + A payment can be related to an order, swap, return, or more. It can be + captured or refunded. + - name: Payment Collections + description: > + A payment collection is useful for managing additional payments, such as + for Order Edits, or installment payments. + - name: Price Lists + description: > + A price list are special prices applied to products based on a set of + conditions, such as customer group. + externalDocs: + description: How to manage price lists + url: https://docs.medusajs.com/modules/price-lists/admin/manage-price-lists + - name: Products + description: > + Products are saleable items in a store. This also includes [saleable gift + cards](https://docs.medusajs.com/modules/gift-cards/admin/manage-gift-cards#manage-gift-card-product) + in a store. + externalDocs: + description: How to manage products + url: https://docs.medusajs.com/modules/products/admin/manage-products + - name: Product Categories + description: > + Products can be categoriezed into categories. A product can be added into + more than one category. + externalDocs: + description: How to manage product categories + url: https://docs.medusajs.com/modules/products/admin/manage-categories + - name: Product Collections + description: > + A product collection is used to organize products for different purposes + such as marketing or discount purposes. For example, you can create a + Summer Collection. + - name: Product Tags + description: > + Product tags are string values created when you create or update a product + with a new tag. + + Products can have more than one tag, and products can share tags. This + allows admins to associate products to similar tags that can be used to + filter products. + - name: Product Types + description: > + Product types are string values created when you create or update a + product with a new type. + + Products can have one type, and products can share types. This allows + admins to associate products with a type that can be used to filter + products. + - name: Product Variants + description: > + Product variants are the actual salable item in your store. Each variant + is a combination of the different option values available on the product. + + Product variants can be managed through the Products API Routes. + externalDocs: + description: How to manage product variants + url: >- + https://docs.medusajs.com/modules/products/admin/manage-products#manage-product-variants + - name: Publishable API Keys + description: > + Publishable API Keys can be used to scope Store API calls with an API key, + determining what resources are retrieved when querying the API. + + For example, a publishable API key can be associated with one or more + sales channels. When it is passed in the header of a request to the List + Product store API Route, + + the sales channels are inferred from the key and only products associated + with those sales channels are retrieved. + + Admins can manage publishable API keys and their associated resources. + Currently, only Sales Channels are supported as a resource. + externalDocs: + description: How to manage publishable API keys + url: >- + https://docs.medusajs.com/development/publishable-api-keys/admin/manage-publishable-api-keys + - name: Reservations + description: > + Reservations, provided by the [Inventory + Module](https://docs.medusajs.com/modules/multiwarehouse/inventory-module), + are quantities of an item that are reserved, typically when an order is + placed but not yet fulfilled. + + Reservations can be associated with any resources, but commonly with line + items of an order. + externalDocs: + description: How to manage item allocations in orders + url: >- + https://docs.medusajs.com/modules/multiwarehouse/admin/manage-item-allocations-in-orders + - name: Regions + description: > + Regions are different countries or geographical regions that the commerce + store serves customers in. + + Admins can manage these regions, their providers, and more. + externalDocs: + description: How to manage regions + url: >- + https://docs.medusajs.com/modules/regions-and-currencies/admin/manage-regions + - name: Return Reasons + description: > + Return reasons are key-value pairs that are used to specify why an order + return is being created. + + Admins can manage available return reasons, and they can be used by both + admins and customers when creating a return. + externalDocs: + description: How to manage return reasons + url: >- + https://docs.medusajs.com/modules/orders/admin/manage-returns#manage-return-reasons + - name: Returns + description: > + A return can be created by a customer or an admin to return items in an + order. + + Admins can manage these returns and change their state. + externalDocs: + description: How to manage returns + url: https://docs.medusajs.com/modules/orders/admin/manage-returns + - name: Sales Channels + description: > + A sales channel indicates a channel where products can be sold in. For + example, a webshop or a mobile app. + + Admins can manage sales channels and the products available in them. + externalDocs: + description: How to manage sales channels + url: https://docs.medusajs.com/modules/sales-channels/admin/manage + - name: Shipping Options + description: > + A shipping option is used to define the available shipping methods during + checkout or when creating a return. + + Admins can create an unlimited number of shipping options, each associated + with a shipping profile and fulfillment provider, among other resources. + externalDocs: + description: Shipping Option architecture + url: >- + https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-option + - name: Shipping Profiles + description: > + A shipping profile is used to group products that can be shipped in the + same manner. + + They are created by the admin and they're not associated with a + fulfillment provider. + externalDocs: + description: Shipping Option architecture + url: >- + https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-profile + - name: Stock Locations + description: > + A stock location, provided by the [Stock Location + module](https://docs.medusajs.com/modules/multiwarehouse/stock-location-module), + indicates a physical address that stock-kept items, such as physical + products, can be stored in. + + An admin can create and manage available stock locations. + externalDocs: + description: How to manage stock locations. + url: >- + https://docs.medusajs.com/modules/multiwarehouse/admin/manage-stock-locations + - name: Store + description: > + A store indicates the general configurations and details about the + commerce store. By default, there's only one store in the Medusa backend. + + Admins can manage the store and its details or configurations. + - name: Swaps + description: > + A swap is created by a customer or an admin to exchange an item with a new + one. + + Creating a swap implicitely includes creating a return for the item being + exchanged. + externalDocs: + description: How to manage swaps + url: https://docs.medusajs.com/modules/orders/admin/manage-swaps + - name: Tax Rates + description: > + Each region has at least a default tax rate. Admins can create and manage + additional tax rates that can be applied for certain conditions, such as + for specific product types. + externalDocs: + description: How to manage tax rates + url: https://docs.medusajs.com/modules/taxes/admin/manage-tax-rates + - name: Uploads + description: > + The upload API Routes are used to upload any type of resources. For + example, they can be used to upload CSV files that are used to import + products into the store. + externalDocs: + description: How to upload CSV file when importing a product. + url: >- + https://docs.medusajs.com/modules/products/admin/import-products#1-upload-csv-file + - name: Users + description: > + A store can have more than one user, each having the same privileges. + Admins can manage users, their passwords, and more. + externalDocs: + description: How to manage users + url: https://docs.medusajs.com/modules/users/admin/manage-users +servers: + - url: https://api.medusa-commerce.com +paths: + /admin/apps: + get: + operationId: GetApps + summary: List Applications + description: Retrieve a list of applications registered in the Medusa backend. + x-authenticated: true + x-codegen: + method: list + x-codeSamples: + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/apps' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Apps Oauth + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminAppsListRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/apps/authorizations: + post: + operationId: PostApps + summary: Generate Token for App + description: >- + Use an app's Oauth provider to generate and store a new token for + authentication. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostAppsReq' + x-codegen: + method: authorize + x-codeSamples: + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/apps/authorizations' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "application_name": "example", + "state": "ready", + "code": "token" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Apps Oauth + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminAppsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/auth: + get: + operationId: GetAuth + summary: Get Current User + x-authenticated: true + description: Get the currently logged in user's details. + x-codegen: + method: getSession + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.auth.getSession() + + .then(({ user }) => { + console.log(user.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/auth' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Auth + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminAuthRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostAuth + summary: User Login + x-authenticated: false + description: >- + Log a User in and includes the Cookie session in the response header. + The cookie session can be used in subsequent requests to authorize the + user to perform admin functionalities. When using Medusa's JS or Medusa + React clients, the cookie is automatically attached to subsequent + requests. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostAuthReq' + x-codegen: + method: createSession + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + medusa.admin.auth.createSession({ + email: "user@example.com", + password: "supersecret" + }) + + .then(({ user }) => { + console.log(user.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/auth' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "email": "user@example.com", + "password": "supersecret" + }' + tags: + - Auth + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminAuthRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/incorrect_credentials' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteAuth + summary: User Logout + x-authenticated: true + description: >- + Delete the current session for the logged in user. This will only work + if you're using Cookie session for authentication. If the API token is + still passed in the header, the user is still authorized to perform + admin functionalities in other API Routes. + x-codegen: + method: deleteSession + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in + + medusa.admin.auth.deleteSession() + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/auth' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Auth + responses: + '200': + description: OK + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/auth/token: + post: + operationId: PostToken + summary: User Login (JWT) + x-authenticated: false + description: >- + After a successful login, a JWT token is returned, which can be used to + send authenticated requests. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostAuthReq' + x-codegen: + method: getToken + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + medusa.admin.auth.getToken({ + email: 'user@example.com', + password: 'supersecret' + }) + + .then(({ access_token }) => { + console.log(access_token); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/auth/token' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "email": "user@example.com", + "password": "supersecret" + }' + tags: + - Auth + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminBearerAuthRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/incorrect_credentials' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/batch-jobs: + get: + operationId: GetBatchJobs + summary: List Batch Jobs + description: >- + Retrieve a list of Batch Jobs. The batch jobs can be filtered by fields + such as `type` or `confirmed_at`. The batch jobs can also be sorted or + paginated. + x-authenticated: true + parameters: + - in: query + name: limit + description: Limit the number of batch jobs returned. + schema: + type: integer + default: 10 + - in: query + name: offset + description: The number of batch jobs to skip when retrieving the batch jobs. + schema: + type: integer + default: 0 + - in: query + name: id + style: form + explode: false + description: Filter by the batch ID + schema: + oneOf: + - type: string + description: batch job ID + - type: array + description: multiple batch job IDs + items: + type: string + - in: query + name: type + style: form + explode: false + description: Filter by the batch type + schema: + type: array + items: + type: string + - in: query + name: confirmed_at + style: form + explode: false + description: Filter by a confirmation date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: pre_processed_at + style: form + explode: false + description: Filter by a pre-processing date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: completed_at + style: form + explode: false + description: Filter by a completion date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: failed_at + style: form + explode: false + description: Filter by a failure date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: canceled_at + style: form + explode: false + description: Filter by a cancelation date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: order + description: A batch-job field to sort-order the retrieved batch jobs by. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + batch jobs. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned batch + jobs. + schema: + type: string + - in: query + name: created_at + style: form + explode: false + description: Filter by a creation date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: updated_at + style: form + explode: false + description: Filter by an update date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + x-codegen: + method: list + queryParams: AdminGetBatchParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.batchJobs.list() + + .then(({ batch_jobs, limit, offset, count }) => { + console.log(batch_jobs.length) + }) + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/batch-jobs' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Batch Jobs + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminBatchJobListRes' + '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: PostBatchJobs + summary: Create a Batch Job + description: >- + Create a Batch Job to be executed asynchronously in the Medusa backend. + If `dry_run` is set to `true`, the batch job will not be executed until + the it is confirmed, which can be done using the Confirm Batch Job API + Route. + externalDocs: + description: How to create a batch job + url: >- + https://docs.medusajs.com/development/batch-jobs/create#create-batch-job + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostBatchesReq' + 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 }) + + // must be previously logged in or use api token + + medusa.admin.batchJobs.create({ + type: 'product-export', + context: {}, + dry_run: false + }).then((({ batch_job }) => { + console.log(batch_job.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/batch-jobs' \ + -H 'Content-Type: application/json' \ + -H 'x-medusa-access-token: {api_token}' \ + --data-raw '{ + "type": "product-export", + "context": { } + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Batch Jobs + responses: + '201': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminBatchJobRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/batch-jobs/{id}: + get: + operationId: GetBatchJobsBatchJob + summary: Get a Batch Job + description: Retrieve the details of a batch job. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Batch Job + 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 }) + + // must be previously logged in or use api token + + medusa.admin.batchJobs.retrieve(batchJobId) + + .then(({ batch_job }) => { + console.log(batch_job.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/batch-jobs/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Batch Jobs + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminBatchJobRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/batch-jobs/{id}/cancel: + post: + operationId: PostBatchJobsBatchJobCancel + summary: Cancel a Batch Job + description: >- + Mark a batch job as canceled. When a batch job is canceled, the + processing of the batch job doesn’t automatically stop. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the batch job. + schema: + type: string + x-codegen: + method: cancel + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.batchJobs.cancel(batchJobId) + + .then(({ batch_job }) => { + console.log(batch_job.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/batch-jobs/{id}/cancel' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Batch Jobs + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminBatchJobRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/batch-jobs/{id}/confirm: + post: + operationId: PostBatchJobsBatchJobConfirmProcessing + summary: Confirm a Batch Job + description: >- + When a batch job is created, it is not executed automatically if + `dry_run` is set to `true`. This API Route confirms that the batch job + should be executed. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the batch job. + schema: + type: string + x-codegen: + method: confirm + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.batchJobs.confirm(batchJobId) + + .then(({ batch_job }) => { + console.log(batch_job.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/batch-jobs/{id}/confirm' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Batch Jobs + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminBatchJobRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/collections: + get: + operationId: GetCollections + summary: List Collections + description: >- + Retrieve a list of Product Collection. The product collections can be + filtered by fields such as `handle` or `title`. The collections can also + be sorted or paginated. + x-authenticated: true + parameters: + - in: query + name: limit + description: The number of collections to return. + schema: + type: integer + default: 10 + - in: query + name: offset + description: The number of collections to skip when retrieving the collections. + schema: + type: integer + default: 0 + - in: query + name: title + description: Filter collections by their title. + schema: + type: string + - in: query + name: handle + description: Filter collections by their handle. + schema: + type: string + - in: query + name: q + description: a term to search collections by their title or handle. + schema: + type: string + - in: query + name: discount_condition_id + description: Filter collections by a discount condition ID associated with them. + schema: + type: string + - in: query + name: created_at + description: Filter by a creation date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: updated_at + description: Filter by an update date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: deleted_at + description: Filter by a deletion date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + x-codegen: + method: list + queryParams: AdminGetCollectionsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.collections.list() + + .then(({ collections, limit, offset, count }) => { + console.log(collections.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/collections' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Collections + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCollectionsListRes' + '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: PostCollections + summary: Create a Collection + description: Create a Product Collection. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostCollectionsReq' + 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 }) + + // must be previously logged in or use api token + + medusa.admin.collections.create({ + title: "New Collection" + }) + + .then(({ collection }) => { + console.log(collection.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/collections' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "title": "New Collection" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Collections + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCollectionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/collections/{id}: + get: + operationId: GetCollectionsCollection + summary: Get a Collection + description: >- + Retrieve a Product Collection by its ID. The products associated with it + are expanded and returned as well. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Product Collection + 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 }) + + // must be previously logged in or use api token + + medusa.admin.collections.retrieve(collectionId) + + .then(({ collection }) => { + console.log(collection.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/collections/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Collections + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCollectionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostCollectionsCollection + summary: Update a Collection + description: Update a Product Collection's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Collection. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostCollectionsCollectionReq' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.collections.update(collectionId, { + title: "New Collection" + }) + + .then(({ collection }) => { + console.log(collection.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/collections/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "title": "New Collection" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Collections + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCollectionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteCollectionsCollection + summary: Delete a Collection + description: Delete a Product Collection. This does not delete associated products. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Collection. + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.collections.delete(collectionId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/collections/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Collections + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCollectionsDeleteRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/collections/{id}/products/batch: + post: + operationId: PostProductsToCollection + summary: Add Products to Collection + description: Add products to a product collection. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the product collection. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostProductsToCollectionReq' + x-codegen: + method: addProducts + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.collections.addProducts(collectionId, { + product_ids: [ + productId1, + productId2 + ] + }) + + .then(({ collection }) => { + console.log(collection.products) + }) + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/collections/{id}/products/batch' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "product_ids": [ + "prod_01G1G5V2MBA328390B5AXJ610F" + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Collections + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCollectionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteProductsFromCollection + summary: Remove Products from Collection + description: >- + Remove a list of products from a collection. This would not delete the + product, only the association between the product and the collection. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Product Collection. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDeleteProductsFromCollectionReq' + x-codegen: + method: removeProducts + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.collections.removeProducts(collectionId, { + product_ids: [ + productId1, + productId2 + ] + }) + + .then(({ id, object, removed_products }) => { + console.log(removed_products) + }) + - lang: Shell + label: cURL + source: > + curl -X DELETE '{backend_url}/admin/collections/{id}/products/batch' + \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "product_ids": [ + "prod_01G1G5V2MBA328390B5AXJ610F" + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Collections + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDeleteProductsFromCollectionRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/currencies: + get: + operationId: GetCurrencies + summary: List Currency + description: >- + Retrieve a list of currencies. The currencies can be filtered by fields + such as `code`. The currencies can also be sorted or paginated. + x-authenticated: true + parameters: + - in: query + name: code + description: filter by currency code. + schema: + type: string + - in: query + name: includes_tax + description: filter currencies by whether they include taxes or not. + schema: + type: boolean + x-featureFlag: tax_inclusive_pricing + - in: query + name: order + description: A field to sort order the retrieved currencies by. + schema: + type: string + - in: query + name: offset + description: The number of currencies to skip when retrieving the currencies. + schema: + type: number + default: '0' + - in: query + name: limit + description: The number of currencies to return. + schema: + type: number + default: '20' + x-codegen: + method: list + queryParams: AdminGetCurrenciesParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.currencies.list() + + .then(({ currencies, count, offset, limit }) => { + console.log(currencies.length); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/currencies' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Currencies + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCurrenciesListRes' + /admin/currencies/{code}: + post: + operationId: PostCurrenciesCurrency + summary: Update a Currency + description: Update a Currency's details. + x-authenticated: true + parameters: + - in: path + name: code + required: true + description: The code of the Currency. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostCurrenciesCurrencyReq' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.currencies.update(code, { + includes_tax: true + }) + + .then(({ currency }) => { + console.log(currency.code); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/currencies/{code}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "includes_tax": true + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Currencies + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCurrenciesRes' + /admin/customer-groups: + get: + operationId: GetCustomerGroups + summary: List Customer Groups + description: >- + Retrieve a list of customer groups. The customer groups can be filtered + by fields such as `name` or `id. The customer groups can also be sorted + or paginated. + x-authenticated: true + parameters: + - in: query + name: q + description: term to search customer groups by name. + schema: + type: string + - in: query + name: offset + description: >- + The number of customer groups to skip when retrieving the customer + groups. + schema: + type: integer + default: 0 + - in: query + name: order + description: A field to sort order the retrieved customer groups by. + schema: + type: string + - in: query + name: discount_condition_id + description: Filter by discount condition ID. + schema: + type: string + - in: query + name: id + style: form + explode: false + description: Filter by the customer group ID + schema: + oneOf: + - type: string + description: customer group ID + - type: array + description: an array of customer group IDs + items: + type: string + - type: object + properties: + lt: + type: string + description: filter by IDs less than this ID + gt: + type: string + description: filter by IDs greater than this ID + lte: + type: string + description: filter by IDs less than or equal to this ID + gte: + type: string + description: filter by IDs greater than or equal to this ID + - in: query + name: name + style: form + explode: false + description: Filter by the customer group name + schema: + type: array + description: an array of customer group names + items: + type: string + description: customer group name + - 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: limit + description: The number of customer groups to return. + schema: + type: integer + default: 10 + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + customer groups. + schema: + type: string + x-codegen: + method: list + queryParams: AdminGetCustomerGroupsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.customerGroups.list() + + .then(({ customer_groups, limit, offset, count }) => { + console.log(customer_groups.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/customer-groups' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Customer Groups + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCustomerGroupsListRes' + '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: PostCustomerGroups + summary: Create a Customer Group + description: Creates a Customer Group. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostCustomerGroupsReq' + 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 }) + + // must be previously logged in or use api token + + medusa.admin.customerGroups.create({ + name: "VIP" + }) + + .then(({ customer_group }) => { + console.log(customer_group.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/customer-groups' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "name": "VIP" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Customer Groups + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCustomerGroupsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/customer-groups/{id}: + get: + operationId: GetCustomerGroupsGroup + summary: Get a Customer Group + description: >- + Retrieve a Customer Group by its ID. You can expand the customer group's + relations or select the fields that should be returned. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Customer Group. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + customer group. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + customer group. + schema: + type: string + x-codegen: + method: retrieve + queryParams: AdminGetCustomerGroupsGroupParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.customerGroups.retrieve(customerGroupId) + + .then(({ customer_group }) => { + console.log(customer_group.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/customer-groups/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Customer Groups + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCustomerGroupsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostCustomerGroupsGroup + summary: Update a Customer Group + description: Update a Customer Group's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the customer group. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostCustomerGroupsGroupReq' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.customerGroups.update(customerGroupId, { + name: "VIP" + }) + + .then(({ customer_group }) => { + console.log(customer_group.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/customer-groups/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "name": "VIP" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Customer Groups + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCustomerGroupsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteCustomerGroupsCustomerGroup + summary: Delete a Customer Group + description: >- + Delete a customer group. This doesn't delete the customers associated + with the customer group. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Customer Group + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.customerGroups.delete(customerGroupId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/customer-groups/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Customer Groups + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCustomerGroupsDeleteRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/customer-groups/{id}/customers: + get: + operationId: GetCustomerGroupsGroupCustomers + summary: List Customers + description: >- + Retrieve a list of customers in a customer group. The customers can be + filtered by the `q` field. The customers can also be paginated. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the customer group. + schema: + type: string + - in: query + name: limit + description: The number of customers to return. + schema: + type: integer + default: 50 + - in: query + name: offset + description: The number of customers to skip when retrieving the customers. + schema: + type: integer + default: 0 + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + customers. + schema: + type: string + - in: query + name: q + description: a term to search customers by email, first_name, and last_name. + schema: + type: string + x-codegen: + method: listCustomers + queryParams: AdminGetGroupsGroupCustomersParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.customerGroups.listCustomers(customerGroupId) + + .then(({ customers }) => { + console.log(customers.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/customer-groups/{id}/customers' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Customer Groups + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCustomersListRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/customer-groups/{id}/customers/batch: + post: + operationId: PostCustomerGroupsGroupCustomersBatch + summary: Add Customers to Group + description: Add a list of customers to a customer group. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the customer group. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminPostCustomerGroupsGroupCustomersBatchReq + x-codegen: + method: addCustomers + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.customerGroups.addCustomers(customerGroupId, { + customer_ids: [ + { + id: customerId + } + ] + }) + + .then(({ customer_group }) => { + console.log(customer_group.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/customer-groups/{id}/customers/batch' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "customer_ids": [ + { + "id": "cus_01G2Q4BS9GAHDBMDEN4ZQZCJB2" + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Customer Groups + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCustomerGroupsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteCustomerGroupsGroupCustomerBatch + summary: Remove Customers from Group + description: >- + Remove a list of customers from a customer group. This doesn't delete + the customer, only the association between the customer and the customer + group. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the customer group. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminDeleteCustomerGroupsGroupCustomerBatchReq + x-codegen: + method: removeCustomers + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.customerGroups.removeCustomers(customerGroupId, { + customer_ids: [ + { + id: customerId + } + ] + }) + + .then(({ customer_group }) => { + console.log(customer_group.id); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/customer-groups/{id}/customers/batch' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "customer_ids": [ + { + "id": "cus_01G2Q4BS9GAHDBMDEN4ZQZCJB2" + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Customer Groups + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCustomerGroupsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/customers: + get: + operationId: GetCustomers + summary: List Customers + description: >- + Retrieve a list of Customers. The customers can be filtered by fields + such as `q` or `groups`. The customers can also be paginated. + x-authenticated: true + parameters: + - in: query + name: limit + description: The number of customers to return. + schema: + type: integer + default: 50 + - in: query + name: offset + description: The number of customers to skip when retrieving the customers. + schema: + type: integer + default: 0 + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + customer. + schema: + type: string + - in: query + name: q + description: term to search customers' email, first_name, and last_name fields. + schema: + type: string + - in: query + name: groups + style: form + explode: false + description: Filter by customer group IDs. + schema: + type: array + items: + type: string + x-codegen: + method: list + queryParams: AdminGetCustomersParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.customers.list() + + .then(({ customers, limit, offset, count }) => { + console.log(customers.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/customers' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Customers + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCustomersListRes' + '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: PostCustomers + summary: Create a Customer + description: Allow admins to create a customer. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostCustomersReq' + 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 }) + + // must be previously logged in or use api token + + medusa.admin.customers.create({ + email: "user@example.com", + first_name: "Caterina", + last_name: "Yost", + password: "supersecret" + }) + + .then(({ customer }) => { + console.log(customer.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/customers' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "email": "user@example.com", + "first_name": "Caterina", + "last_name": "Yost", + "password": "supersecret" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Customers + responses: + '201': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCustomersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/customers/{id}: + get: + operationId: GetCustomersCustomer + summary: Get a Customer + description: Retrieve the details of a customer. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Customer. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + customer. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + customer. + 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 }) + + // must be previously logged in or use api token + + medusa.admin.customers.retrieve(customerId) + + .then(({ customer }) => { + console.log(customer.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/customers/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Customers + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCustomersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostCustomersCustomer + summary: Update a Customer + description: Update a Customer's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Customer. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + customer. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be retrieved in the returned + customer. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostCustomersCustomerReq' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.customers.update(customerId, { + first_name: "Dolly" + }) + + .then(({ customer }) => { + console.log(customer.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/customers/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "first_name": "Dolly" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Customers + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCustomersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/discounts: + get: + operationId: GetDiscounts + summary: List Discounts + x-authenticated: true + description: >- + Retrieve a list of Discounts. The discounts can be filtered by fields + such as `rule` or `is_dynamic`. The discounts can also be paginated. + parameters: + - in: query + name: q + description: term to search discounts' code field. + schema: + type: string + - in: query + name: rule + description: Filter discounts by rule fields. + schema: + type: object + properties: + type: + type: string + enum: + - fixed + - percentage + - free_shipping + description: Filter discounts by type. + allocation: + type: string + enum: + - total + - item + description: Filter discounts by allocation type. + - in: query + name: is_dynamic + description: Filter discounts by whether they're dynamic or not. + schema: + type: boolean + - in: query + name: is_disabled + description: Filter discounts by whether they're disabled or not. + schema: + type: boolean + - in: query + name: limit + description: The number of discounts to return + schema: + type: number + default: '20' + - in: query + name: offset + description: The number of discounts to skip when retrieving the discounts. + schema: + type: number + default: '0' + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in each returned + discount. + schema: + type: string + x-codegen: + method: list + queryParams: AdminGetDiscountsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.discounts.list() + + .then(({ discounts, limit, offset, count }) => { + console.log(discounts.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/discounts' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Discounts + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDiscountsListRes' + '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: PostDiscounts + summary: Create a Discount + x-authenticated: true + description: >- + Create a Discount with a given set of rules that defines how the + Discount is applied. + parameters: + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + discount. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be retrieved in the returned + discount. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostDiscountsReq' + x-codegen: + method: create + queryParams: AdminPostDiscountsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + import { AllocationType, DiscountRuleType } from "@medusajs/medusa" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.discounts.create({ + code: "TEST", + rule: { + type: DiscountRuleType.FIXED, + value: 10, + allocation: AllocationType.ITEM + }, + regions: ["reg_XXXXXXXX"], + is_dynamic: false, + is_disabled: false + }) + + .then(({ discount }) => { + console.log(discount.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/discounts' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "code": "TEST", + "rule": { + "type": "fixed", + "value": 10, + "allocation": "item" + }, + "regions": ["reg_XXXXXXXX"] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Discounts + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDiscountsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/discounts/code/{code}: + get: + operationId: GetDiscountsDiscountCode + summary: Get Discount by Code + description: Retrieve a Discount's details by its discount code + x-authenticated: true + parameters: + - in: path + name: code + required: true + description: The code of the Discount + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + discount. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + discount. + schema: + type: string + x-codegen: + method: retrieveByCode + queryParams: AdminGetDiscountsDiscountCodeParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.discounts.retrieveByCode(code) + + .then(({ discount }) => { + console.log(discount.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/discounts/code/{code}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Discounts + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDiscountsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/discounts/{discount_id}/conditions: + post: + operationId: PostDiscountsDiscountConditions + summary: Create a Condition + description: >- + Create a Discount Condition. Only one of `products`, `product_types`, + `product_collections`, `product_tags`, and `customer_groups` should be + provided, based on the type of discount condition. For example, if the + discount condition's type is `products`, the `products` field should be + provided in the request body. + x-authenticated: true + parameters: + - in: path + name: discount_id + required: true + description: The ID of the discount. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + discount. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + discount. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostDiscountsDiscountConditions' + x-codegen: + method: createCondition + queryParams: AdminPostDiscountsDiscountConditionsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + import { DiscountConditionOperator } from "@medusajs/medusa" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.discounts.createCondition(discountId, { + operator: DiscountConditionOperator.IN + }) + + .then(({ discount }) => { + console.log(discount.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/discounts/{id}/conditions' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "operator": "in" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Discounts + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDiscountsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/discounts/{discount_id}/conditions/{condition_id}: + get: + operationId: GetDiscountsDiscountConditionsCondition + summary: Get a Condition + description: Retrieve a Discount Condition's details. + x-authenticated: true + parameters: + - in: path + name: discount_id + required: true + description: The ID of the Discount. + schema: + type: string + - in: path + name: condition_id + required: true + description: The ID of the Discount Condition. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + discount condition. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + discount condition. + schema: + type: string + x-codegen: + method: getCondition + queryParams: AdminGetDiscountsDiscountConditionsConditionParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.discounts.getCondition(discountId, conditionId) + + .then(({ discount_condition }) => { + console.log(discount_condition.id); + }); + - lang: Shell + label: cURL + source: > + curl '{backend_url}/admin/discounts/{id}/conditions/{condition_id}' + \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Discounts + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDiscountConditionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostDiscountsDiscountConditionsCondition + summary: Update a Condition + description: >- + Update a Discount Condition. Only one of `products`, `product_types`, + `product_collections`, `product_tags`, and `customer_groups` should be + provided, based on the type of discount condition. For example, if the + discount condition's type is `products`, the `products` field should be + provided in the request body. + x-authenticated: true + parameters: + - in: path + name: discount_id + required: true + description: The ID of the Discount. + schema: + type: string + - in: path + name: condition_id + required: true + description: The ID of the Discount Condition. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + discount. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + discount. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminPostDiscountsDiscountConditionsCondition + x-codegen: + method: updateCondition + queryParams: AdminPostDiscountsDiscountConditionsConditionParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.discounts.updateCondition(discountId, conditionId, { + products: [ + productId + ] + }) + + .then(({ discount }) => { + console.log(discount.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/discounts/{id}/conditions/{condition}' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "products": [ + "prod_01G1G5V2MBA328390B5AXJ610F" + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Discounts + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDiscountsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteDiscountsDiscountConditionsCondition + summary: Delete a Condition + description: >- + Deletes a Discount Condition. This does not delete resources associated + to the discount condition. + x-authenticated: true + parameters: + - in: path + name: discount_id + required: true + description: The ID of the Discount + schema: + type: string + - in: path + name: condition_id + required: true + description: The ID of the Discount Condition + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + discount. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + discount. + schema: + type: string + x-codegen: + method: deleteCondition + queryParams: AdminDeleteDiscountsDiscountConditionsConditionParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.discounts.deleteCondition(discountId, conditionId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/discounts/{id}/conditions/{condition_id}' \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Discounts + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDiscountConditionsDeleteRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/discounts/{discount_id}/conditions/{condition_id}/batch: + post: + operationId: PostDiscountsDiscountConditionsConditionBatch + summary: Add Batch Resources + description: >- + Add a batch of resources to a discount condition. The type of resource + depends on the type of discount condition. For example, if the discount + condition's type is `products`, the resources being added should be + products. + x-authenticated: true + parameters: + - in: path + name: discount_id + required: true + description: The ID of the discount the condition belongs to. + schema: + type: string + - in: path + name: condition_id + required: true + description: The ID of the discount condition on which to add the item. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + discount. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + discount. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminPostDiscountsDiscountConditionsConditionBatchReq + x-codegen: + method: addConditionResourceBatch + queryParams: AdminPostDiscountsDiscountConditionsConditionBatchParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.discounts.addConditionResourceBatch(discountId, + conditionId, { + resources: [{ id: itemId }] + }) + + .then(({ discount }) => { + console.log(discount.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/discounts/{id}/conditions/{condition_id}/batch' + \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "resources": [{ "id": "item_id" }] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Discounts + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDiscountsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteDiscountsDiscountConditionsConditionBatch + summary: Remove Batch Resources + description: >- + Remove a batch of resources from a discount condition. This will only + remove the association between the resource and the discount condition, + but not the resource itself. + x-authenticated: true + parameters: + - in: path + name: discount_id + required: true + description: The ID of the discount. + schema: + type: string + - in: path + name: condition_id + required: true + description: The ID of the condition to remove the resources from. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + discount. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + discount. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminDeleteDiscountsDiscountConditionsConditionBatchReq + x-codegen: + method: deleteConditionResourceBatch + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.discounts.deleteConditionResourceBatch(discountId, + conditionId, { + resources: [{ id: itemId }] + }) + + .then(({ discount }) => { + console.log(discount.id); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/discounts/{id}/conditions/{condition_id}/batch' + \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "resources": [{ "id": "item_id" }] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Discounts + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDiscountsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/discounts/{id}: + get: + operationId: GetDiscountsDiscount + summary: Get a Discount + description: Retrieves a Discount + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Discount + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + discount. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + discount. + schema: + type: string + x-codegen: + method: retrieve + queryParams: AdminGetDiscountParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.discounts.retrieve(discountId) + + .then(({ discount }) => { + console.log(discount.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/discounts/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Discounts + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDiscountsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostDiscountsDiscount + summary: Update a Discount + description: >- + Update a Discount with a given set of rules that define how the Discount + is applied. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Discount. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + discount. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be retrieved in the returned + discount. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostDiscountsDiscountReq' + x-codegen: + method: update + queryParams: AdminPostDiscountsDiscountParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.discounts.update(discountId, { + code: "TEST" + }) + + .then(({ discount }) => { + console.log(discount.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/discounts/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "code": "TEST" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Discounts + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDiscountsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteDiscountsDiscount + summary: Delete a Discount + description: >- + Delete a Discount. Deleting the discount will make it unavailable for + customers to use. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Discount + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.discounts.delete(discountId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/discounts/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Discounts + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDiscountsDeleteRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/discounts/{id}/dynamic-codes: + post: + operationId: PostDiscountsDiscountDynamicCodes + summary: Create a Dynamic Code + description: >- + Create a dynamic unique code that can map to a parent Discount. This is + useful if you want to automatically generate codes with the same rules + and conditions. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Discount to create the dynamic code for." + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostDiscountsDiscountDynamicCodesReq' + x-codegen: + method: createDynamicCode + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.discounts.createDynamicCode(discountId, { + code: "TEST", + usage_limit: 1 + }) + + .then(({ discount }) => { + console.log(discount.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/discounts/{id}/dynamic-codes' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "code": "TEST" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Discounts + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDiscountsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/discounts/{id}/dynamic-codes/{code}: + delete: + operationId: DeleteDiscountsDiscountDynamicCodesCode + summary: Delete a Dynamic Code + description: Delete a dynamic code from a Discount. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Discount + schema: + type: string + - in: path + name: code + required: true + description: The dynamic code to delete + schema: + type: string + x-codegen: + method: deleteDynamicCode + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.discounts.deleteDynamicCode(discountId, code) + + .then(({ discount }) => { + console.log(discount.id); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/discounts/{id}/dynamic-codes/{code}' \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Discounts + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDiscountsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/discounts/{id}/regions/{region_id}: + post: + operationId: PostDiscountsDiscountRegionsRegion + summary: Add Region to Discount + description: Add a Region to the list of Regions a Discount can be used in. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Discount. + schema: + type: string + - in: path + name: region_id + required: true + description: The ID of the Region. + schema: + type: string + x-codegen: + method: addRegion + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.discounts.addRegion(discountId, regionId) + + .then(({ discount }) => { + console.log(discount.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/discounts/{id}/regions/{region_id}' \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Discounts + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDiscountsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteDiscountsDiscountRegionsRegion + summary: Remove Region + x-authenticated: true + description: >- + Remove a Region from the list of Regions that a Discount can be used in. + This does not delete a region, only the association between it and the + discount. + parameters: + - in: path + name: id + required: true + description: The ID of the Discount. + schema: + type: string + - in: path + name: region_id + required: true + description: The ID of the Region. + schema: + type: string + x-codegen: + method: removeRegion + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.discounts.removeRegion(discountId, regionId) + + .then(({ discount }) => { + console.log(discount.id); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/discounts/{id}/regions/{region_id}' \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Discounts + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDiscountsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/draft-orders: + get: + operationId: GetDraftOrders + summary: List Draft Orders + description: >- + Retrieve an list of Draft Orders. The draft orders can be filtered by + fields such as `q`. The draft orders can also paginated. + x-authenticated: true + parameters: + - in: query + name: offset + description: The number of draft orders to skip when retrieving the draft orders. + schema: + type: number + default: '0' + - in: query + name: limit + description: Limit the number of draft orders returned. + schema: + type: number + default: '50' + - in: query + name: q + description: >- + a term to search draft orders' display IDs and emails in the draft + order's cart + schema: + type: string + x-codegen: + method: list + queryParams: AdminGetDraftOrdersParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.draftOrders.list() + + .then(({ draft_orders, limit, offset, count }) => { + console.log(draft_orders.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/draft-orders' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Draft Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDraftOrdersListRes' + '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: PostDraftOrders + summary: Create a Draft Order + description: >- + Create a Draft Order. A draft order is not transformed into an order + until payment is captured. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostDraftOrdersReq' + 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 }) + + // must be previously logged in or use api token + + medusa.admin.draftOrders.create({ + email: "user@example.com", + region_id, + items: [ + { + quantity: 1 + } + ], + shipping_methods: [ + { + option_id + } + ], + }) + + .then(({ draft_order }) => { + console.log(draft_order.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/draft-orders' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "email": "user@example.com", + "region_id": "{region_id}" + "items": [ + { + "quantity": 1 + } + ], + "shipping_methods": [ + { + "option_id": "{option_id}" + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Draft Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDraftOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/draft-orders/{id}: + get: + operationId: GetDraftOrdersDraftOrder + summary: Get a Draft Order + description: Retrieve a Draft Order's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Draft Order. + schema: + type: string + x-codegen: + method: retrieve + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.draftOrders.retrieve(draftOrderId) + + .then(({ draft_order }) => { + console.log(draft_order.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/draft-orders/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Draft Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDraftOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostDraftOrdersDraftOrder + summary: Update a Draft Order + description: Update a Draft Order's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Draft Order. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostDraftOrdersDraftOrderReq' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.draftOrders.update(draftOrderId, { + email: "user@example.com" + }) + + .then(({ draft_order }) => { + console.log(draft_order.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/draft-orders/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "email": "user@example.com" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Draft Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDraftOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteDraftOrdersDraftOrder + summary: Delete a Draft Order + description: Delete a Draft Order + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Draft Order. + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.draftOrders.delete(draftOrderId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/draft-orders/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Draft Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDraftOrdersDeleteRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/draft-orders/{id}/line-items: + post: + operationId: PostDraftOrdersDraftOrderLineItems + summary: Create a Line Item + description: Create a Line Item in the Draft Order. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Draft Order. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostDraftOrdersDraftOrderLineItemsReq' + x-codegen: + method: addLineItem + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.draftOrders.addLineItem(draftOrderId, { + quantity: 1 + }) + + .then(({ draft_order }) => { + console.log(draft_order.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/draft-orders/{id}/line-items' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "quantity": 1 + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Draft Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDraftOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/draft-orders/{id}/line-items/{line_id}: + post: + operationId: PostDraftOrdersDraftOrderLineItemsItem + summary: Update a Line Item + description: Update a Line Item in a Draft Order + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Draft Order. + schema: + type: string + - in: path + name: line_id + required: true + description: The ID of the Line Item. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminPostDraftOrdersDraftOrderLineItemsItemReq + x-codegen: + method: updateLineItem + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.draftOrders.updateLineItem(draftOrderId, lineId, { + quantity: 1 + }) + + .then(({ draft_order }) => { + console.log(draft_order.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/draft-orders/{id}/line-items/{line_id}' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "quantity": 1 + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Draft Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDraftOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteDraftOrdersDraftOrderLineItemsItem + summary: Delete a Line Item + description: Deletes a Line Item from a Draft Order. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Draft Order. + schema: + type: string + - in: path + name: line_id + required: true + description: The ID of the line item. + schema: + type: string + x-codegen: + method: removeLineItem + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.draftOrders.removeLineItem(draftOrderId, itemId) + + .then(({ draft_order }) => { + console.log(draft_order.id); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/draft-orders/{id}/line-items/{line_id}' \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Draft Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDraftOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/draft-orders/{id}/pay: + post: + summary: Mark Paid + operationId: PostDraftOrdersDraftOrderRegisterPayment + description: >- + Capture the draft order's payment. This will also set the draft order's + status to `completed` and create an Order from the draft order. The + payment is captured through Medusa's system payment, which is manual + payment that isn't integrated with any third-party payment provider. It + is assumed that the payment capturing is handled manually by the admin. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The Draft Order ID. + schema: + type: string + x-codegen: + method: markPaid + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.draftOrders.markPaid(draftOrderId) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/draft-orders/{id}/pay' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Draft Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminPostDraftOrdersDraftOrderRegisterPaymentRes + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/gift-cards: + get: + operationId: GetGiftCards + summary: List Gift Cards + description: >- + Retrieve a list of Gift Cards. The gift cards can be filtered by fields + such as `q`. The gift cards can also paginated. + x-authenticated: true + parameters: + - in: query + name: offset + description: The number of gift cards to skip when retrieving the gift cards. + schema: + type: number + default: '0' + - in: query + name: limit + description: Limit the number of gift cards returned. + schema: + type: number + default: '50' + - in: query + name: q + description: a term to search gift cards' code or display ID + schema: + type: string + x-codegen: + method: list + queryParams: AdminGetGiftCardsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.giftCards.list() + + .then(({ gift_cards, limit, offset, count }) => { + console.log(gift_cards.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/gift-cards' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Gift Cards + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminGiftCardsListRes' + '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: PostGiftCards + summary: Create a Gift Card + description: >- + Create a Gift Card that can redeemed by its unique code. The Gift Card + is only valid within 1 region. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostGiftCardsReq' + 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 }) + + // must be previously logged in or use api token + + medusa.admin.giftCards.create({ + region_id + }) + + .then(({ gift_card }) => { + console.log(gift_card.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/gift-cards' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "region_id": "{region_id}" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Gift Cards + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminGiftCardsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/gift-cards/{id}: + get: + operationId: GetGiftCardsGiftCard + summary: Get a Gift Card + description: Retrieve a Gift Card's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Gift Card. + schema: + type: string + x-codegen: + method: retrieve + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.giftCards.retrieve(giftCardId) + + .then(({ gift_card }) => { + console.log(gift_card.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/gift-cards/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Gift Cards + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminGiftCardsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostGiftCardsGiftCard + summary: Update a Gift Card + description: Update a Gift Card's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Gift Card. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostGiftCardsGiftCardReq' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.giftCards.update(giftCardId, { + region_id + }) + + .then(({ gift_card }) => { + console.log(gift_card.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/gift-cards/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "region_id": "{region_id}" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Gift Cards + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminGiftCardsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteGiftCardsGiftCard + summary: Delete a Gift Card + description: Delete a Gift Card. Once deleted, it can't be used by customers. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Gift Card to delete. + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.giftCards.delete(giftCardId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/gift-cards/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Gift Cards + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminGiftCardsDeleteRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/inventory-items: + get: + operationId: GetInventoryItems + summary: List Inventory Items + description: >- + Retrieve a list of inventory items. The inventory items can be filtered + by fields such as `q` or `location_id`. The inventory items can also be + paginated. + x-authenticated: true + parameters: + - in: query + name: offset + description: >- + The number of inventory items to skip when retrieving the inventory + items. + schema: + type: integer + default: 0 + - in: query + name: limit + description: Limit the number of inventory items returned. + schema: + type: integer + default: 20 + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in each returned + inventory item. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + inventory item. + schema: + type: string + - in: query + name: q + description: term to search inventory item's sku, title, and description. + schema: + type: string + - in: query + name: location_id + style: form + explode: false + description: Filter by location IDs. + schema: + type: array + items: + type: string + - in: query + name: id + style: form + explode: false + description: Filter by the inventory ID + schema: + oneOf: + - type: string + description: inventory ID + - type: array + description: an array of inventory IDs + items: + type: string + - in: query + name: sku + description: Filter by SKU + schema: + type: string + - in: query + name: origin_country + description: Filter by origin country + schema: + type: string + - in: query + name: mid_code + description: Filter by MID code + schema: + type: string + - in: query + name: material + description: Filter by material + schema: + type: string + - in: query + name: hs_code + description: Filter by HS Code + schema: + type: string + - in: query + name: weight + description: Filter by weight + schema: + type: string + - in: query + name: length + description: Filter by length + schema: + type: string + - in: query + name: height + description: Filter by height + schema: + type: string + - in: query + name: width + description: Filter by width + schema: + type: string + - in: query + name: requires_shipping + description: Filter by whether the item requires shipping + schema: + type: string + x-codegen: + method: list + queryParams: AdminGetInventoryItemsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.inventoryItems.list() + + .then(({ inventory_items, count, offset, limit }) => { + console.log(inventory_items.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/inventory-items' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Inventory Items + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminInventoryItemsListWithVariantsAndLocationLevelsRes + '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: PostInventoryItems + summary: Create an Inventory Item + description: Create an Inventory Item for a product variant. + x-authenticated: true + parameters: + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + inventory item. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + inventory item. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostInventoryItemsReq' + x-codegen: + method: create + queryParams: AdminPostInventoryItemsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.inventoryItems.create({ + variant_id: "variant_123", + }) + + .then(({ inventory_item }) => { + console.log(inventory_item.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/inventory-items' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "variant_id": "variant_123", + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Inventory Items + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminInventoryItemsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/inventory-items/{id}: + get: + operationId: GetInventoryItemsInventoryItem + summary: Get an Inventory Item + description: Retrieve an Inventory Item's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Inventory Item. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + inventory item. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + inventory item. + schema: + type: string + x-codegen: + method: retrieve + queryParams: AdminGetInventoryItemsItemParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.inventoryItems.retrieve(inventoryItemId) + + .then(({ inventory_item }) => { + console.log(inventory_item.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/inventory-items/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Inventory Items + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminInventoryItemsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostInventoryItemsInventoryItem + summary: Update an Inventory Item + description: Update an Inventory Item's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Inventory Item. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + inventory level. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + inventory level. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostInventoryItemsInventoryItemReq' + x-codegen: + method: update + queryParams: AdminPostInventoryItemsInventoryItemParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.inventoryItems.update(inventoryItemId, { + origin_country: "US", + }) + + .then(({ inventory_item }) => { + console.log(inventory_item.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/inventory-items/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "origin_country": "US" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Inventory Items + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminInventoryItemsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteInventoryItemsInventoryItem + summary: Delete an Inventory Item + description: >- + Delete an Inventory Item. This does not delete the associated product + variant. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Inventory Item to delete. + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.inventoryItems.delete(inventoryItemId) + .then(({ id, object, deleted }) => { + console.log(id) + }) + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/inventory-items/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Inventory Items + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminInventoryItemsDeleteRes' + '400': + $ref: '#/components/responses/400_error' + /admin/inventory-items/{id}/location-levels: + get: + operationId: GetInventoryItemsInventoryItemLocationLevels + summary: List Inventory Level + description: >- + Retrieve a list of inventory levels of an inventory item. The inventory + levels can be filtered by fields such as `location_id`. The inventory + levels can also be paginated. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Inventory Item the locations are associated with. + schema: + type: string + - in: query + name: location_id + style: form + explode: false + description: Filter by location IDs. + schema: + type: array + items: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + inventory levels. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + inventory levels. + schema: + type: string + x-codegen: + method: listLocationLevels + queryParams: AdminGetInventoryItemsItemLocationLevelsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.inventoryItems.listLocationLevels(inventoryItemId) + + .then(({ inventory_item }) => { + console.log(inventory_item.location_levels); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/inventory-items/{id}/location-levels' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Inventory Items + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminInventoryItemsLocationLevelsRes' + '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: PostInventoryItemsInventoryItemLocationLevels + summary: Create an Location Level + description: Create an Location Level for a given Inventory Item. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Inventory Item. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + inventory item. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + inventory item. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminPostInventoryItemsItemLocationLevelsReq + x-codegen: + method: createLocationLevel + queryParams: AdminPostInventoryItemsItemLocationLevelsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.inventoryItems.createLocationLevel(inventoryItemId, { + location_id: "sloc_123", + stocked_quantity: 10, + }) + + .then(({ inventory_item }) => { + console.log(inventory_item.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/inventory-items/{id}/location-levels' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "location_id": "sloc_123", + "stocked_quantity": 10 + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Inventory Items + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminInventoryItemsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/inventory-items/{id}/location-levels/{location_id}: + post: + operationId: PostInventoryItemsInventoryItemLocationLevelsLocationLevel + summary: Update a Location Level + description: Update a Location Level's details for a given Inventory Item. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Inventory Item that the location is associated with. + schema: + type: string + - in: path + name: location_id + required: true + description: The ID of the Location to update. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + location level. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + location level. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminPostInventoryItemsItemLocationLevelsLevelReq + x-codegen: + method: updateLocationLevel + queryParams: AdminPostInventoryItemsItemLocationLevelsLevelParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.inventoryItems.updateLocationLevel(inventoryItemId, + locationId, { + stocked_quantity: 15, + }) + + .then(({ inventory_item }) => { + console.log(inventory_item.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/inventory-items/{id}/location-levels/{location_id}' + \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "stocked_quantity": 15 + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Inventory Items + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminInventoryItemsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteInventoryItemsInventoryIteLocationLevelsLocation + summary: Delete a Location Level + description: Delete a location level of an Inventory Item. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Inventory Item. + schema: + type: string + - in: path + name: location_id + required: true + description: The ID of the location. + schema: + type: string + x-codegen: + method: deleteLocationLevel + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.inventoryItems.deleteLocationLevel(inventoryItemId, + locationId) + + .then(({ inventory_item }) => { + console.log(inventory_item.id); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/inventory-items/{id}/location-levels/{location_id}' + \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Inventory Items + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminInventoryItemsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/invites: + get: + operationId: GetInvites + summary: Lists Invites + description: Retrieve a list of invites. + x-authenticated: true + x-codegen: + method: list + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.invites.list() + + .then(({ invites }) => { + console.log(invites.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/invites' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Invites + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminListInvitesRes' + '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: PostInvites + summary: Create an Invite + description: >- + Create an Invite. This will generate a token associated with the invite + and trigger an `invite.created` event. If you have a Notification + Provider installed that handles this event, a notification should be + sent to the email associated with the invite to allow them to accept the + invite. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostInvitesReq' + 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 }) + + // must be previously logged in or use api token + + medusa.admin.invites.create({ + user: "user@example.com", + role: "admin" + }) + + .then(() => { + // successful + }) + + .catch(() => { + // an error occurred + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/invites' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "user": "user@example.com", + "role": "admin" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Invites + responses: + '200': + description: OK + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/invites/accept: + post: + operationId: PostInvitesInviteAccept + summary: Accept an Invite + description: >- + Accept an Invite. This will also delete the invite and create a new user + that can log in and perform admin functionalities. The user will have + the email associated with the invite, and the password provided in the + request body. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostInvitesInviteAcceptReq' + x-codegen: + method: accept + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.invites.accept({ + token, + user: { + first_name: "Brigitte", + last_name: "Collier", + password: "supersecret" + } + }) + + .then(() => { + // successful + }) + + .catch(() => { + // an error occurred + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/invites/accept' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "token": "{token}", + "user": { + "first_name": "Brigitte", + "last_name": "Collier", + "password": "supersecret" + } + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Invites + responses: + '200': + description: OK + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/invites/{invite_id}: + delete: + operationId: DeleteInvitesInvite + summary: Delete an Invite + description: Delete an Invite. Only invites that weren't accepted can be deleted. + x-authenticated: true + parameters: + - in: path + name: invite_id + required: true + description: The ID of the Invite + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.invites.delete(inviteId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/invites/{invite_id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Invites + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminInviteDeleteRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/invites/{invite_id}/resend: + post: + operationId: PostInvitesInviteResend + summary: Resend an Invite + description: >- + Resend an Invite. This renews the expiry date by 7 days and generates a + new token for the invite. It also triggers the `invite.created` event, + so if you have a Notification Provider installed that handles this + event, a notification should be sent to the email associated with the + invite to allow them to accept the invite. + x-authenticated: true + parameters: + - in: path + name: invite_id + required: true + description: The ID of the Invite + schema: + type: string + x-codegen: + method: resend + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.invites.resend(inviteId) + + .then(() => { + // successful + }) + + .catch(() => { + // an error occurred + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/invites/{invite_id}/resend' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Invites + responses: + '200': + description: OK + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/notes: + get: + operationId: GetNotes + summary: List Notes + x-authenticated: true + description: >- + Retrieve a list of notes. The notes can be filtered by fields such as + `resource_id`. The notes can also be paginated. + parameters: + - in: query + name: limit + description: Limit the number of notes returned. + schema: + type: number + default: '50' + - in: query + name: offset + description: The number of notes to skip when retrieving the notes. + schema: + type: number + default: '0' + - in: query + name: resource_id + description: Filter by resource ID + schema: + type: string + x-codegen: + method: list + queryParams: AdminGetNotesParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.notes.list() + + .then(({ notes, limit, offset, count }) => { + console.log(notes.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/notes' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Notes + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminNotesListRes' + '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: PostNotes + summary: Create a Note + description: Create a Note which can be associated with any resource. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostNotesReq' + 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 }) + + // must be previously logged in or use api token + + medusa.admin.notes.create({ + resource_id, + resource_type: "order", + value: "We delivered this order" + }) + + .then(({ note }) => { + console.log(note.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/notes' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "resource_id": "{resource_id}", + "resource_type": "order", + "value": "We delivered this order" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Notes + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminNotesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/notes/{id}: + get: + operationId: GetNotesNote + summary: Get a Note + description: Retrieve a note's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the note. + 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 }) + + // must be previously logged in or use api token + + medusa.admin.notes.retrieve(noteId) + + .then(({ note }) => { + console.log(note.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/notes/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Notes + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminNotesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostNotesNote + summary: Update a Note + x-authenticated: true + description: Update a Note's details.' + parameters: + - in: path + name: id + required: true + description: The ID of the Note + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostNotesNoteReq' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.notes.update(noteId, { + value: "We delivered this order" + }) + + .then(({ note }) => { + console.log(note.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/notes/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "value": "We delivered this order" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Notes + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminNotesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteNotesNote + summary: Delete a Note + description: Delete a Note. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Note to delete. + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.notes.delete(noteId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/notes/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Notes + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminNotesDeleteRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/notifications: + get: + operationId: GetNotifications + summary: List Notifications + description: >- + Retrieve a list of notifications. The notifications can be filtered by + fields such as `event_name` or `resource_type`. The notifications can + also be paginated. + x-authenticated: true + parameters: + - in: query + name: offset + description: >- + The number of inventory items to skip when retrieving the inventory + items. + schema: + type: integer + default: 0 + - in: query + name: limit + description: Limit the number of notifications returned. + schema: + type: integer + default: 50 + - in: query + name: fields + description: >- + Comma-separated fields that should be included in each returned + notification. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in each returned + notification. + schema: + type: string + - in: query + name: event_name + description: >- + Filter by the name of the event that triggered sending this + notification. + schema: + type: string + - in: query + name: resource_type + description: Filter by the resource type. + schema: + type: string + - in: query + name: resource_id + description: Filter by the resource ID. + schema: + type: string + - in: query + name: to + description: >- + Filter by the address that the Notification was sent to. This will + usually be an email address, but it can also represent other + addresses such as a chat bot user id. + schema: + type: string + - in: query + name: include_resends + description: >- + A boolean indicating whether the result set should include resent + notifications or not + schema: + type: string + x-codegen: + method: list + queryParams: AdminGetNotificationsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.notifications.list() + + .then(({ notifications }) => { + console.log(notifications.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/notifications' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Notifications + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminNotificationsListRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/notifications/{id}/resend: + post: + operationId: PostNotificationsNotificationResend + summary: Resend Notification + description: >- + Resend a previously sent notifications, with the same data but + optionally to a different address. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Notification + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostNotificationsNotificationResendReq' + x-codegen: + method: resend + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.notifications.resend(notificationId) + + .then(({ notification }) => { + console.log(notification.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/notifications/{id}/resend' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Notifications + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminNotificationsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/order-edits: + get: + operationId: GetOrderEdits + summary: List Order Edits + description: >- + Retrieve a list of order edits. The order edits can be filtered by + fields such as `q` or `order_id`. The order edits can also be paginated. + x-authenticated: true + parameters: + - in: query + name: q + description: term to search order edits' internal note. + schema: + type: string + - in: query + name: order_id + description: Filter by order ID + schema: + type: string + - in: query + name: limit + description: Limit the number of order edits returned. + schema: + type: number + default: '20' + - in: query + name: offset + description: The number of order edits to skip when retrieving the order edits. + schema: + type: number + default: '0' + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in each returned + order edit. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in each returned + order edit. + schema: + type: string + x-codegen: + method: list + queryParams: GetOrderEditsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orderEdits.list() + .then(({ order_edits, count, limit, offset }) => { + console.log(order_edits.length) + }) + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/order-edits' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Order Edits + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrderEditsListRes' + '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: PostOrderEdits + summary: Create an OrderEdit + description: Create an Order Edit. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostOrderEditsReq' + x-authenticated: true + 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 }) + + // must be previously logged in or use api token + + medusa.admin.orderEdits.create({ orderId }) + .then(({ order_edit }) => { + console.log(order_edit.id) + }) + - lang: Shell + label: cURL + source: > + curl -X POST '{backend_url}/admin/order-edits' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ "order_id": "my_order_id", "internal_note": + "my_optional_note" }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Order Edits + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrderEditsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/order-edits/{id}: + get: + operationId: GetOrderEditsOrderEdit + summary: Get an Order Edit + description: Retrieve an Order Edit's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the OrderEdit. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in each returned + order edit. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned order + edit. + schema: + type: string + x-codegen: + method: retrieve + queryParams: GetOrderEditsOrderEditParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orderEdits.retrieve(orderEditId) + .then(({ order_edit }) => { + console.log(order_edit.id) + }) + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/order-edits/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Order Edits + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrderEditsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostOrderEditsOrderEdit + summary: Update an Order Edit + description: Updates an Order Edit's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the OrderEdit. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostOrderEditsOrderEditReq' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orderEdits.update(orderEditId, { + internal_note: "internal reason XY" + }) + .then(({ order_edit }) => { + console.log(order_edit.id) + }) + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/order-edits/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "internal_note": "internal reason XY" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Order Edits + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrderEditsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteOrderEditsOrderEdit + summary: Delete an Order Edit + description: >- + Delete an Order Edit. Only order edits that have the status `created` + can be deleted. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Order Edit to delete. + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orderEdits.delete(orderEditId) + .then(({ id, object, deleted }) => { + console.log(id) + }) + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/order-edits/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Order Edits + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrderEditDeleteRes' + '400': + $ref: '#/components/responses/400_error' + /admin/order-edits/{id}/cancel: + post: + operationId: PostOrderEditsOrderEditCancel + summary: Cancel an Order Edit + description: Cancel an OrderEdit. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the OrderEdit. + schema: + type: string + x-codegen: + method: cancel + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orderEdits.cancel(orderEditId) + .then(({ order_edit }) => { + console.log(order_edit.id) + }) + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/order-edits/{id}/cancel' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Order Edits + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrderEditsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '500': + $ref: '#/components/responses/500_error' + /admin/order-edits/{id}/changes/{change_id}: + delete: + operationId: DeleteOrderEditsOrderEditItemChange + summary: Delete a Line Item Change + description: >- + Delete a line item change that indicates the addition, deletion, or + update of a line item in the original order. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Order Edit. + schema: + type: string + - in: path + name: change_id + required: true + description: The ID of the Line Item Change to delete. + schema: + type: string + x-codegen: + method: deleteItemChange + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orderEdits.deleteItemChange(orderEdit_id, itemChangeId) + .then(({ id, object, deleted }) => { + console.log(id) + }) + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/order-edits/{id}/changes/{change_id}' \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Order Edits + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrderEditItemChangeDeleteRes' + '400': + $ref: '#/components/responses/400_error' + /admin/order-edits/{id}/confirm: + post: + operationId: PostOrderEditsOrderEditConfirm + summary: Confirm an OrderEdit + description: >- + Confirm an Order Edit. This will reflect the changes in the order edit + on the associated order. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the order edit. + schema: + type: string + x-codegen: + method: confirm + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orderEdits.confirm(orderEditId) + .then(({ order_edit }) => { + console.log(order_edit.id) + }) + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/order-edits/{id}/confirm' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Order Edits + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrderEditsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '500': + $ref: '#/components/responses/500_error' + /admin/order-edits/{id}/items: + post: + operationId: PostOrderEditsEditLineItems + summary: Add a Line Item + description: >- + Create a line item change in the order edit that indicates adding an + item in the original order. The item will not be added to the original + order until the order edit is confirmed. + parameters: + - in: path + name: id + required: true + description: The ID of the Order Edit. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostOrderEditsEditLineItemsReq' + x-authenticated: true + x-codegen: + method: addLineItem + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orderEdits.addLineItem(orderEditId, { + variant_id, + quantity + }) + + .then(({ order_edit }) => { + console.log(order_edit.id) + }) + - lang: Shell + label: cURL + source: > + curl -X POST '{backend_url}/admin/order-edits/{id}/items' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6", + "quantity": 3 }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Order Edits + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrderEditsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/order-edits/{id}/items/{item_id}: + post: + operationId: PostOrderEditsEditLineItemsLineItem + summary: Upsert Line Item Change + description: >- + Create or update a line item change in the order edit that indicates + addition, deletion, or update of a line item into an original order. + Line item changes are only reflected on the original order after the + order edit is confirmed. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Order Edit. + schema: + type: string + - in: path + name: item_id + required: true + description: The ID of the line item in the original order. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostOrderEditsEditLineItemsLineItemReq' + x-codegen: + method: updateLineItem + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orderEdits.updateLineItem(orderEditId, lineItemId, { + quantity: 5 + }) + .then(({ order_edit }) => { + console.log(order_edit.id) + }) + - lang: Shell + label: cURL + source: > + curl -X POST '{backend_url}/admin/order-edits/{id}/items/{item_id}' + \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ "quantity": 5 }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Order Edits + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrderEditsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteOrderEditsOrderEditLineItemsLineItem + summary: Delete Line Item + description: >- + Create a line item change in the order edit that indicates deleting an + item in the original order. The item in the original order will not be + deleted until the order edit is confirmed. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Order Edit. + schema: + type: string + - in: path + name: item_id + required: true + description: The ID of line item in the original order. + schema: + type: string + x-codegen: + method: removeLineItem + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orderEdits.removeLineItem(orderEditId, lineItemId) + .then(({ order_edit }) => { + console.log(order_edit.id) + }) + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/order-edits/{id}/items/{item_id}' \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Order Edits + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrderEditsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/order-edits/{id}/request: + post: + operationId: PostOrderEditsOrderEditRequest + summary: Request Confirmation + description: >- + Request customer confirmation of an Order Edit. This would emit the + event `order-edit.requested` which Notification Providers listen to and + send a notification to the customer about the order edit. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Order Edit. + schema: + type: string + x-codegen: + method: requestConfirmation + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orderEdits.requestConfirmation(orderEditId) + .then({ order_edit }) => { + console.log(order_edit.id) + }) + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/order-edits/{id}/request' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Order Edits + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrderEditsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders: + get: + operationId: GetOrders + summary: List Orders + description: >- + Retrieve a list of Orders. The orders can be filtered by fields such as + `status` or `display_id`. The order can also be paginated. + x-authenticated: true + parameters: + - in: query + name: q + description: >- + term to search orders' shipping address, first name, email, and + display ID + schema: + type: string + - in: query + name: id + description: Filter by ID. + schema: + type: string + - in: query + name: status + style: form + explode: false + description: Filter by status + schema: + type: array + items: + type: string + enum: + - pending + - completed + - archived + - canceled + - requires_action + - in: query + name: fulfillment_status + style: form + explode: false + description: Filter by fulfillment status + schema: + type: array + items: + type: string + enum: + - not_fulfilled + - fulfilled + - partially_fulfilled + - shipped + - partially_shipped + - canceled + - returned + - partially_returned + - requires_action + - in: query + name: payment_status + style: form + explode: false + description: Filter by payment status + schema: + type: array + items: + type: string + enum: + - captured + - awaiting + - not_paid + - refunded + - partially_refunded + - canceled + - requires_action + - in: query + name: display_id + description: Filter by display ID + schema: + type: string + - in: query + name: cart_id + description: Filter by cart ID + schema: + type: string + - in: query + name: customer_id + description: Filter by customer ID + schema: + type: string + - in: query + name: email + description: Filter by email + schema: + type: string + - in: query + name: region_id + style: form + explode: false + description: Filter by region IDs. + schema: + oneOf: + - type: string + description: ID of a Region. + - type: array + items: + type: string + description: ID of a Region. + - in: query + name: currency_code + style: form + explode: false + description: Filter by currency codes. + schema: + type: string + externalDocs: + url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes + description: See a list of codes. + - in: query + name: tax_rate + description: Filter by tax rate. + schema: + type: string + - in: query + name: created_at + description: Filter by a creation date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: updated_at + description: Filter by an update date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: canceled_at + description: Filter by a cancelation date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: sales_channel_id + style: form + explode: false + description: Filter by Sales Channel IDs + schema: + type: array + items: + type: string + description: The ID of a Sales Channel + - in: query + name: offset + description: The number of orders to skip when retrieving the orders. + schema: + type: integer + default: 0 + - in: query + name: limit + description: Limit the number of orders returned. + schema: + type: integer + default: 50 + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + x-codegen: + method: list + queryParams: AdminGetOrdersParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.list() + + .then(({ orders, limit, offset, count }) => { + console.log(orders.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/orders' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersListRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}: + get: + operationId: GetOrdersOrder + summary: Get an Order + description: Retrieve an Order's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Order. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + x-codegen: + method: retrieve + queryParams: AdminGetOrdersOrderParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.retrieve(orderId) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/orders/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostOrdersOrder + summary: Update an Order + description: Update and order's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Order. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostOrdersOrderReq' + x-codegen: + method: update + params: AdminPostOrdersOrderParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.update(orderId, { + email: "user@example.com" + }) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/orders/adasda' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "email": "user@example.com" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/archive: + post: + operationId: PostOrdersOrderArchive + summary: Archive Order + description: Archive an order and change its status. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Order. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + x-codegen: + method: archive + params: AdminPostOrdersOrderArchiveParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.archive(orderId) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/orders/{id}/archive' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/cancel: + post: + operationId: PostOrdersOrderCancel + summary: Cancel an Order + description: >- + Cancel an order and change its status. This will also cancel any + associated Fulfillments and Payments, and it may fail if the Payment or + Fulfillment Provider is unable to cancel the Payment/Fulfillment. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Order. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + x-codegen: + method: cancel + params: AdminPostOrdersOrderCancel + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.cancel(orderId) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/orders/{id}/cancel' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/capture: + post: + operationId: PostOrdersOrderCapture + summary: Capture an Order's Payments + description: >- + Capture all the Payments associated with an Order. The payment of + canceled orders can't be captured. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Order. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + x-codegen: + method: capturePayment + params: AdminPostOrdersOrderCaptureParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.capturePayment(orderId) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/orders/{id}/capture' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/claims: + post: + operationId: PostOrdersOrderClaims + summary: Create a Claim + description: >- + Create a Claim for an order. If a return shipping method is specified, a + return will also be created and associated with the claim. If the + claim's type is `refund`, the refund is processed as well. + externalDocs: + description: How are claims created + url: https://docs.medusajs.com/modules/orders/claims#how-are-claims-created + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Order. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostOrdersOrderClaimsReq' + x-codegen: + method: createClaim + params: AdminPostOrdersOrderClaimsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.createClaim(orderId, { + type: 'refund', + claim_items: [ + { + item_id, + quantity: 1 + } + ] + }) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/orders/{id}/claims' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "type": "refund", + "claim_items": [ + { + "item_id": "asdsd", + "quantity": 1 + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/claims/{claim_id}: + post: + operationId: PostOrdersOrderClaimsClaim + summary: Update a Claim + description: Update a Claim's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Order associated with the claim. + schema: + type: string + - in: path + name: claim_id + required: true + description: The ID of the Claim. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostOrdersOrderClaimsClaimReq' + x-codegen: + method: updateClaim + params: AdminPostOrdersOrderClaimsClaimParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.updateClaim(orderId, claimId, { + no_notification: true + }) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/orders/{id}/claims/{claim_id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "no_notification": true + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/claims/{claim_id}/cancel: + post: + operationId: PostOrdersClaimCancel + summary: Cancel a Claim + description: >- + Cancel a Claim and change its status. A claim can't be canceled if it + has a refund, if its fulfillments haven't been canceled, of if its + associated return hasn't been canceled. + x-authenticated: true + externalDocs: + description: Canceling a claim + url: https://docs.medusajs.com/modules/orders/claims#cancel-a-claim + parameters: + - in: path + name: id + required: true + description: The ID of the order the claim is associated with. + schema: + type: string + - in: path + name: claim_id + required: true + description: The ID of the Claim. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + x-codegen: + method: cancelClaim + params: AdminPostOrdersClaimCancel + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.cancelClaim(orderId, claimId) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/orders/{id}/claims/{claim_id}/cancel' \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/claims/{claim_id}/fulfillments: + post: + operationId: PostOrdersOrderClaimsClaimFulfillments + summary: Create a Claim Fulfillment + description: Create a Fulfillment for a Claim. + x-authenticated: true + externalDocs: + description: Fulfill a claim + url: https://docs.medusajs.com/modules/orders/claims#fulfill-a-claim + parameters: + - in: path + name: id + required: true + description: The ID of the Order the claim is associated with. + schema: + type: string + - in: path + name: claim_id + required: true + description: The ID of the Claim. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminPostOrdersOrderClaimsClaimFulfillmentsReq + x-codegen: + method: fulfillClaim + params: AdminPostOrdersOrderClaimsClaimFulfillmentsReq + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.fulfillClaim(orderId, claimId, { + + }) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/orders/{id}/claims/{claim_id}/fulfillments' \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/claims/{claim_id}/fulfillments/{fulfillment_id}/cancel: + post: + operationId: PostOrdersClaimFulfillmentsCancel + summary: Cancel Claim's Fulfillment + description: Cancel a claim's fulfillment and change its status. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the order the claim is associated with. + schema: + type: string + - in: path + name: claim_id + required: true + description: The ID of the claim. + schema: + type: string + - in: path + name: fulfillment_id + required: true + description: The ID of the fulfillment. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + x-codegen: + method: cancelClaimFulfillment + params: AdminPostOrdersClaimFulfillmentsCancelParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.cancelClaimFulfillment(orderId, claimId, + fulfillmentId) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/orders/{id}/claims/{claim_id}/fulfillments/{fulfillment_id}/cancel' + \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/claims/{claim_id}/shipments: + post: + operationId: PostOrdersOrderClaimsClaimShipments + summary: Ship a Claim's Fulfillment + description: >- + Mark a claim's fulfillment as shipped. This changes the claim's + fulfillment status to either `shipped` or `partially_shipped`, depending + on whether all the items were shipped. + x-authenticated: true + externalDocs: + description: Fulfill a claim + url: https://docs.medusajs.com/modules/orders/claims#fulfill-a-claim + parameters: + - in: path + name: id + required: true + description: The ID of the Order the claim is associated with. + schema: + type: string + - in: path + name: claim_id + required: true + description: The ID of the Claim. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostOrdersOrderClaimsClaimShipmentsReq' + x-codegen: + method: createClaimShipment + params: AdminPostOrdersOrderClaimsClaimShipmentsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.createClaimShipment(orderId, claimId, { + fulfillment_id + }) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/orders/{id}/claims/{claim_id}/shipments' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "fulfillment_id": "{fulfillment_id}" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/complete: + post: + operationId: PostOrdersOrderComplete + summary: Complete an Order + description: >- + Complete an Order and change its status. A canceled order can't be + completed. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Order. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + x-codegen: + method: complete + params: AdminPostOrdersOrderCompleteParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.complete(orderId) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/orders/{id}/complete' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/fulfillment: + post: + operationId: PostOrdersOrderFulfillments + summary: Create a Fulfillment + description: Create a Fulfillment of an Order using the fulfillment provider. + x-authenticated: true + externalDocs: + description: Fulfillments of orders + url: https://docs.medusajs.com/modules/orders/#fulfillments-in-orders + parameters: + - in: path + name: id + required: true + description: The ID of the Order. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostOrdersOrderFulfillmentsReq' + x-codegen: + method: createFulfillment + params: AdminPostOrdersOrderFulfillmentsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.createFulfillment(orderId, { + items: [ + { + item_id, + quantity: 1 + } + ] + }) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/orders/{id}/fulfillment' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "items": [ + { + "item_id": "{item_id}", + "quantity": 1 + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/fulfillments/{fulfillment_id}/cancel: + post: + operationId: PostOrdersOrderFulfillmentsCancel + summary: Cancel a Fulfilmment + description: Cancel an order's fulfillment and change its status. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Order. + schema: + type: string + - in: path + name: fulfillment_id + required: true + description: The ID of the Fulfillment. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + x-codegen: + method: cancelFulfillment + params: AdminPostOrdersOrderFulfillementsCancelParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.cancelFulfillment(orderId, fulfillmentId) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/orders/{id}/fulfillments/{fulfillment_id}/cancel' + \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/line-items/{line_item_id}/reserve: + post: + operationId: PostOrdersOrderLineItemReservations + summary: Create a Reservation + description: >- + Create a Reservation for a line item at a specified location, optionally + for a partial quantity. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Order. + schema: + type: string + - in: path + name: line_item_id + required: true + description: The ID of the Line item. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersOrderLineItemReservationReq' + x-codeSamples: + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/orders/{id}/line-items/{line_item_id}/reserve' + \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "location_id": "loc_1" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostReservationsReq' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/refund: + post: + operationId: PostOrdersOrderRefunds + summary: Create a Refund + description: >- + Refund an amount for an order. The amount must be less than or equal the + `refundable_amount` of the order. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Order. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostOrdersOrderRefundsReq' + x-codegen: + method: refundPayment + params: AdminPostOrdersOrderRefundsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.refundPayment(orderId, { + amount: 1000, + reason: "Do not like it" + }) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/orders/adasda/refund' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "amount": 1000, + "reason": "Do not like it" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/reservations: + get: + operationId: GetOrdersOrderReservations + summary: Get Order Reservations + description: Retrieve the list of reservations of an Order + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Order. + schema: + type: string + - in: query + name: offset + description: The number of reservations to skip when retrieving the reservations. + schema: + type: integer + default: 0 + - in: query + name: limit + description: Limit the number of reservations returned. + schema: + type: integer + default: 20 + x-codeSamples: + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/orders/{id}/reservations' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminReservationsListRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/return: + post: + operationId: PostOrdersOrderReturns + summary: Request a Return + description: >- + Request and create a Return for items in an order. If the return + shipping method is specified, it will be automatically fulfilled. + x-authenticated: true + externalDocs: + description: Return creation process + url: https://docs.medusajs.com/modules/orders/returns#returns-process + parameters: + - in: path + name: id + required: true + description: The ID of the Order. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostOrdersOrderReturnsReq' + x-codegen: + method: requestReturn + params: AdminPostOrdersOrderReturnsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.requestReturn(orderId, { + items: [ + { + item_id, + quantity: 1 + } + ] + }) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/orders/{id}/return' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "items": [ + { + "item_id": "{item_id}", + "quantity": 1 + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/shipment: + post: + operationId: PostOrdersOrderShipment + summary: Ship a Fulfillment + description: >- + Mark a fulfillment as shipped. This changes the order's fulfillment + status to either `shipped` or `partially_shipped`, depending on whether + all the items were shipped. + x-authenticated: true + externalDocs: + description: Fulfillments of orders + url: https://docs.medusajs.com/modules/orders/#fulfillments-in-orders + parameters: + - in: path + name: id + required: true + description: The ID of the Order. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostOrdersOrderShipmentReq' + x-codegen: + method: createShipment + params: AdminPostOrdersOrderShipmentParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.createShipment(order_id, { + fulfillment_id + }) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/orders/{id}/shipment' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "fulfillment_id": "{fulfillment_id}" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/shipping-methods: + post: + operationId: PostOrdersOrderShippingMethods + summary: Add a Shipping Method + description: >- + Adds a Shipping Method to an Order. If another Shipping Method exists + with the same Shipping Profile, the previous Shipping Method will be + replaced. + parameters: + - in: path + name: id + required: true + description: The ID of the Order. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostOrdersOrderShippingMethodsReq' + x-authenticated: true + x-codegen: + method: addShippingMethod + params: AdminPostOrdersOrderShippingMethodsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.addShippingMethod(orderId, { + price: 1000, + option_id + }) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/orders/{id}/shipping-methods' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "price": 1000, + "option_id": "{option_id}" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/swaps: + post: + operationId: PostOrdersOrderSwaps + summary: Create a Swap + description: >- + Create a Swap. This includes creating a return that is associated with + the swap. + x-authenticated: true + externalDocs: + description: How are swaps created + url: https://docs.medusajs.com/modules/orders/swaps#how-are-swaps-created + parameters: + - in: path + name: id + required: true + description: The ID of the Order. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostOrdersOrderSwapsReq' + x-codegen: + method: createSwap + queryParams: AdminPostOrdersOrderSwapsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.createSwap(orderId, { + return_items: [ + { + item_id, + quantity: 1 + } + ] + }) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/orders/{id}/swaps' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "return_items": [ + { + "item_id": "asfasf", + "quantity": 1 + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/swaps/{swap_id}/cancel: + post: + operationId: PostOrdersSwapCancel + summary: Cancel a Swap + description: Cancel a Swap and change its status. + x-authenticated: true + externalDocs: + description: Canceling a swap + url: https://docs.medusajs.com/modules/orders/swaps#canceling-a-swap + parameters: + - in: path + name: id + required: true + description: The ID of the Order the swap is associated with. + schema: + type: string + - in: path + name: swap_id + required: true + description: The ID of the Swap. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + x-codegen: + method: cancelSwap + params: AdminPostOrdersSwapCancelParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.cancelSwap(orderId, swapId) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/orders/{order_id}/swaps/{swap_id}/cancel' \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/swaps/{swap_id}/fulfillments: + post: + operationId: PostOrdersOrderSwapsSwapFulfillments + summary: Create a Swap Fulfillment + description: Create a Fulfillment for a Swap. + x-authenticated: true + externalDocs: + description: Handling a swap's fulfillment + url: >- + https://docs.medusajs.com/modules/orders/swaps#handling-swap-fulfillment + parameters: + - in: path + name: id + required: true + description: The ID of the Order the swap is associated with. + schema: + type: string + - in: path + name: swap_id + required: true + description: The ID of the Swap. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminPostOrdersOrderSwapsSwapFulfillmentsReq + x-codegen: + method: fulfillSwap + params: AdminPostOrdersOrderSwapsSwapFulfillmentsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.fulfillSwap(orderId, swapId, { + + + }) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/orders/{id}/swaps/{swap_id}/fulfillments' \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/swaps/{swap_id}/fulfillments/{fulfillment_id}/cancel: + post: + operationId: PostOrdersSwapFulfillmentsCancel + summary: Cancel Swap's Fulfilmment + description: Cancel a swap's fulfillment and change its status. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the order the swap is associated with. + schema: + type: string + - in: path + name: swap_id + required: true + description: The ID of the swap. + schema: + type: string + - in: path + name: fulfillment_id + required: true + description: The ID of the fulfillment. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + x-codegen: + method: cancelSwapFulfillment + params: AdminPostOrdersSwapFulfillementsCancelParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.cancelSwapFulfillment(orderId, swapId, + fulfillmentId) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/orders/{id}/swaps/{swap_id}/fulfillments/{fulfillment_id}/cancel' + \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/swaps/{swap_id}/process-payment: + post: + operationId: PostOrdersOrderSwapsSwapProcessPayment + summary: Process a Swap Payment + description: >- + Process a swap's payment either by refunding or issuing a payment. This + depends on the `difference_due` of the swap. If `difference_due` is + negative, the amount is refunded. If `difference_due` is positive, the + amount is captured. + x-authenticated: true + externalDocs: + description: Handling a swap's payment + url: https://docs.medusajs.com/modules/orders/swaps#handling-swap-payment + parameters: + - in: path + name: id + required: true + description: The ID of the order the swap is associated with. + schema: + type: string + - in: path + name: swap_id + required: true + description: The ID of the swap. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + x-codegen: + method: processSwapPayment + params: AdminPostOrdersOrderSwapsSwapProcessPaymentParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.processSwapPayment(orderId, swapId) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/orders/{id}/swaps/{swap_id}/process-payment' \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/orders/{id}/swaps/{swap_id}/shipments: + post: + operationId: PostOrdersOrderSwapsSwapShipments + summary: Ship a Swap's Fulfillment + description: >- + RMark a swap's fulfillment as shipped. This changes the swap's + fulfillment status to either `shipped` or `partially_shipped`, depending + on whether all the items were shipped. + x-authenticated: true + externalDocs: + description: Handling swap fulfillments + url: >- + https://docs.medusajs.com/modules/orders/swaps#handling-swap-fulfillment + parameters: + - in: path + name: id + required: true + description: The ID of the Order. + schema: + type: string + - in: path + name: swap_id + required: true + description: The ID of the Swap. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + order. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + order. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostOrdersOrderSwapsSwapShipmentsReq' + x-codegen: + method: createSwapShipment + params: AdminPostOrdersOrderSwapsSwapShipmentsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.orders.createSwapShipment(order_id, swap_id, { + fulfillment_id + }) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/orders/{id}/swaps/{swap_id}/shipments' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "fulfillment_id": "{fulfillment_id}" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Orders + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminOrdersRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/payment-collections/{id}: + get: + operationId: GetPaymentCollectionsPaymentCollection + summary: Get a Payment Collection + description: Retrieve a Payment Collection's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Payment Collection. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + payment collection. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + payment collection. + schema: + type: string + x-codegen: + method: retrieve + queryParams: AdminGetPaymentCollectionsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.paymentCollections.retrieve(paymentCollectionId) + .then(({ payment_collection }) => { + console.log(payment_collection.id) + }) + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/payment-collections/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Payment Collections + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPaymentCollectionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostPaymentCollectionsPaymentCollection + summary: Update Payment Collection + description: Update a Payment Collection's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Payment Collection. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminUpdatePaymentCollectionsReq' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.paymentCollections.update(paymentCollectionId, { + description + }) + .then(({ payment_collection }) => { + console.log(payment_collection.id) + }) + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/payment-collections/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "description": "Description of payment collection" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Payment Collections + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPaymentCollectionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeletePaymentCollectionsPaymentCollection + summary: Delete a Payment Collection + description: >- + Delete a Payment Collection. Only payment collections with the statuses + `canceled` or `not_paid` can be deleted. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Payment Collection. + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.paymentCollections.delete(paymentCollectionId) + .then(({ id, object, deleted }) => { + console.log(id) + }) + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/payment-collections/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Payment Collections + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPaymentCollectionDeleteRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + /admin/payment-collections/{id}/authorize: + post: + operationId: PostPaymentCollectionsPaymentCollectionAuthorize + summary: Mark Authorized + description: >- + Set the status of a Payment Collection as `authorized`. This will also + change the `authorized_amount` of the payment collection. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Payment Collection. + schema: + type: string + x-codegen: + method: markAsAuthorized + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.paymentCollections.markAsAuthorized(paymentCollectionId) + .then(({ payment_collection }) => { + console.log(payment_collection.id) + }) + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/payment-collections/{id}/authorize' \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Payment Collections + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPaymentCollectionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/payments/{id}: + get: + operationId: GetPaymentsPayment + summary: Get Payment details + description: Retrieve a Payment's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Payment. + schema: + type: string + x-codegen: + method: retrieve + queryParams: GetPaymentsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.payments.retrieve(paymentId) + + .then(({ payment }) => { + console.log(payment.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/payments/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Payments + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPaymentRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/payments/{id}/capture: + post: + operationId: PostPaymentsPaymentCapture + summary: Capture a Payment + description: Capture a Payment. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Payment. + schema: + type: string + x-codegen: + method: capturePayment + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.payments.capturePayment(paymentId) + + .then(({ payment }) => { + console.log(payment.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/payments/{id}/capture' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Payments + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPaymentRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/payments/{id}/refund: + post: + operationId: PostPaymentsPaymentRefunds + summary: Refund Payment + description: Refund a payment. The payment must be captured first. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Payment. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostPaymentRefundsReq' + x-codegen: + method: refundPayment + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.payments.refundPayment(paymentId, { + amount: 1000, + reason: "return", + note: "Do not like it", + }) + + .then(({ payment }) => { + console.log(payment.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/payments/pay_123/refund' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "amount": 1000, + "reason": "return", + "note": "Do not like it" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Payments + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminRefundRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/price-lists: + get: + operationId: GetPriceLists + summary: List Price Lists + description: >- + Retrieve a list of price lists. The price lists can be filtered by + fields such as `q` or `status`. The price lists can also be sorted or + paginated. + x-authenticated: true + parameters: + - in: query + name: limit + description: Limit the number of price lists returned. + schema: + type: number + default: '10' + - in: query + name: offset + description: The number of price lists to skip when retrieving the price lists. + schema: + type: number + default: '0' + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + price lists. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned price + lists. + schema: + type: string + - in: query + name: order + description: A price-list field to sort-order the retrieved price lists by. + schema: + type: string + - in: query + name: id + description: Filter by ID + schema: + type: string + - in: query + name: q + description: >- + term to search price lists' description, name, and customer group's + name. + schema: + type: string + - in: query + name: status + style: form + explode: false + description: Filter by status. + schema: + type: array + items: + type: string + enum: + - active + - draft + - in: query + name: name + description: Filter by name + schema: + type: string + - in: query + name: customer_groups + style: form + explode: false + description: Filter by customer-group IDs. + schema: + type: array + items: + type: string + - in: query + name: type + style: form + explode: false + description: Filter by type. + schema: + type: array + items: + type: string + enum: + - sale + - override + - in: query + name: created_at + description: Filter by a creation date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: updated_at + description: Filter by an update date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: deleted_at + description: Filter by a deletion date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + x-codegen: + method: list + queryParams: AdminGetPriceListPaginationParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.priceLists.list() + + .then(({ price_lists, limit, offset, count }) => { + console.log(price_lists.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/price-lists' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Price Lists + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPriceListsListRes' + '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: PostPriceListsPriceList + summary: Create a Price List + description: Create a Price List. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostPriceListsPriceListReq' + x-codegen: + method: create + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + import { PriceListType } from "@medusajs/medusa" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.priceLists.create({ + name: "New Price List", + description: "A new price list", + type: PriceListType.SALE, + prices: [ + { + amount: 1000, + variant_id, + currency_code: "eur" + } + ] + }) + + .then(({ price_list }) => { + console.log(price_list.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/price-lists' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "name": "New Price List", + "description": "A new price list", + "type": "sale", + "prices": [ + { + "amount": 1000, + "variant_id": "afafa", + "currency_code": "eur" + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Price Lists + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPriceListRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/price-lists/{id}: + get: + operationId: GetPriceListsPriceList + summary: Get a Price List + description: Retrieve a Price List's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Price List. + schema: + type: string + x-codegen: + method: retrieve + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.priceLists.retrieve(priceListId) + + .then(({ price_list }) => { + console.log(price_list.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/price-lists/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Price Lists + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPriceListRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostPriceListsPriceListPriceList + summary: Update a Price List + description: Update a Price List's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Price List. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostPriceListsPriceListPriceListReq' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.priceLists.update(priceListId, { + name: "New Price List" + }) + + .then(({ price_list }) => { + console.log(price_list.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/price-lists/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "name": "New Price List" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Price Lists + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPriceListRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeletePriceListsPriceList + summary: Delete a Price List + description: Delete a Price List and its associated prices. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Price List. + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.priceLists.delete(priceListId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/price-lists/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Price Lists + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPriceListDeleteRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/price-lists/{id}/prices/batch: + post: + operationId: PostPriceListsPriceListPricesBatch + summary: Add or Update Prices + description: Add or update a list of prices in a Price List + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Price List. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostPriceListPricesPricesReq' + x-codegen: + method: addPrices + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.priceLists.addPrices(priceListId, { + prices: [ + { + amount: 1000, + variant_id, + currency_code: "eur" + } + ] + }) + + .then(({ price_list }) => { + console.log(price_list.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/price-lists/{id}/prices/batch' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "prices": [ + { + "amount": 100, + "variant_id": "afasfa", + "currency_code": "eur" + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Price Lists + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPriceListRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeletePriceListsPriceListPricesBatch + summary: Delete Prices + description: Delete a list of prices in a Price List + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Price List + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDeletePriceListPricesPricesReq' + x-codegen: + method: deletePrices + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.priceLists.deletePrices(priceListId, { + price_ids: [ + price_id + ] + }) + + .then(({ ids, object, deleted }) => { + console.log(ids.length); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/price-lists/{id}/prices/batch' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "price_ids": [ + "adasfa" + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Price Lists + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPriceListDeleteBatchRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/price-lists/{id}/products: + get: + operationId: GetPriceListsPriceListProducts + summary: List Products + description: >- + Retrieve a price list's products. The products can be filtered by fields + such as `q` or `status`. The products can also be sorted or paginated. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: ID of the price list. + schema: + type: string + - in: query + name: q + description: >- + term used to search products' title, description, product variant's + title and sku, and product collection's title. + schema: + type: string + - in: query + name: id + description: Filter by product ID + schema: + type: string + - in: query + name: status + description: Filter by product status + style: form + explode: false + schema: + type: array + items: + type: string + enum: + - draft + - proposed + - published + - rejected + - in: query + name: collection_id + description: >- + Filter by product collection ID. Only products in the specified + collections are retrieved. + style: form + explode: false + schema: + type: array + items: + type: string + - in: query + name: tags + description: >- + Filter by tag IDs. Only products having the specified tags are + retrieved. + style: form + explode: false + schema: + type: array + items: + type: string + - in: query + name: title + description: Filter by title + schema: + type: string + - in: query + name: description + description: Filter by description + schema: + type: string + - in: query + name: handle + description: Filter by handle + schema: + type: string + - in: query + name: is_giftcard + description: >- + A boolean value to filter by whether the product is a gift card or + not. + schema: + type: string + - in: query + name: type + description: Filter product type. + schema: + type: string + - in: query + name: order + description: A product field to sort-order the retrieved products by. + schema: + type: string + - in: query + name: created_at + description: Filter by a creation date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: updated_at + description: Filter by an update date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: deleted_at + description: Filter by a deletion date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: offset + description: The number of products to skip when retrieving the products. + schema: + type: integer + default: 0 + - in: query + name: limit + description: Limit the number of products returned. + schema: + type: integer + default: 50 + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + products. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + products. + schema: + type: string + x-codegen: + method: listProducts + queryParams: AdminGetPriceListsPriceListProductsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.priceLists.listProducts(priceListId) + + .then(({ products, limit, offset, count }) => { + console.log(products.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/price-lists/{id}/products' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Price Lists + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPriceListsProductsListRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/price-lists/{id}/products/prices/batch: + delete: + operationId: DeletePriceListsPriceListProductsPricesBatch + summary: Delete Product Prices + description: Delete all the prices associated with multiple products in a price list. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Price List + schema: + type: string + x-codegen: + method: deleteProductsPrices + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.priceLists.deleteProductsPrices(priceListId, { + product_ids: [ + productId1, + productId2, + ] + }) + + .then(({ ids, object, deleted }) => { + console.log(ids.length); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/price-lists/{id}/products/prices/batch' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "product_ids": [ + "prod_1", + "prod_2" + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Price Lists + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPriceListDeleteProductPricesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/price-lists/{id}/products/{product_id}/prices: + delete: + operationId: DeletePriceListsPriceListProductsProductPrices + summary: Delete a Product's Prices + description: Delete all the prices related to a specific product in a price list. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Price List. + schema: + type: string + - in: path + name: product_id + required: true + description: The ID of the product from which the prices will be deleted. + schema: + type: string + x-codegen: + method: deleteProductPrices + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.priceLists.deleteProductPrices(priceListId, productId) + + .then(({ ids, object, deleted }) => { + console.log(ids.length); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/price-lists/{id}/products/{product_id}/prices' + \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Price Lists + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPriceListDeleteProductPricesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/price-lists/{id}/variants/{variant_id}/prices: + delete: + operationId: DeletePriceListsPriceListVariantsVariantPrices + summary: Delete a Variant's Prices + description: Delete all the prices related to a specific variant in a price list + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Price List. + schema: + type: string + - in: path + name: variant_id + required: true + description: The ID of the variant. + schema: + type: string + x-codegen: + method: deleteVariantPrices + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.priceLists.deleteVariantPrices(priceListId, variantId) + + .then(({ ids, object, deleted }) => { + console.log(ids); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/price-lists/{id}/variants/{variant_id}/prices' + \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Price Lists + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPriceListDeleteVariantPricesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/product-categories: + get: + operationId: GetProductCategories + summary: List Product Categories + description: >- + Retrieve a list of product categories. The product categories can be + filtered by fields such as `q` or `handle`. The product categories can + also be paginated. + x-authenticated: true + x-featureFlag: product_categories + parameters: + - in: query + name: q + description: term to search product categories' names and handles. + schema: + type: string + - in: query + name: handle + description: Filter by handle. + schema: + type: string + - in: query + name: is_internal + description: Filter by whether the category is internal or not. + schema: + type: boolean + - in: query + name: is_active + description: Filter by whether the category is active or not. + schema: + type: boolean + - in: query + name: include_descendants_tree + description: >- + If set to `true`, all nested descendants of a category are included + in the response. + schema: + type: boolean + - in: query + name: parent_category_id + description: Filter by the ID of a parent category. + schema: + type: string + - 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: AdminGetProductCategoriesParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.productCategories.list() + + .then(({ product_categories, limit, offset, count }) => { + console.log(product_categories.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/product-categories' \ + -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/AdminProductCategoriesListRes' + '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: PostProductCategories + summary: Create a Product Category + description: Create a Product Category. + x-authenticated: true + x-featureFlag: product_categories + parameters: + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + product category. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + product category. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostProductCategoriesReq' + x-codegen: + method: create + queryParams: AdminPostProductCategoriesParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.productCategories.create({ + name: "Skinny Jeans", + }) + + .then(({ product_category }) => { + console.log(product_category.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/product-categories' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "name": "Skinny Jeans" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Categories + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductCategoriesCategoryRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/product-categories/{id}: + get: + operationId: GetProductCategoriesCategory + summary: Get a Product Category + description: Retrieve a Product Category's details. + x-authenticated: true + x-featureFlag: product_categories + parameters: + - in: path + name: id + required: true + description: The ID of the Product Category + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + product category. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + product category. + schema: + type: string + x-codegen: + method: retrieve + queryParams: AdminGetProductCategoryParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.productCategories.retrieve(productCategoryId) + + .then(({ product_category }) => { + console.log(product_category.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/product-categories/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Categories + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductCategoriesCategoryRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostProductCategoriesCategory + summary: Update a Product Category + description: Updates a Product Category. + x-authenticated: true + x-featureFlag: product_categories + parameters: + - in: path + name: id + required: true + description: The ID of the Product Category. + schema: + type: string + - in: query + name: expand + description: >- + (Comma separated) Which fields should be expanded in each product + category. + schema: + type: string + - in: query + name: fields + description: >- + (Comma separated) Which fields should be retrieved in each product + category. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostProductCategoriesCategoryReq' + x-codegen: + method: update + queryParams: AdminPostProductCategoriesCategoryParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.productCategories.update(productCategoryId, { + name: "Skinny Jeans" + }) + + .then(({ product_category }) => { + console.log(product_category.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/product-categories/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "name": "Skinny Jeans" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Categories + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductCategoriesCategoryRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteProductCategoriesCategory + summary: Delete a Product Category + description: Delete a Product Category. This does not delete associated products. + x-authenticated: true + x-featureFlag: product_categories + parameters: + - in: path + name: id + required: true + description: The ID of the Product Category + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.productCategories.delete(productCategoryId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/product-categories/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Categories + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductCategoriesCategoryDeleteRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/product-categories/{id}/products/batch: + post: + operationId: PostProductCategoriesCategoryProductsBatch + summary: Add Products to a Category + description: Add a list of products to a product category. + x-authenticated: true + x-featureFlag: product_categories + parameters: + - in: path + name: id + required: true + description: The ID of the Product Category. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + product category. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + product category. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminPostProductCategoriesCategoryProductsBatchReq + x-codegen: + method: addProducts + queryParams: AdminPostProductCategoriesCategoryProductsBatchParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.productCategories.addProducts(productCategoryId, { + product_ids: [ + { + id: productId + } + ] + }) + + .then(({ product_category }) => { + console.log(product_category.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/product-categories/{id}/products/batch' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "product_ids": [ + { + "id": "{product_id}" + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Categories + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductCategoriesCategoryRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteProductCategoriesCategoryProductsBatch + summary: Remove Products from Category + description: Remove a list of products from a product category. + x-authenticated: true + x-featureFlag: product_categories + parameters: + - in: path + name: id + required: true + description: The ID of the Product Category. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + product category. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + product category. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminDeleteProductCategoriesCategoryProductsBatchReq + x-codegen: + method: removeProducts + queryParams: AdminDeleteProductCategoriesCategoryProductsBatchParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.productCategories.removeProducts(productCategoryId, { + product_ids: [ + { + id: productId + } + ] + }) + + .then(({ product_category }) => { + console.log(product_category.id); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/product-categories/{id}/products/batch' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "product_ids": [ + { + "id": "{product_id}" + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Categories + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductCategoriesCategoryRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/product-tags: + get: + operationId: GetProductTags + summary: List Product Tags + description: >- + Retrieve a list of product tags. The product tags can be filtered by + fields such as `q` or `value`. The product tags can also be sorted or + paginated. + x-authenticated: true + parameters: + - in: query + name: limit + description: Limit the number of product tags returned. + schema: + type: integer + default: 10 + - in: query + name: offset + description: The number of product tags to skip when retrieving the product tags. + schema: + type: integer + default: 0 + - in: query + name: order + description: A product tag field to sort-order the retrieved product tags by. + schema: + type: string + - in: query + name: discount_condition_id + description: >- + Filter by the ID of a discount condition. Only product tags that + this discount condition is applied to will be retrieved. + schema: + type: string + - in: query + name: value + style: form + explode: false + description: Filter by tag value. + schema: + type: array + items: + type: string + - in: query + name: q + description: term to search product tags' values. + schema: + type: string + - in: query + name: id + style: form + explode: false + description: Filter by tag IDs. + schema: + type: array + items: + type: string + - in: query + name: created_at + description: Filter by a creation date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: updated_at + description: Filter by an update date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + x-codegen: + method: list + queryParams: AdminGetProductTagsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.productTags.list() + + .then(({ product_tags }) => { + console.log(product_tags.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/product-tags' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Tags + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductTagsListRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/product-types: + get: + operationId: GetProductTypes + summary: List Product Types + description: >- + Retrieve a list of product types. The product types can be filtered by + fields such as `q` or `value`. The product types can also be sorted or + paginated. + x-authenticated: true + parameters: + - in: query + name: limit + description: Limit the number of product types returned. + schema: + type: integer + default: 20 + - in: query + name: offset + description: >- + The number of product types to skip when retrieving the product + types. + schema: + type: integer + default: 0 + - in: query + name: order + description: A product type field to sort-order the retrieved product types by. + schema: + type: string + - in: query + name: discount_condition_id + description: >- + Filter by the ID of a discount condition. Only product types that + this discount condition is applied to will be retrieved. + schema: + type: string + - in: query + name: value + style: form + explode: false + description: Filter by value. + schema: + type: array + items: + type: string + - in: query + name: id + style: form + explode: false + description: Filter by product type IDs. + schema: + type: array + items: + type: string + - in: query + name: q + description: term to search product types' values. + schema: + type: string + - in: query + name: created_at + description: Filter by a creation date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: updated_at + description: Filter by an update date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + x-codegen: + method: list + queryParams: AdminGetProductTypesParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.productTypes.list() + + .then(({ product_types }) => { + console.log(product_types.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/product-types' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Types + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductTypesListRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/products: + get: + operationId: GetProducts + summary: List Products + description: >- + Retrieve a list of products. The products can be filtered by fields such + as `q` or `status`. The products can also be sorted or paginated. + x-authenticated: true + parameters: + - in: query + name: q + description: >- + term to search products' title, description, variants' title and + sku, and collections' title. + schema: + type: string + - in: query + name: discount_condition_id + description: >- + Filter by the ID of a discount condition. Only products that this + discount condition is applied to will be retrieved. + schema: + type: string + - in: query + name: id + style: form + explode: false + description: Filter by product IDs. + schema: + oneOf: + - type: string + description: ID of the product. + - type: array + items: + type: string + description: ID of a product. + - in: query + name: status + style: form + explode: false + description: Filter by status. + schema: + type: array + items: + type: string + enum: + - draft + - proposed + - published + - rejected + - in: query + name: collection_id + style: form + explode: false + description: >- + Filter by product collection IDs. Only products that are associated + with the specified collections will be retrieved. + schema: + type: array + items: + type: string + - in: query + name: tags + style: form + explode: false + description: >- + Filter by product tag IDs. Only products that are associated with + the specified tags will be retrieved. + schema: + type: array + items: + type: string + - in: query + name: price_list_id + style: form + explode: false + description: >- + Filter by IDs of price lists. Only products that these price lists + are applied to will be retrieved. + schema: + type: array + items: + type: string + - in: query + name: sales_channel_id + style: form + explode: false + description: >- + Filter by sales channel IDs. Only products that are available in the + specified sales channels will be retrieved. + schema: + type: array + items: + type: string + - in: query + name: type_id + style: form + explode: false + description: >- + Filter by product type IDs. Only products that are associated with + the specified types will be retrieved. + schema: + type: array + items: + type: string + - in: query + name: category_id + style: form + explode: false + description: >- + Filter by product category IDs. Only products that are associated + with the specified categories will be retrieved. + schema: + type: array + x-featureFlag: product_categories + items: + type: string + - in: query + name: include_category_children + style: form + explode: false + description: >- + whether to include product category children when filtering by + `category_id` + schema: + type: boolean + x-featureFlag: product_categories + - in: query + name: title + description: Filter by title. + schema: + type: string + - in: query + name: description + description: Filter by description. + schema: + type: string + - in: query + name: handle + description: Filter by handle. + schema: + type: string + - in: query + name: is_giftcard + description: Whether to retrieve gift cards or regular products. + schema: + type: boolean + - in: query + name: created_at + description: Filter by a creation date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: updated_at + description: Filter by an update date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: deleted_at + description: Filter by a deletion date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: offset + description: The number of products to skip when retrieving the products. + schema: + type: integer + default: 0 + - in: query + name: limit + description: Limit the number of products returned. + schema: + type: integer + default: 50 + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + products. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + products. + schema: + type: string + - in: query + name: order + description: A product field to sort-order the retrieved products by. + schema: + type: string + x-codegen: + method: list + queryParams: AdminGetProductsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.products.list() + + .then(({ products, limit, offset, count }) => { + console.log(products.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/products' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Products + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductsListRes' + '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: PostProducts + summary: Create a Product + x-authenticated: true + description: >- + Create a new Product. This API Route can also be used to create a gift + card if the `is_giftcard` field is set to `true`. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostProductsReq' + 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 }) + + // must be previously logged in or use api token + + medusa.admin.products.create({ + title: "Shirt", + is_giftcard: false, + discountable: true + }) + + .then(({ product }) => { + console.log(product.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/products' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "title": "Shirt" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Products + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/products/tag-usage: + get: + operationId: GetProductsTagUsage + summary: List Tags Usage Number + description: >- + Retrieve a list of Product Tags with how many times each is used in + products. + x-authenticated: true + x-codegen: + method: listTags + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.products.listTags() + + .then(({ tags }) => { + console.log(tags.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/products/tag-usage' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Products + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductsListTagsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/products/types: + get: + deprecated: true + operationId: GetProductsTypes + summary: List Product Types + description: Retrieve a list of Product Types. + x-authenticated: true + x-codegen: + method: listTypes + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.products.listTypes() + + .then(({ types }) => { + console.log(types.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/products/types' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Products + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductsListTypesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/products/{id}: + get: + operationId: GetProductsProduct + summary: Get a Product + description: Retrieve a Product's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Product. + 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 }) + + // must be previously logged in or use api token + + medusa.admin.products.retrieve(productId) + + .then(({ product }) => { + console.log(product.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/products/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Products + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostProductsProduct + summary: Update a Product + description: Update a Product's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Product. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostProductsProductReq' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.products.update(productId, { + title: "Shirt", + }) + + .then(({ product }) => { + console.log(product.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/products/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "title": "Size" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Products + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteProductsProduct + summary: Delete a Product + description: Delete a Product and its associated product variants and options. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Product. + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.products.delete(productId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/products/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Products + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductsDeleteRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/products/{id}/metadata: + post: + operationId: PostProductsProductMetadata + summary: Set Metadata + description: >- + Set the metadata of a Product. It can be any key-value pair, which + allows adding custom data to a product. + externalDocs: + description: Learn about the metadata attribute, and how to delete and update it. + url: >- + https://docs.medusajs.com/development/entities/overview#metadata-attribute + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Product. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostProductsProductMetadataReq' + x-codegen: + method: setMetadata + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.products.setMetadata(productId, { + key: "test", + value: "true" + }) + + .then(({ product }) => { + console.log(product.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/products/{id}/metadata' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "key": "test", + "value": "true" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Products + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/products/{id}/options: + post: + operationId: PostProductsProductOptions + summary: Add a Product Option + description: Add a Product Option to a Product. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Product. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostProductsProductOptionsReq' + x-codegen: + method: addOption + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.products.addOption(productId, { + title: "Size" + }) + + .then(({ product }) => { + console.log(product.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/products/{id}/options' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "title": "Size" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Products + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/products/{id}/options/{option_id}: + post: + operationId: PostProductsProductOptionsOption + summary: Update a Product Option + description: Update a Product Option's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Product. + schema: + type: string + - in: path + name: option_id + required: true + description: The ID of the Product Option. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostProductsProductOptionsOption' + x-codegen: + method: updateOption + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.products.updateOption(productId, optionId, { + title: "Size" + }) + + .then(({ product }) => { + console.log(product.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST '{backend_url}/admin/products/{id}/options/{option_id}' + \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "title": "Size" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Products + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteProductsProductOptionsOption + summary: Delete a Product Option + description: >- + Delete a Product Option. If there are product variants that use this + product option, they must be deleted before deleting the product option. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Product. + schema: + type: string + - in: path + name: option_id + required: true + description: The ID of the Product Option. + schema: + type: string + x-codegen: + method: deleteOption + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.products.deleteOption(productId, optionId) + + .then(({ option_id, object, deleted, product }) => { + console.log(product.id); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/products/{id}/options/{option_id}' \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Products + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductsDeleteOptionRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/products/{id}/variants: + get: + operationId: GetProductsProductVariants + summary: List a Product's Variants + description: > + Retrieve a list of Product Variants associated with a Product. The + variants can be paginated. + + + By default, each variant will only have the `id` and `variant_id` + fields. You can use the `expand` and `fields` request parameters to + retrieve more fields or relations. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: ID of the product. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + product variants. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + product variants. + schema: + type: string + - in: query + name: offset + description: >- + The number of product variants to skip when retrieving the product + variants. + schema: + type: integer + default: 0 + - in: query + name: limit + description: Limit the number of product variants returned. + schema: + type: integer + default: 100 + x-codegen: + method: listVariants + queryParams: AdminGetProductsVariantsParams + x-codeSamples: + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/products/{id}/variants' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Products + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductsListVariantsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostProductsProductVariants + summary: Create a Product Variant + description: >- + Create a Product Variant associated with a Product. Each product variant + must have a unique combination of Product Option values. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Product. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostProductsProductVariantsReq' + x-codegen: + method: createVariant + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.products.createVariant(productId, { + title: "Color", + prices: [ + { + amount: 1000, + currency_code: "eur" + } + ], + options: [ + { + option_id, + value: "S" + } + ], + inventory_quantity: 100 + }) + + .then(({ product }) => { + console.log(product.id); + }) + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/products/{id}/variants' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "title": "Color", + "prices": [ + { + "amount": 1000, + "currency_code": "eur" + } + ], + "options": [ + { + "option_id": "asdasf", + "value": "S" + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Products + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/products/{id}/variants/{variant_id}: + post: + operationId: PostProductsProductVariantsVariant + summary: Update a Product Variant + description: Update a Product Variant's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Product. + schema: + type: string + - in: path + name: variant_id + required: true + description: The ID of the Product Variant. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostProductsProductVariantsVariantReq' + x-codegen: + method: updateVariant + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.products.updateVariant(productId, variantId, { + title: "Color", + prices: [ + { + amount: 1000, + currency_code: "eur" + } + ], + options: [ + { + option_id, + value: "S" + } + ], + inventory_quantity: 100 + }) + + .then(({ product }) => { + console.log(product.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/products/{id}/variants/{variant_id}' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "title": "Color", + "prices": [ + { + "amount": 1000, + "currency_code": "eur" + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Products + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteProductsProductVariantsVariant + summary: Delete a Product Variant + description: Delete a Product Variant. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Product. + schema: + type: string + - in: path + name: variant_id + required: true + description: The ID of the Product Variant. + schema: + type: string + x-codegen: + method: deleteVariant + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.products.deleteVariant(productId, variantId) + + .then(({ variant_id, object, deleted, product }) => { + console.log(product.id); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/products/{id}/variants/{variant_id}' \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Products + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminProductsDeleteVariantRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/publishable-api-key/{id}: + post: + operationId: PostPublishableApiKysPublishableApiKey + summary: Update Publishable API Key + description: Update a Publishable API Key's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Publishable API Key. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminPostPublishableApiKeysPublishableApiKeyReq + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.publishableApiKeys.update(publishableApiKeyId, { + title: "new title" + }) + + .then(({ publishable_api_key }) => { + console.log(publishable_api_key.id) + }) + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/publishable-api-key/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "title": "new title" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Publishable Api Keys + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPublishableApiKeysRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/publishable-api-keys: + get: + operationId: GetPublishableApiKeys + summary: List Publishable API keys + description: >- + Retrieve a list of publishable API keys. The publishable API keys can be + filtered by fields such as `q`. The publishable API keys can also be + paginated. + x-authenticated: true + parameters: + - in: query + name: q + description: term to search publishable API keys' titles. + schema: + type: string + - in: query + name: limit + description: Limit the number of publishable API keys returned. + schema: + type: number + default: '20' + - in: query + name: offset + description: >- + The number of publishable API keys to skip when retrieving the + publishable API keys. + schema: + type: number + default: '0' + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + publishable API keys. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + publishable API keys. + schema: + type: string + x-codegen: + method: list + queryParams: GetPublishableApiKeysParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.publishableApiKeys.list() + .then(({ publishable_api_keys, count, limit, offset }) => { + console.log(publishable_api_keys) + }) + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/publishable-api-keys' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Publishable Api Keys + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPublishableApiKeysListRes' + '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: PostPublishableApiKeys + summary: Create Publishable API Key + description: Creates a Publishable API Key. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostPublishableApiKeysReq' + x-authenticated: true + 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 }) + + // must be previously logged in or use api token + + medusa.admin.publishableApiKeys.create({ + title + }) + + .then(({ publishable_api_key }) => { + console.log(publishable_api_key.id) + }) + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/publishable-api-keys' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "title": "Web API Key" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Publishable Api Keys + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPublishableApiKeysRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/publishable-api-keys/{id}: + get: + operationId: GetPublishableApiKeysPublishableApiKey + summary: Get a Publishable API Key + description: Retrieve a publishable API key's details. + parameters: + - in: path + name: id + required: true + description: The ID of the Publishable API Key. + schema: + type: string + x-authenticated: true + x-codegen: + method: retrieve + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.publishableApiKeys.retrieve(publishableApiKeyId) + + .then(({ publishable_api_key }) => { + console.log(publishable_api_key.id) + }) + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/publishable-api-keys/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Publishable Api Keys + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPublishableApiKeysRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeletePublishableApiKeysPublishableApiKey + summary: Delete Publishable API Key + description: >- + Delete a Publishable API Key. Associated resources, such as sales + channels, are not deleted. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Publishable API Key to delete. + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.publishableApiKeys.delete(publishableApiKeyId) + + .then(({ id, object, deleted }) => { + console.log(id) + }) + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/publishable-api-key/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Publishable Api Keys + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPublishableApiKeyDeleteRes' + '400': + $ref: '#/components/responses/400_error' + /admin/publishable-api-keys/{id}/revoke: + post: + operationId: PostPublishableApiKeysPublishableApiKeyRevoke + summary: Revoke a Publishable API Key + description: >- + Revoke a Publishable API Key. Revoking the publishable API Key can't be + undone, and the key can't be used in future requests. + parameters: + - in: path + name: id + required: true + description: The ID of the Publishable API Key. + schema: + type: string + x-authenticated: true + x-codegen: + method: revoke + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.publishableApiKeys.revoke(publishableApiKeyId) + .then(({ publishable_api_key }) => { + console.log(publishable_api_key.id) + }) + - lang: Shell + label: cURL + source: > + curl -X POST '{backend_url}/admin/publishable-api-keys/{id}/revoke' + \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Publishable Api Keys + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPublishableApiKeysRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/publishable-api-keys/{id}/sales-channels: + get: + operationId: GetPublishableApiKeySalesChannels + summary: List Sales Channels + description: >- + List the sales channels associated with a publishable API key. The sales + channels can be filtered by fields such as `q`. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the publishable API key. + schema: + type: string + - in: query + name: q + description: query to search sales channels' names and descriptions. + schema: + type: string + x-codegen: + method: listSalesChannels + queryParams: GetPublishableApiKeySalesChannelsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.publishableApiKeys.listSalesChannels() + .then(({ sales_channels }) => { + console.log(sales_channels.length) + }) + - lang: Shell + label: cURL + source: > + curl '{backend_url}/admin/publishable-api-keys/{id}/sales-channels' + \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Publishable Api Keys + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminPublishableApiKeysListSalesChannelsRes + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/publishable-api-keys/{id}/sales-channels/batch: + post: + operationId: PostPublishableApiKeySalesChannelsChannelsBatch + summary: Add Sales Channels + description: Assign a list of sales channels to a publishable API key. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Publishable Api Key. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminPostPublishableApiKeySalesChannelsBatchReq + x-codegen: + method: addSalesChannelsBatch + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.publishableApiKeys.addSalesChannelsBatch(publishableApiKeyId, + { + sales_channel_ids: [ + { + id: channelId + } + ] + }) + + .then(({ publishable_api_key }) => { + console.log(publishable_api_key.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/publishable-api-keys/{pak_id}/batch' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "sales_channel_ids": [ + { + "id": "{sales_channel_id}" + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Publishable Api Keys + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPublishableApiKeysRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeletePublishableApiKeySalesChannelsChannelsBatch + summary: Remove Sales Channels + description: >- + Remove a list of sales channels from a publishable API key. This doesn't + delete the sales channels and only removes the association between them + and the publishable API key. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Publishable API Key. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminDeletePublishableApiKeySalesChannelsBatchReq + x-codegen: + method: deleteSalesChannelsBatch + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.publishableApiKeys.deleteSalesChannelsBatch(publishableApiKeyId, + { + sales_channel_ids: [ + { + id: channelId + } + ] + }) + + .then(({ publishable_api_key }) => { + console.log(publishable_api_key.id); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE '{backend_url}/admin/publishable-api-keys/{id}/batch' + \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "sales_channel_ids": [ + { + "id": "{sales_channel_id}" + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Publishable Api Keys + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPublishableApiKeysRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/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 + x-authenticated: true + parameters: + - in: query + name: limit + schema: + type: integer + default: 50 + required: false + description: Limit the number of regions returned. + - in: query + name: offset + schema: + type: integer + default: 0 + required: false + description: The number of regions to skip when retrieving the regions. + - in: query + name: created_at + required: false + description: Filter by a creation date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: updated_at + required: false + description: Filter by an update date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: deleted_at + required: false + description: Filter by a deletion date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + x-codegen: + method: list + queryParams: AdminGetRegionsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.regions.list() + + .then(({ regions, limit, offset, count }) => { + console.log(regions.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/regions' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Regions + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminRegionsListRes' + '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: PostRegions + summary: Create a Region + description: Create a Region. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostRegionsReq' + 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 }) + + // must be previously logged in or use api token + + medusa.admin.regions.create({ + name: "Europe", + currency_code: "eur", + tax_rate: 0, + payment_providers: [ + "manual" + ], + fulfillment_providers: [ + "manual" + ], + countries: [ + "DK" + ] + }) + + .then(({ region }) => { + console.log(region.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/regions' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "name": "Europe", + "currency_code": "eur", + "tax_rate": 0, + "payment_providers": [ + "manual" + ], + "fulfillment_providers": [ + "manual" + ], + "countries": [ + "DK" + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Regions + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminRegionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/regions/{id}: + get: + operationId: GetRegionsRegion + summary: Get a Region + description: Retrieve a Region's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Region. + 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 }) + + // must be previously logged in or use api token + + medusa.admin.regions.retrieve(regionId) + + .then(({ region }) => { + console.log(region.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/regions/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Regions + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminRegionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostRegionsRegion + summary: Update a Region + description: Update a Region's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Region. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostRegionsRegionReq' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.regions.update(regionId, { + name: "Europe" + }) + + .then(({ region }) => { + console.log(region.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/regions/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "name": "Europe" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Regions + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminRegionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteRegionsRegion + summary: Delete a Region + description: >- + Delete a Region. Associated resources, such as providers or currencies + are not deleted. Associated tax rates are deleted. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Region. + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.regions.delete(regionId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/regions/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Regions + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminRegionsDeleteRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/regions/{id}/countries: + post: + operationId: PostRegionsRegionCountries + summary: Add Country + description: Add a Country to the list of Countries in a Region + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Region. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostRegionsRegionCountriesReq' + x-codegen: + method: addCountry + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.regions.addCountry(regionId, { + country_code: "dk" + }) + + .then(({ region }) => { + console.log(region.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/regions/{region_id}/countries' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "country_code": "dk" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Regions + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminRegionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/regions/{id}/countries/{country_code}: + delete: + operationId: PostRegionsRegionCountriesCountry + summary: Remove Country + x-authenticated: true + description: >- + Remove a Country from the list of Countries in a Region. The country + will still be available in the system, and it can be used in other + regions. + parameters: + - in: path + name: id + required: true + description: The ID of the Region. + schema: + type: string + - in: path + name: country_code + description: The 2 character ISO code for the Country. + required: true + schema: + type: string + externalDocs: + url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes + description: See a list of codes. + x-codegen: + method: deleteCountry + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.regions.deleteCountry(regionId, "dk") + + .then(({ region }) => { + console.log(region.id); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/regions/{id}/countries/{country_code}' \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Regions + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminRegionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/regions/{id}/fulfillment-options: + get: + operationId: GetRegionsRegionFulfillmentOptions + summary: List Fulfillment Options + description: Retrieve a list of fulfillment options available in a Region. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Region. + schema: + type: string + x-codegen: + method: retrieveFulfillmentOptions + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.regions.retrieveFulfillmentOptions(regionId) + + .then(({ fulfillment_options }) => { + console.log(fulfillment_options.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/regions/{id}/fulfillment-options' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Regions + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminGetRegionsRegionFulfillmentOptionsRes + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/regions/{id}/fulfillment-providers: + post: + operationId: PostRegionsRegionFulfillmentProviders + summary: Add Fulfillment Provider + description: >- + Add a Fulfillment Provider to the list of fulfullment providers in a + Region. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Region. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminPostRegionsRegionFulfillmentProvidersReq + x-codegen: + method: addFulfillmentProvider + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.regions.addFulfillmentProvider(regionId, { + provider_id: "manual" + }) + + .then(({ region }) => { + console.log(region.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/regions/{id}/fulfillment-providers' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "provider_id": "manual" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Regions + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminRegionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/regions/{id}/fulfillment-providers/{provider_id}: + delete: + operationId: PostRegionsRegionFulfillmentProvidersProvider + summary: Remove Fulfillment Provider + description: >- + Remove a Fulfillment Provider from a Region. The fulfillment provider + will still be available for usage in other regions. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Region. + schema: + type: string + - in: path + name: provider_id + required: true + description: The ID of the Fulfillment Provider. + schema: + type: string + x-codegen: + method: deleteFulfillmentProvider + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.regions.deleteFulfillmentProvider(regionId, "manual") + + .then(({ region }) => { + console.log(region.id); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/regions/{id}/fulfillment-providers/{provider_id}' + \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Regions + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminRegionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/regions/{id}/payment-providers: + post: + operationId: PostRegionsRegionPaymentProviders + summary: Add Payment Provider + description: Add a Payment Provider to the list of payment providers in a Region. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Region. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostRegionsRegionPaymentProvidersReq' + x-codegen: + method: addPaymentProvider + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.regions.addPaymentProvider(regionId, { + provider_id: "manual" + }) + + .then(({ region }) => { + console.log(region.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/regions/{id}/payment-providers' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "provider_id": "manual" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Regions + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminRegionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/regions/{id}/payment-providers/{provider_id}: + delete: + operationId: PostRegionsRegionPaymentProvidersProvider + summary: Remove Payment Provider + description: >- + Remove a Payment Provider from a Region. The payment provider will still + be available for usage in other regions. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Region. + schema: + type: string + - in: path + name: provider_id + required: true + description: The ID of the Payment Provider. + schema: + type: string + x-codegen: + method: deletePaymentProvider + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.regions.deletePaymentProvider(regionId, "manual") + + .then(({ region }) => { + console.log(region.id); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/regions/{id}/payment-providers/{provider_id}' \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Regions + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminRegionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/reservations: + get: + operationId: GetReservations + summary: List Reservations + description: >- + Retrieve a list of Reservations. The reservations can be filtered by + fields such as `location_id` or `quantity`. The reservations can also be + paginated. + x-authenticated: true + parameters: + - in: query + name: location_id + style: form + explode: false + description: Filter by location ID + schema: + type: array + items: + type: string + - in: query + name: inventory_item_id + style: form + explode: false + description: Filter by inventory item ID. + schema: + type: array + items: + type: string + - in: query + name: line_item_id + style: form + explode: false + description: Filter by line item ID. + schema: + type: array + items: + type: string + - in: query + name: quantity + description: Filter by reservation quantity + schema: + type: object + properties: + lt: + type: number + description: filter by reservation quantity less than this number + gt: + type: number + description: filter by reservation quantity greater than this number + lte: + type: number + description: >- + filter by reservation quantity less than or equal to this + number + gte: + type: number + description: >- + filter by reservation quantity greater than or equal to this + number + - in: query + name: description + description: Filter by description. + schema: + oneOf: + - type: string + description: description value to filter by. + - type: object + properties: + contains: + type: string + description: >- + filter by reservation description containing search + string. + starts_with: + type: string + description: >- + filter by reservation description starting with search + string. + ends_with: + type: string + description: >- + filter by reservation description ending with search + 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: offset + description: The number of reservations to skip when retrieving the reservations. + schema: + type: integer + default: 0 + - in: query + name: limit + description: Limit the number of reservations returned. + schema: + type: integer + default: 20 + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + reservations. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + reservations. + schema: + type: string + x-codegen: + method: list + queryParams: AdminGetReservationsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.reservations.list() + + .then(({ reservations, count, limit, offset }) => { + console.log(reservations.length) + }) + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/product-categories' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Reservations + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminReservationsListRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostReservations + summary: Create a Reservation + description: >- + Create a Reservation which can be associated with any resource, such as + an order's line item. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostReservationsReq' + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.reservations.create({ + line_item_id: "item_123", + location_id: "loc_123", + inventory_item_id: "iitem_123", + quantity: 1 + }) + + .then(({ reservation }) => { + console.log(reservation.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/reservations' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "line_item_id": "item_123", + "location_id": "loc_123", + "inventory_item_id": "iitem_123", + "quantity": 1 + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Reservations + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminReservationsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/reservations/{id}: + get: + operationId: GetReservationsReservation + summary: Get a Reservation + description: Retrieve a reservation's details.' + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the reservation. + schema: + type: string + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.reservations.retrieve(reservationId) + + .then(({ reservation }) => { + console.log(reservation.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/reservations/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Reservations + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminReservationsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostReservationsReservation + summary: Update a Reservation + description: Update a Reservation's details.' + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Reservation. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostReservationsReservationReq' + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.reservations.update(reservationId, { + quantity: 3 + }) + + .then(({ reservation }) => { + console.log(reservation.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/reservations/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "quantity": 3, + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Reservations + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminReservationsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteReservationsReservation + summary: Delete a Reservation + description: >- + Delete a Reservation. Associated resources, such as the line item, will + not be deleted. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Reservation to delete. + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.reservations.delete(reservationId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/reservations/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Reservations + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminReservationsDeleteRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/return-reasons: + get: + operationId: GetReturnReasons + summary: List Return Reasons + description: Retrieve a list of Return Reasons. + x-authenticated: true + x-codegen: + method: list + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.returnReasons.list() + + .then(({ return_reasons }) => { + console.log(return_reasons.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/return-reasons' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Return Reasons + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminReturnReasonsListRes' + '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: PostReturnReasons + summary: Create a Return Reason + description: Create a Return Reason. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostReturnReasonsReq' + 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 }) + + // must be previously logged in or use api token + + medusa.admin.returnReasons.create({ + label: "Damaged", + value: "damaged" + }) + + .then(({ return_reason }) => { + console.log(return_reason.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/return-reasons' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "label": "Damaged", + "value": "damaged" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Return Reasons + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminReturnReasonsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/return-reasons/{id}: + get: + operationId: GetReturnReasonsReason + summary: Get a Return Reason + description: Retrieve a Return Reason's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Return Reason. + schema: + type: string + x-codegen: + method: retrieve + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.returnReasons.retrieve(returnReasonId) + + .then(({ return_reason }) => { + console.log(return_reason.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/return-reasons/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Return Reasons + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminReturnReasonsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostReturnReasonsReason + summary: Update a Return Reason + description: Update a Return Reason's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Return Reason. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostReturnReasonsReasonReq' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.returnReasons.update(returnReasonId, { + label: "Damaged" + }) + + .then(({ return_reason }) => { + console.log(return_reason.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/return-reasons/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "label": "Damaged" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Return Reasons + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminReturnReasonsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteReturnReason + summary: Delete a Return Reason + description: Delete a return reason. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the return reason + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.returnReasons.delete(returnReasonId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/return-reasons/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Return Reasons + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminReturnReasonsDeleteRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/returns: + get: + operationId: GetReturns + summary: List Returns + description: Retrieve a list of Returns. The returns can be paginated. + parameters: + - in: query + name: limit + description: Limit the number of Returns returned. + schema: + type: number + default: '50' + - in: query + name: offset + description: The number of Returns to skip when retrieving the Returns. + schema: + type: number + default: '0' + x-codegen: + method: list + queryParams: AdminGetReturnsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.returns.list() + + .then(({ returns, limit, offset, count }) => { + console.log(returns.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/returns' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Returns + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminReturnsListRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/returns/{id}/cancel: + post: + operationId: PostReturnsReturnCancel + summary: Cancel a Return + description: >- + Registers a Return as canceled. The return can be associated with an + order, claim, or swap. + parameters: + - in: path + name: id + required: true + description: The ID of the Return. + schema: + type: string + x-codegen: + method: cancel + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.returns.cancel(returnId) + + .then(({ order }) => { + console.log(order.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/returns/{id}/cancel' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Returns + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminReturnsCancelRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/returns/{id}/receive: + post: + operationId: PostReturnsReturnReceive + summary: Receive a Return + description: >- + Mark a Return as received. This also updates the status of associated + order, claim, or swap accordingly. + parameters: + - in: path + name: id + required: true + description: The ID of the Return. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostReturnsReturnReceiveReq' + x-codegen: + method: receive + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.returns.receive(returnId, { + items: [ + { + item_id, + quantity: 1 + } + ] + }) + + .then((data) => { + console.log(data.return.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/returns/{id}/receive' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "items": [ + { + "item_id": "asafg", + "quantity": 1 + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Returns + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminReturnsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/sales-channels: + get: + operationId: GetSalesChannels + summary: List Sales Channels + description: >- + Retrieve a list of sales channels. The sales channels can be filtered by + fields such as `q` or `name`. The sales channels can also be sorted or + paginated. + x-authenticated: true + parameters: + - in: query + name: id + description: Filter by a sales channel ID. + schema: + type: string + - in: query + name: name + description: Filter by name. + schema: + type: string + - in: query + name: description + description: Filter by description. + schema: + type: string + - in: query + name: q + description: term used to search sales channels' names and descriptions. + schema: + type: string + - in: query + name: order + description: A sales-channel field to sort-order the retrieved sales channels by. + schema: + type: string + - in: query + name: created_at + description: Filter by a creation date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: updated_at + description: Filter by an update date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: deleted_at + description: Filter by a deletion date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: offset + description: >- + The number of sales channels to skip when retrieving the sales + channels. + schema: + type: integer + default: 0 + - in: query + name: limit + description: Limit the number of sales channels returned. + schema: + type: integer + default: 20 + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + sales channels. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned sales + channels. + schema: + type: string + x-codegen: + method: list + queryParams: AdminGetSalesChannelsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.salesChannels.list() + + .then(({ sales_channels, limit, offset, count }) => { + console.log(sales_channels.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/sales-channels' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Sales Channels + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminSalesChannelsListRes' + '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: PostSalesChannels + summary: Create a Sales Channel + description: Create a Sales Channel. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostSalesChannelsReq' + 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 }) + + // must be previously logged in or use api token + + medusa.admin.salesChannels.create({ + name: "App", + description: "Mobile app" + }) + + .then(({ sales_channel }) => { + console.log(sales_channel.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/sales-channels' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "name": "App" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Sales Channels + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminSalesChannelsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/sales-channels/{id}: + get: + operationId: GetSalesChannelsSalesChannel + summary: Get a Sales Channel + description: Retrieve a sales channel's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Sales channel. + schema: + type: string + x-codegen: + method: retrieve + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.salesChannels.retrieve(salesChannelId) + + .then(({ sales_channel }) => { + console.log(sales_channel.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/sales-channels/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Sales Channels + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminSalesChannelsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostSalesChannelsSalesChannel + summary: Update a Sales Channel + description: Update a Sales Channel's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Sales Channel. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostSalesChannelsSalesChannelReq' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.salesChannels.update(salesChannelId, { + name: "App" + }) + + .then(({ sales_channel }) => { + console.log(sales_channel.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/sales-channels/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "name": "App" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Sales Channels + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminSalesChannelsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteSalesChannelsSalesChannel + summary: Delete a Sales Channel + description: >- + Delete a sales channel. Associated products, stock locations, and other + resources are not deleted. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Sales channel. + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.salesChannels.delete(salesChannelId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/sales-channels/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Sales Channels + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminSalesChannelsDeleteRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/sales-channels/{id}/products/batch: + post: + operationId: PostSalesChannelsChannelProductsBatch + summary: Add Products to Sales Channel + description: Add a list of products to a sales channel. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Sales channel. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminPostSalesChannelsChannelProductsBatchReq + x-codegen: + method: addProducts + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.salesChannels.addProducts(salesChannelId, { + product_ids: [ + { + id: productId + } + ] + }) + + .then(({ sales_channel }) => { + console.log(sales_channel.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/sales-channels/{id}/products/batch' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "product_ids": [ + { + "id": "{product_id}" + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Sales Channels + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminSalesChannelsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteSalesChannelsChannelProductsBatch + summary: Remove Products from Sales Channel + description: >- + Remove a list of products from a sales channel. This does not delete the + product. It only removes the association between the product and the + sales channel. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Sales Channel + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminDeleteSalesChannelsChannelProductsBatchReq + x-codegen: + method: removeProducts + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.salesChannels.removeProducts(salesChannelId, { + product_ids: [ + { + id: productId + } + ] + }) + + .then(({ sales_channel }) => { + console.log(sales_channel.id); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/sales-channels/{id}/products/batch' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "product_ids": [ + { + "id": "{product_id}" + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Sales Channels + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminSalesChannelsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/sales-channels/{id}/stock-locations: + post: + operationId: PostSalesChannelsSalesChannelStockLocation + summary: Associate a Stock Location + description: Associate a stock location with a Sales Channel. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Sales Channel. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminPostSalesChannelsChannelStockLocationsReq + x-codegen: + method: addLocation + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.salesChannels.addLocation(salesChannelId, { + location_id: "loc_123" + }) + + .then(({ sales_channel }) => { + console.log(sales_channel.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/sales-channels/{id}/stock-locations' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "locaton_id": "loc_123" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Sales Channels + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminSalesChannelsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteSalesChannelsSalesChannelStockLocation + summary: Remove Stock Location from Sales Channels. + description: >- + Remove a stock location from a Sales Channel. This only removes the + association between the stock location and the sales channel. It does + not delete the stock location. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Sales Channel. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminDeleteSalesChannelsChannelStockLocationsReq + x-codegen: + method: removeLocation + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.salesChannels.removeLocation(salesChannelId, { + location_id: "loc_id" + }) + + .then(({ sales_channel }) => { + console.log(sales_channel.id); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/sales-channels/{id}/stock-locations' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "locaton_id": "loc_id" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Sales Channels + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminSalesChannelsDeleteLocationRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/shipping-options: + get: + operationId: GetShippingOptions + summary: List Shipping Options + description: >- + Retrieve a list of Shipping Options. The shipping options can be + filtered by fields such as `region_id` or `is_return`. + x-authenticated: true + parameters: + - in: query + name: region_id + schema: + type: string + description: Filter by a region ID. + - in: query + name: is_return + description: Filter by whether the shipping option is used for returns or orders. + schema: + type: boolean + - in: query + name: admin_only + schema: + type: boolean + description: Filter by whether the shipping option is used only by admins or not. + x-codegen: + method: list + queryParams: AdminGetShippingOptionsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.shippingOptions.list() + + .then(({ shipping_options, count }) => { + console.log(shipping_options.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/shipping-options' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Shipping Options + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminShippingOptionsListRes' + '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: PostShippingOptions + summary: Create Shipping Option + description: Create a Shipping Option. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostShippingOptionsReq' + 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 }) + + // must be previously logged in or use api token + + medusa.admin.shippingOptions.create({ + name: "PostFake", + region_id, + provider_id, + data: { + }, + price_type: "flat_rate" + }) + + .then(({ shipping_option }) => { + console.log(shipping_option.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/shipping-options' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "name": "PostFake", + "region_id": "afasf", + "provider_id": "manual", + "data": {}, + "price_type": "flat_rate" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Shipping Options + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminShippingOptionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/shipping-options/{id}: + get: + operationId: GetShippingOptionsOption + summary: Get a Shipping Option + description: Retrieve a Shipping Option's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Shipping Option. + schema: + type: string + x-codegen: + method: retrieve + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.shippingOptions.retrieve(optionId) + + .then(({ shipping_option }) => { + console.log(shipping_option.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/shipping-options/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Shipping Options + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminShippingOptionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostShippingOptionsOption + summary: Update Shipping Option + description: Update a Shipping Option's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Shipping Option. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostShippingOptionsOptionReq' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.shippingOptions.update(optionId, { + name: "PostFake", + requirements: [ + { + id, + type: "max_subtotal", + amount: 1000 + } + ] + }) + + .then(({ shipping_option }) => { + console.log(shipping_option.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/shipping-options/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "requirements": [ + { + "type": "max_subtotal", + "amount": 1000 + } + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Shipping Options + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminShippingOptionsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteShippingOptionsOption + summary: Delete Shipping Option + description: >- + Delete a Shipping Option. Once deleted, it can't be used when creating + orders or returns. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Shipping Option. + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.shippingOptions.delete(optionId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/shipping-options/{option_id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Shipping Options + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminShippingOptionsDeleteRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/shipping-profiles: + get: + operationId: GetShippingProfiles + summary: List Shipping Profiles + description: Retrieve a list of Shipping Profiles. + x-authenticated: true + x-codegen: + method: list + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.shippingProfiles.list() + + .then(({ shipping_profiles }) => { + console.log(shipping_profiles.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/shipping-profiles' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Shipping Profiles + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminShippingProfilesListRes' + '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: PostShippingProfiles + summary: Create a Shipping Profile + description: Create a Shipping Profile. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostShippingProfilesReq' + 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 }) + + // must be previously logged in or use api token + + medusa.admin.shippingProfiles.create({ + name: "Large Products" + }) + + .then(({ shipping_profile }) => { + console.log(shipping_profile.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/shipping-profiles' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "name": "Large Products" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Shipping Profiles + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminShippingProfilesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/shipping-profiles/{id}: + get: + operationId: GetShippingProfilesProfile + summary: Get a Shipping Profile + description: Retrieve a Shipping Profile's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Shipping Profile. + 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 }) + + // must be previously logged in or use api token + + medusa.admin.shippingProfiles.retrieve(profileId) + + .then(({ shipping_profile }) => { + console.log(shipping_profile.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/shipping-profiles/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Shipping Profiles + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminShippingProfilesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostShippingProfilesProfile + summary: Update a Shipping Profile + description: Update a Shipping Profile's details. + parameters: + - in: path + name: id + required: true + description: The ID of the Shipping Profile. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostShippingProfilesProfileReq' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.shippingProfiles.update(shippingProfileId, { + name: 'Large Products' + }) + + .then(({ shipping_profile }) => { + console.log(shipping_profile.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/shipping-profiles/{id} \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "name": "Large Products" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Shipping Profiles + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminShippingProfilesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteShippingProfilesProfile + summary: Delete a Shipping Profile + description: >- + Delete a Shipping Profile. Associated shipping options are deleted as + well. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Shipping Profile. + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.shippingProfiles.delete(profileId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/shipping-profiles/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Shipping Profiles + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDeleteShippingProfileRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/stock-locations: + get: + operationId: GetStockLocations + summary: List Stock Locations + description: >- + Retrieve a list of stock locations. The stock locations can be filtered + by fields such as `name` or `created_at`. The stock locations can also + be sorted or paginated. + x-authenticated: true + parameters: + - in: query + name: id + description: Filter by ID. + schema: + type: string + - in: query + name: name + description: Filter by name. + schema: + type: string + - in: query + name: order + description: >- + A stock-location field to sort-order the retrieved stock locations + by. + schema: + type: string + - in: query + name: created_at + description: Filter by a creation date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: updated_at + description: Filter by an update date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: deleted_at + description: Filter by a deletion date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: offset + description: >- + The number of stock locations to skip when retrieving the stock + locations. + schema: + type: integer + default: 0 + - in: query + name: limit + description: Limit the number of stock locations returned. + schema: + type: integer + default: 20 + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + stock locations. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned stock + locations. + schema: + type: string + x-codegen: + method: list + queryParams: AdminGetStockLocationsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.stockLocations.list() + + .then(({ stock_locations, limit, offset, count }) => { + console.log(stock_locations.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/stock-locations' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Stock Locations + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminStockLocationsListRes' + '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: PostStockLocations + summary: Create a Stock Location + description: Create a Stock Location. + x-authenticated: true + parameters: + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + stock location. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned stock + location. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostStockLocationsReq' + 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 }) + + // must be previously logged in or use api token + + medusa.admin.stockLocations.create({ + name: "Main Warehouse", + }) + + .then(({ stock_location }) => { + console.log(stock_location.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/stock-locations' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "name": "App" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Stock Locations + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminStockLocationsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/stock-locations/{id}: + get: + operationId: GetStockLocationsStockLocation + summary: Get a Stock Location + description: Retrieve a Stock Location's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Stock Location. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + stock location. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned stock + location. + schema: + type: string + x-codegen: + method: retrieve + queryParams: AdminGetStockLocationsLocationParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.stockLocations.retrieve(stockLocationId) + + .then(({ stock_location }) => { + console.log(stock_location.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/stock-locations/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Stock Locations + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminStockLocationsRes' + post: + operationId: PostStockLocationsStockLocation + summary: Update a Stock Location + description: Update a Stock Location's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Stock Location. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + stock location. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned stock + location. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostStockLocationsLocationReq' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.stockLocations.update(stockLocationId, { + name: 'Main Warehouse' + }) + + .then(({ stock_location }) => { + console.log(stock_location.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/stock-locations/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "name": "Main Warehouse" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Stock Locations + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminStockLocationsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteStockLocationsStockLocation + summary: Delete a Stock Location + description: Delete a Stock Location. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Stock Location. + schema: + type: string + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.stockLocations.delete(stockLocationId) + + .then(({ id, object, deleted }) => { + console.log(id) + }) + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/stock-locations/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Stock Locations + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminStockLocationsDeleteRes' + '400': + $ref: '#/components/responses/400_error' + /admin/store: + get: + operationId: GetStore + summary: Get Store details + description: Retrieve the Store's details. + x-authenticated: true + x-codegen: + method: retrieve + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.store.retrieve() + + .then(({ store }) => { + console.log(store.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/store' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Store + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminExtendedStoresRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostStore + summary: Update Store Details + description: Update the Store's details. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostStoreReq' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.store.update({ + name: "Medusa Store" + }) + + .then(({ store }) => { + console.log(store.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/store' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "name": "Medusa Store" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Store + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminStoresRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/store/currencies/{code}: + post: + operationId: PostStoreCurrenciesCode + summary: Add a Currency Code + description: >- + Add a Currency Code to the available currencies in a store. This does + not create new currencies, as currencies are defined within the Medusa + backend. To create a currency, you can create a migration that inserts + the currency into the database. + x-authenticated: true + parameters: + - in: path + name: code + required: true + description: The 3 character ISO currency code. + schema: + type: string + externalDocs: + url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes + description: See a list of codes. + x-codegen: + method: addCurrency + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.store.addCurrency("eur") + + .then(({ store }) => { + console.log(store.currencies); + }); + - lang: Shell + label: cURL + source: > + curl -X POST '{backend_url}/admin/store/currencies/{currency_code}' + \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Store + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminStoresRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteStoreCurrenciesCode + summary: Remove a Currency + description: >- + Remove a Currency Code from the available currencies in a store. This + does not completely delete the currency and it can be added again later + to the store. + x-authenticated: true + parameters: + - in: path + name: code + required: true + description: The 3 character ISO currency code. + schema: + type: string + externalDocs: + url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes + description: See a list of codes. + x-codegen: + method: deleteCurrency + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.store.deleteCurrency("eur") + + .then(({ store }) => { + console.log(store.currencies); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/store/currencies/{currency_code}' \ + + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Store + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminStoresRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/store/payment-providers: + get: + operationId: GetStorePaymentProviders + summary: List Payment Providers + description: Retrieve a list of available Payment Providers in a store. + x-authenticated: true + x-codegen: + method: listPaymentProviders + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.store.listPaymentProviders() + + .then(({ payment_providers }) => { + console.log(payment_providers.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/store/payment-providers' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Store + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPaymentProvidersList' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/store/tax-providers: + get: + operationId: GetStoreTaxProviders + summary: List Tax Providers + description: Retrieve a list of available Tax Providers in a store. + x-authenticated: true + x-codegen: + method: listTaxProviders + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.store.listTaxProviders() + + .then(({ tax_providers }) => { + console.log(tax_providers.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/store/tax-providers' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Store + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminTaxProvidersList' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/swaps: + get: + operationId: GetSwaps + summary: List Swaps + description: Retrieve a list of Swaps. The swaps can be paginated. + parameters: + - in: query + name: limit + description: Limit the number of swaps returned. + schema: + type: number + default: '50' + - in: query + name: offset + description: The number of swaps to skip when retrieving the swaps. + schema: + type: number + default: '0' + x-authenticated: true + x-codegen: + method: list + queryParams: AdminGetSwapsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.swaps.list() + + .then(({ swaps }) => { + console.log(swaps.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/swaps' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Swaps + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminSwapsListRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/swaps/{id}: + get: + operationId: GetSwapsSwap + summary: Get a Swap + description: Retrieve a Swap's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Swap. + 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 }) + + // must be previously logged in or use api token + + medusa.admin.swaps.retrieve(swapId) + + .then(({ swap }) => { + console.log(swap.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/swaps/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Swaps + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminSwapsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/tax-rates: + get: + operationId: GetTaxRates + summary: List Tax Rates + description: >- + Retrieve a list of Tax Rates. The tax rates can be filtered by fields + such as `name` or `rate`. The tax rates can also be paginated. + x-authenticated: true + parameters: + - in: query + name: name + description: Filter by name. + schema: + type: string + - in: query + name: region_id + style: form + explode: false + description: Filter by Region IDs + schema: + oneOf: + - type: string + - type: array + items: + type: string + - in: query + name: code + description: Filter by code. + schema: + type: string + - in: query + name: rate + style: form + explode: false + description: Filter by Rate + schema: + oneOf: + - type: number + - type: object + properties: + lt: + type: number + description: filter by rates less than this number + gt: + type: number + description: filter by rates greater than this number + lte: + type: number + description: filter by rates less than or equal to this number + gte: + type: number + description: filter by rates greater than or equal to this number + - in: query + name: offset + description: The number of tax rates to skip when retrieving the tax rates. + schema: + type: integer + default: 0 + - in: query + name: limit + description: Limit the number of tax rates returned. + schema: + type: integer + default: 50 + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned tax + rate. + style: form + explode: false + schema: + type: array + items: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + tax rate. + style: form + explode: false + schema: + type: array + items: + type: string + x-codegen: + method: list + queryParams: AdminGetTaxRatesParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.taxRates.list() + + .then(({ tax_rates, limit, offset, count }) => { + console.log(tax_rates.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/tax-rates' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Tax Rates + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminTaxRatesListRes' + '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: PostTaxRates + summary: Create a Tax Rate + description: Create a Tax Rate. + parameters: + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned tax + rate. + style: form + explode: false + schema: + type: array + items: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + tax rate. + style: form + explode: false + schema: + type: array + items: + type: string + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostTaxRatesReq' + x-codegen: + method: create + queryParams: AdminPostTaxRatesParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.taxRates.create({ + code: "TEST", + name: "New Tax Rate", + region_id + }) + + .then(({ tax_rate }) => { + console.log(tax_rate.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/tax-rates' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "code": "TEST", + "name": "New Tax Rate", + "region_id": "{region_id}" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Tax Rates + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminTaxRatesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/tax-rates/{id}: + get: + operationId: GetTaxRatesTaxRate + summary: Get a Tax Rate + description: Retrieve a Tax Rate's details. + parameters: + - in: path + name: id + required: true + description: ID of the tax rate. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned tax + rate. + style: form + explode: false + schema: + type: array + items: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + tax rate. + style: form + explode: false + schema: + type: array + items: + type: string + x-authenticated: true + x-codegen: + method: retrieve + queryParams: AdminGetTaxRatesTaxRateParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.taxRates.retrieve(taxRateId) + + .then(({ tax_rate }) => { + console.log(tax_rate.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/tax-rates/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Tax Rates + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminTaxRatesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostTaxRatesTaxRate + summary: Update a Tax Rate + description: Update a Tax Rate's details. + parameters: + - in: path + name: id + required: true + description: ID of the tax rate. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned tax + rate. + style: form + explode: false + schema: + type: array + items: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + tax rate. + style: form + explode: false + schema: + type: array + items: + type: string + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostTaxRatesTaxRateReq' + x-codegen: + method: update + queryParams: AdminPostTaxRatesTaxRateParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.taxRates.update(taxRateId, { + name: "New Tax Rate" + }) + + .then(({ tax_rate }) => { + console.log(tax_rate.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/tax-rates/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "name": "New Tax Rate" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Tax Rates + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminTaxRatesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteTaxRatesTaxRate + summary: Delete a Tax Rate + description: >- + Delete a Tax Rate. Resources associated with the tax rate, such as + products or product types, are not deleted. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the Shipping Option. + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.taxRates.delete(taxRateId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/tax-rates/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Tax Rates + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminTaxRatesDeleteRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/tax-rates/{id}/product-types/batch: + post: + operationId: PostTaxRatesTaxRateProductTypes + summary: Add to Product Types + description: Associates a Tax Rate with a list of Product Types + parameters: + - in: path + name: id + required: true + description: ID of the tax rate. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned tax + rate. + style: form + explode: false + schema: + type: array + items: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + tax rate. + style: form + explode: false + schema: + type: array + items: + type: string + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostTaxRatesTaxRateProductTypesReq' + x-codegen: + method: addProductTypes + queryParams: AdminPostTaxRatesTaxRateProductTypesParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.taxRates.addProductTypes(taxRateId, { + product_types: [ + productTypeId + ] + }) + + .then(({ tax_rate }) => { + console.log(tax_rate.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/tax-rates/{id}/product-types/batch' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "product_types": [ + "{product_type_id}" + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Tax Rates + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminTaxRatesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteTaxRatesTaxRateProductTypes + summary: Remove Product Types from Rate + description: >- + Remove product types from a tax rate. This only removes the association + between the product types and the tax rate. It does not delete the + product types. + parameters: + - in: path + name: id + required: true + description: ID of the tax rate. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned tax + rate. + style: form + explode: false + schema: + type: array + items: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + tax rate. + style: form + explode: false + schema: + type: array + items: + type: string + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDeleteTaxRatesTaxRateProductTypesReq' + x-codegen: + method: removeProductTypes + queryParams: AdminDeleteTaxRatesTaxRateProductTypesParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.taxRates.removeProductTypes(taxRateId, { + product_types: [ + productTypeId + ] + }) + + .then(({ tax_rate }) => { + console.log(tax_rate.id); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/tax-rates/{id}/product-types/batch' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "product_types": [ + "{product_type_id}" + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Tax Rates + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminTaxRatesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/tax-rates/{id}/products/batch: + post: + operationId: PostTaxRatesTaxRateProducts + summary: Add to Products + description: Associates a Tax Rate with a list of Products. + parameters: + - in: path + name: id + required: true + description: ID of the tax rate. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned tax + rate. + style: form + explode: false + schema: + type: array + items: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + tax rate. + style: form + explode: false + schema: + type: array + items: + type: string + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostTaxRatesTaxRateProductsReq' + x-codegen: + method: addProducts + queryParams: AdminPostTaxRatesTaxRateProductsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.taxRates.addProducts(taxRateId, { + products: [ + productId + ] + }) + + .then(({ tax_rate }) => { + console.log(tax_rate.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/tax-rates/{id}/products/batch' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "products": [ + "{product_id}" + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Tax Rates + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminTaxRatesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteTaxRatesTaxRateProducts + summary: Remove Products from Rate + description: >- + Remove products from a tax rate. This only removes the association + between the products and the tax rate. It does not delete the products. + parameters: + - in: path + name: id + required: true + description: ID of the tax rate. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned tax + rate. + style: form + explode: false + schema: + type: array + items: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + tax rate. + style: form + explode: false + schema: + type: array + items: + type: string + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDeleteTaxRatesTaxRateProductsReq' + x-codegen: + method: removeProducts + queryParams: AdminDeleteTaxRatesTaxRateProductsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.taxRates.removeProducts(taxRateId, { + products: [ + productId + ] + }) + + .then(({ tax_rate }) => { + console.log(tax_rate.id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/tax-rates/{id}/products/batch' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "products": [ + "{product_id}" + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Tax Rates + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminTaxRatesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/tax-rates/{id}/shipping-options/batch: + post: + operationId: PostTaxRatesTaxRateShippingOptions + summary: Add to Shipping Options + description: Associates a Tax Rate with a list of Shipping Options. + parameters: + - in: path + name: id + required: true + description: ID of the tax rate. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned tax + rate. + style: form + explode: false + schema: + type: array + items: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + tax rate. + style: form + explode: false + schema: + type: array + items: + type: string + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostTaxRatesTaxRateShippingOptionsReq' + x-codegen: + method: addShippingOptions + queryParams: AdminPostTaxRatesTaxRateShippingOptionsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.taxRates.addShippingOptions(taxRateId, { + shipping_options: [ + shippingOptionId + ] + }) + + .then(({ tax_rate }) => { + console.log(tax_rate.id); + }); + - lang: Shell + label: cURL + source: > + curl -X POST + '{backend_url}/admin/tax-rates/{id}/shipping-options/batch' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "shipping_options": [ + "{shipping_option_id}" + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Tax Rates + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminTaxRatesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteTaxRatesTaxRateShippingOptions + summary: Remove Shipping Options from Rate + description: >- + Remove shipping options from a tax rate. This only removes the + association between the shipping options and the tax rate. It does not + delete the shipping options. + parameters: + - in: path + name: id + required: true + description: ID of the tax rate. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned tax + rate. + style: form + explode: false + schema: + type: array + items: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + tax rate. + style: form + explode: false + schema: + type: array + items: + type: string + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: >- + #/components/schemas/AdminDeleteTaxRatesTaxRateShippingOptionsReq + x-codegen: + method: removeShippingOptions + queryParams: AdminDeleteTaxRatesTaxRateShippingOptionsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.taxRates.removeShippingOptions(taxRateId, { + shipping_options: [ + shippingOptionId + ] + }) + + .then(({ tax_rate }) => { + console.log(tax_rate.id); + }); + - lang: Shell + label: cURL + source: > + curl -X DELETE + '{backend_url}/admin/tax-rates/{id}/shipping-options/batch' \ + + -H 'x-medusa-access-token: {api_token}' \ + + -H 'Content-Type: application/json' \ + + --data-raw '{ + "shipping_options": [ + "{shipping_option_id}" + ] + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Tax Rates + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminTaxRatesRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/uploads: + post: + operationId: PostUploads + summary: Upload Files + description: >- + Upload at least one file to a public bucket or storage. The file upload + is handled by the file service installed on the Medusa backend. + x-authenticated: true + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + files: + type: string + format: binary + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.uploads.create(file) + + .then(({ uploads }) => { + console.log(uploads.length); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/uploads' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: image/jpeg' \ + --form 'files=@""' \ + --form 'files=@""' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Uploads + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminUploadsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteUploads + summary: Delete an Uploaded File + description: >- + Delete an uploaded file from storage. The file is deleted using the + installed file service on the Medusa backend. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDeleteUploadsReq' + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.uploads.delete({ + file_key + }) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/uploads' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "file_key": "{file_key}" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Uploads + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDeleteUploadsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/uploads/download-url: + post: + operationId: PostUploadsDownloadUrl + summary: Get a File's Download URL + description: >- + Create and retrieve a presigned or public download URL for a file. The + URL creation is handled by the file service installed on the Medusa + backend. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminPostUploadsDownloadUrlReq' + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.uploads.getPresignedDownloadUrl({ + file_key + }) + + .then(({ download_url }) => { + console.log(download_url); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/uploads/download-url' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "file_key": "{file_key}" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Uploads + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminUploadsDownloadUrlRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/uploads/protected: + post: + operationId: PostUploadsProtected + summary: Protected File Upload + description: >- + Upload at least one file to an ACL or a non-public bucket. The file + upload is handled by the file service installed on the Medusa backend. + x-authenticated: true + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + files: + type: string + format: binary + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.uploads.createProtected(file) + + .then(({ uploads }) => { + console.log(uploads.length); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/uploads/protected' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: image/jpeg' \ + --form 'files=@""' \ + --form 'files=@""' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Uploads + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminUploadsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/users: + get: + operationId: GetUsers + summary: List Users + description: Retrieve all admin users. + x-authenticated: true + x-codegen: + method: list + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.users.list() + + .then(({ users }) => { + console.log(users.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/users' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Users + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminUsersListRes' + '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: PostUsers + summary: Create a User + description: >- + Create an admin User. The user has the same privileges as all admin + users, and will be able to authenticate and perform admin + functionalities right after creation. + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminCreateUserRequest' + 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 }) + + // must be previously logged in or use api token + + medusa.admin.users.create({ + email: "user@example.com", + password: "supersecret" + }) + + .then(({ user }) => { + console.log(user.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/users' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "email": "user@example.com", + "password": "supersecret" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Users + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminUserRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/users/password-token: + post: + operationId: PostUsersUserPasswordToken + summary: Request Password Reset + description: Generate a password token for an admin user with a given email. + externalDocs: + description: How to reset a user's password + url: >- + https://docs.medusajs.com/modules/users/admin/manage-profile#reset-password + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminResetPasswordTokenRequest' + x-codegen: + method: sendResetPasswordToken + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.users.sendResetPasswordToken({ + email: "user@example.com" + }) + + .then(() => { + // successful + }) + + .catch(() => { + // error occurred + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/users/password-token' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "email": "user@example.com" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Users + responses: + '204': + description: OK + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/users/reset-password: + post: + operationId: PostUsersUserPassword + summary: Reset Password + description: >- + Reset the password of an admin User using their reset password token. A + user must request to reset their password first before attempting to + reset their password with this request. + externalDocs: + description: How to reset a user's password + url: >- + https://docs.medusajs.com/modules/users/admin/manage-profile#reset-password + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminResetPasswordRequest' + x-codegen: + method: resetPassword + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.users.resetPassword({ + token: "supersecrettoken", + password: "supersecret" + }) + + .then(({ user }) => { + console.log(user.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/users/reset-password' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "token": "supersecrettoken", + "password": "supersecret" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Users + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminUserRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/users/{id}: + get: + operationId: GetUsersUser + summary: Get a User + description: Retrieve an admin user's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the User. + 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 }) + + // must be previously logged in or use api token + + medusa.admin.users.retrieve(userId) + + .then(({ user }) => { + console.log(user.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/users/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Users + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminUserRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostUsersUser + summary: Update a User + description: Update an admin user's details. + parameters: + - in: path + name: id + required: true + description: The ID of the User. + schema: + type: string + x-authenticated: true + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AdminUpdateUserRequest' + x-codegen: + method: update + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.users.update(userId, { + first_name: "Marcellus" + }) + + .then(({ user }) => { + console.log(user.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/admin/users/{id}' \ + -H 'x-medusa-access-token: {api_token}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "first_name": "Marcellus" + }' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Users + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminUserRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteUsersUser + summary: Delete a User + description: >- + Delete a User. Once deleted, the user will not be able to authenticate + or perform admin functionalities. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the User. + schema: + type: string + x-codegen: + method: delete + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.users.delete(userId) + + .then(({ id, object, deleted }) => { + console.log(id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/admin/users/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Users + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminDeleteUserRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/variants: + get: + operationId: GetVariants + summary: List Product Variants + description: >- + Retrieve a list of Product Variants. The product variant can be filtered + by fields such as `id` or `title`. The product variant can also be + paginated. + x-authenticated: true + parameters: + - in: query + name: id + style: form + explode: false + description: Filter by product variant IDs. + schema: + oneOf: + - type: string + description: A product variant ID. + - type: array + description: An array of product variant IDs. + items: + type: string + - in: query + name: expand + description: >- + "Comma-separated relations that should be expanded in the returned + product variants." + schema: + type: string + - in: query + name: fields + description: >- + "Comma-separated fields that should be included in the returned + product variants." + schema: + type: string + - in: query + name: offset + description: >- + The number of product variants to skip when retrieving the product + variants. + schema: + type: number + default: '0' + - in: query + name: limit + description: Limit the number of product variants returned. + schema: + type: number + default: '100' + - in: query + name: cart_id + style: form + explode: false + description: The ID of the cart to use for the price selection context. + schema: + type: string + - in: query + name: region_id + style: form + explode: false + description: The ID of the region to use for the price selection context. + schema: + type: string + externalDocs: + description: Price selection context overview + url: >- + https://docs.medusajs.com/modules/price-lists/price-selection-strategy#context-object + - in: query + name: currency_code + style: form + explode: false + description: >- + The 3 character ISO currency code to use for the price selection + context. + schema: + type: string + externalDocs: + description: Price selection context overview + url: >- + https://docs.medusajs.com/modules/price-lists/price-selection-strategy#context-object + - in: query + name: customer_id + style: form + explode: false + description: The ID of the customer to use for the price selection context. + schema: + type: string + externalDocs: + description: Price selection context overview + url: >- + https://docs.medusajs.com/modules/price-lists/price-selection-strategy#context-object + - in: query + name: title + style: form + explode: false + description: Filter by title. + schema: + oneOf: + - type: string + description: a single title to filter by + - type: array + description: multiple titles to filter by + items: + type: string + - in: query + name: inventory_quantity + description: Filter by available inventory quantity + schema: + oneOf: + - type: number + description: a specific number to filter by. + - type: object + description: filter using less and greater than comparisons. + properties: + lt: + type: number + description: filter by inventory quantity less than this number + gt: + type: number + description: filter by inventory quantity greater than this number + lte: + type: number + description: >- + filter by inventory quantity less than or equal to this + number + gte: + type: number + description: >- + filter by inventory quantity greater than or equal to this + number + x-codegen: + method: list + queryParams: AdminGetVariantsParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.variants.list() + + .then(({ variants, limit, offset, count }) => { + console.log(variants.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/variants' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Variants + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminVariantsListRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/variants/{id}: + get: + operationId: GetVariantsVariant + summary: Get a Product variant + description: Retrieve a product variant's details. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The ID of the product variant. + schema: + type: string + - in: query + name: expand + description: >- + "Comma-separated relations that should be expanded in the returned + product variant." + schema: + type: string + - in: query + name: fields + description: >- + "Comma-separated fields that should be included in the returned + product variant." + schema: + type: string + x-codegen: + method: retrieve + queryParams: AdminGetVariantParams + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.variants.retrieve(variantId) + + .then(({ variant }) => { + console.log(variant.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/variants/{id}' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Variants + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminVariantsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /admin/variants/{id}/inventory: + get: + operationId: GetVariantsVariantInventory + summary: Get Variant's Inventory + description: Retrieve the available inventory of a Product Variant. + x-authenticated: true + parameters: + - in: path + name: id + required: true + description: The Product Variant ID. + schema: + type: string + x-codegen: + method: getInventory + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged in or use api token + + medusa.admin.variants.getInventory(variantId) + + .then(({ variant }) => { + console.log(variant.inventory, variant.sales_channel_availability) + }) + - lang: Shell + label: cURL + source: | + curl '{backend_url}/admin/variants/{id}/inventory' \ + -H 'x-medusa-access-token: {api_token}' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Variants + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AdminGetVariantsVariantInventoryRes' + '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' +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: + api_token: + type: apiKey + x-displayName: API Token + in: header + name: x-medusa-access-token + jwt_token: + type: http + x-displayName: JWT Token + scheme: bearer + cookie_auth: + type: apiKey + in: cookie + name: connect.sid + x-displayName: Cookie Session ID + 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 + 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 + AdminAppsListRes: + type: object + required: + - apps + properties: + apps: + type: array + description: An array of app details. + items: + $ref: '#/components/schemas/OAuth' + AdminAppsRes: + type: object + required: + - apps + properties: + apps: + description: App details. + $ref: '#/components/schemas/OAuth' + AdminAuthRes: + type: object + required: + - user + properties: + user: + description: User details. + $ref: '#/components/schemas/User' + AdminBatchJobListRes: + type: object + required: + - batch_jobs + - count + - offset + - limit + properties: + batch_jobs: + type: array + description: An array of batch job details. + items: + $ref: '#/components/schemas/BatchJob' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: The number of batch jobs skipped when retrieving the batch jobs. + limit: + type: integer + description: The number of items per page + AdminBatchJobRes: + type: object + required: + - batch_job + properties: + batch_job: + description: Batch job details. + $ref: '#/components/schemas/BatchJob' + AdminBearerAuthRes: + type: object + properties: + access_token: + description: Access token that can be used to send authenticated requests. + type: string + AdminCollectionsDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted Collection + object: + type: string + description: The type of the object that was deleted. + default: product-collection + deleted: + type: boolean + description: Whether the collection was deleted successfully or not. + default: true + AdminCollectionsListRes: + type: object + required: + - collections + - count + - offset + - limit + properties: + collections: + type: array + description: an array of collection 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 + AdminCollectionsRes: + type: object + x-expanded-relations: + field: collection + relations: + - products + required: + - collection + properties: + collection: + type: Product Collection details. + $ref: '#/components/schemas/ProductCollection' + AdminCreateUserRequest: + type: object + required: + - email + - password + properties: + email: + description: The User's email. + type: string + format: email + first_name: + description: The first name of the User. + type: string + last_name: + description: The last name of the User. + type: string + role: + description: >- + The role assigned to the user. These roles don't provide any + different privileges. + type: string + enum: + - admin + - member + - developer + password: + description: The User's password. + type: string + format: password + AdminCurrenciesListRes: + type: object + required: + - currencies + - count + - offset + - limit + properties: + currencies: + type: array + description: An array of currency details. + items: + $ref: '#/components/schemas/Currency' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: The number of currencies skipped when retrieving the currencies. + limit: + type: integer + description: The number of items per page + AdminCurrenciesRes: + type: object + required: + - currency + properties: + currency: + description: Currency details. + $ref: '#/components/schemas/Currency' + AdminCustomerGroupsDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted customer group. + object: + type: string + description: The type of the object that was deleted. + default: customer_group + deleted: + type: boolean + description: Whether the customer group was deleted successfully or not. + default: true + AdminCustomerGroupsListRes: + type: object + required: + - customer_groups + - count + - offset + - limit + properties: + customer_groups: + type: array + description: An array of customer group details. + items: + $ref: '#/components/schemas/CustomerGroup' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: >- + The number of customer groups skipped when retrieving the customer + groups. + limit: + type: integer + description: The number of items per page + AdminCustomerGroupsRes: + type: object + required: + - customer_group + properties: + customer_group: + description: Customer group details. + $ref: '#/components/schemas/CustomerGroup' + AdminCustomersListRes: + type: object + required: + - customers + - count + - offset + - limit + properties: + customers: + type: array + description: An array of customer details. + items: + $ref: '#/components/schemas/Customer' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: The number of customers skipped when retrieving the customers. + limit: + type: integer + description: The number of items per page + AdminCustomersRes: + type: object + x-expanded-relations: + field: customer + relations: + - orders + - shipping_addresses + required: + - customer + properties: + customer: + description: Customer details. + $ref: '#/components/schemas/Customer' + AdminDeleteCustomerGroupsGroupCustomerBatchReq: + type: object + required: + - customer_ids + properties: + customer_ids: + description: The ids of the customers to remove + type: array + items: + type: object + required: + - id + properties: + id: + description: ID of the customer + type: string + AdminDeleteDiscountsDiscountConditionsConditionBatchReq: + type: object + required: + - resources + properties: + resources: + description: The resources to be removed from the discount condition + type: array + items: + type: object + required: + - id + properties: + id: + description: The id of the item + type: string + AdminDeletePriceListPricesPricesReq: + type: object + properties: + price_ids: + description: The price IDs of the Money Amounts to delete. + type: array + items: + type: string + AdminDeletePriceListsPriceListProductsPricesBatchReq: + type: object + properties: + product_ids: + description: The IDs of the products to delete their associated prices. + type: array + items: + type: string + AdminDeleteProductCategoriesCategoryProductsBatchReq: + type: object + required: + - product_ids + properties: + product_ids: + description: The IDs of the products to delete from the Product Category. + type: array + items: + type: object + required: + - id + properties: + id: + description: The ID of a product + type: string + AdminDeleteProductsFromCollectionReq: + type: object + required: + - product_ids + properties: + product_ids: + description: An array of Product IDs to remove from the Product Collection. + type: array + items: + description: The ID of a Product to add to the Product Collection. + type: string + AdminDeleteProductsFromCollectionRes: + type: object + required: + - id + - object + - removed_products + properties: + id: + type: string + description: The ID of the collection + object: + type: string + description: The type of object the removal was executed on + default: product-collection + removed_products: + description: The IDs of the products removed from the collection + type: array + items: + description: The ID of the Product removed from the Product Collection. + type: string + AdminDeletePublishableApiKeySalesChannelsBatchReq: + type: object + required: + - sales_channel_ids + properties: + sales_channel_ids: + description: The IDs of the sales channels to remove from the publishable API key + type: array + items: + type: object + required: + - id + properties: + id: + type: string + description: The ID of the sales channel + AdminDeleteSalesChannelsChannelProductsBatchReq: + type: object + required: + - product_ids + properties: + product_ids: + description: The IDs of the products to remove from the Sales Channel. + type: array + items: + type: object + required: + - id + properties: + id: + description: The ID of a product + type: string + AdminDeleteSalesChannelsChannelStockLocationsReq: + type: object + required: + - location_id + properties: + location_id: + description: The ID of the stock location + type: string + AdminDeleteShippingProfileRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted Shipping Profile. + object: + type: string + description: The type of the object that was deleted. + default: shipping_profile + deleted: + type: boolean + description: Whether or not the items were deleted. + default: true + AdminDeleteTaxRatesTaxRateProductTypesReq: + type: object + required: + - product_types + properties: + product_types: + type: array + description: >- + The IDs of the product types to remove their association with this + tax rate. + items: + type: string + AdminDeleteTaxRatesTaxRateProductsReq: + type: object + required: + - products + properties: + products: + type: array + description: >- + The IDs of the products to remove their association with this tax + rate. + items: + type: string + AdminDeleteTaxRatesTaxRateShippingOptionsReq: + type: object + required: + - shipping_options + properties: + shipping_options: + type: array + description: >- + The IDs of the shipping options to remove their association with + this tax rate. + items: + type: string + AdminDeleteUploadsReq: + type: object + required: + - file_key + properties: + file_key: + description: >- + key of the file to delete. This is obtained when you first uploaded + the file, or by the file service if you used it directly. + type: string + AdminDeleteUploadsRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The file key of the upload deleted + object: + type: string + description: The type of the object that was deleted. + default: file + deleted: + type: boolean + description: Whether or not the items were deleted. + default: true + AdminDeleteUserRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted user. + object: + type: string + description: The type of the object that was deleted. + default: user + deleted: + type: boolean + description: Whether or not the items were deleted. + default: true + AdminDiscountConditionsDeleteRes: + type: object + required: + - id + - object + - deleted + - discount + properties: + id: + type: string + description: The ID of the deleted Discount Condition + object: + type: string + description: The type of the object that was deleted. + default: discount-condition + deleted: + type: boolean + description: Whether the discount condition was deleted successfully. + default: true + discount: + description: The Discount to which the condition used to belong to. + $ref: '#/components/schemas/Discount' + AdminDiscountConditionsRes: + type: object + x-expanded-relations: + field: discount_condition + relations: + - discount_rule + required: + - discount_condition + properties: + discount_condition: + description: Discount condition details. + $ref: '#/components/schemas/DiscountCondition' + AdminDiscountsDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted Discount + object: + type: string + description: The type of the object that was deleted. + default: discount + deleted: + type: boolean + description: Whether the discount was deleted successfully. + default: true + AdminDiscountsListRes: + type: object + x-expanded-relations: + field: discounts + relations: + - parent_discount + - regions + - rule + - rule.conditions + required: + - discounts + - count + - offset + - limit + properties: + discounts: + type: array + items: + $ref: '#/components/schemas/Discount' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: The number of discounts skipped when retrieving the discounts. + limit: + type: integer + description: The number of items per page + AdminDiscountsRes: + type: object + x-expanded-relations: + field: discount + relations: + - parent_discount + - regions + - rule + - rule.conditions + eager: + - regions.fulfillment_providers + - regions.payment_providers + required: + - discount + properties: + discount: + description: Discount details. + $ref: '#/components/schemas/Discount' + AdminDraftOrdersDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted Draft Order. + object: + type: string + description: The type of the object that was deleted. + default: draft-order + deleted: + type: boolean + description: Whether the draft order was deleted successfully. + default: true + AdminDraftOrdersListRes: + type: object + x-expanded-relations: + field: draft_orders + relations: + - order + - cart + - cart.items + - cart.items.adjustments + required: + - draft_orders + - count + - offset + - limit + properties: + draft_orders: + type: array + description: An array of draft order's details. + items: + $ref: '#/components/schemas/DraftOrder' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: The number of draft orders skipped when retrieving the draft orders. + limit: + type: integer + description: The number of items per page + AdminDraftOrdersRes: + type: object + x-expanded-relations: + field: draft_order + relations: + - order + - cart + - cart.items + - cart.items.adjustments + - cart.billing_address + - cart.customer + - cart.discounts + - cart.discounts.rule + - cart.items + - cart.items.adjustments + - cart.payment + - cart.payment_sessions + - cart.region + - cart.region.payment_providers + - cart.shipping_address + - cart.shipping_methods + - cart.shipping_methods.shipping_option + eager: + - cart.region.fulfillment_providers + - cart.region.payment_providers + - cart.shipping_methods.shipping_option + implicit: + - cart.discounts + - cart.discounts.rule + - cart.gift_cards + - cart.items + - cart.items.adjustments + - cart.items.tax_lines + - cart.items.variant + - cart.items.variant.product + - cart.items.variant.product.profiles + - cart.region + - cart.region.tax_rates + - cart.shipping_address + - cart.shipping_methods + - cart.shipping_methods.tax_lines + totals: + - cart.discount_total + - cart.gift_card_tax_total + - cart.gift_card_total + - cart.item_tax_total + - cart.refundable_amount + - cart.refunded_total + - cart.shipping_tax_total + - cart.shipping_total + - cart.subtotal + - cart.tax_total + - cart.total + - cart.items.discount_total + - cart.items.gift_card_total + - cart.items.original_tax_total + - cart.items.original_total + - cart.items.refundable + - cart.items.subtotal + - cart.items.tax_total + - cart.items.total + required: + - draft_order + properties: + draft_order: + description: Draft order's details. + $ref: '#/components/schemas/DraftOrder' + AdminExtendedStoresRes: + type: object + x-expanded-relations: + field: store + relations: + - currencies + - default_currency + required: + - store + properties: + store: + description: Store details. + $ref: '#/components/schemas/ExtendedStoreDTO' + AdminGetRegionsRegionFulfillmentOptionsRes: + type: object + required: + - fulfillment_options + properties: + fulfillment_options: + type: array + description: Fulfillment providers details. + items: + type: object + required: + - provider_id + - options + properties: + provider_id: + description: ID of the fulfillment provider + type: string + options: + description: fulfillment provider options + type: array + items: + type: object + example: + - id: manual-fulfillment + - id: manual-fulfillment-return + is_return: true + AdminGetVariantsVariantInventoryRes: + type: object + properties: + variant: + type: object + description: The product variant's. + $ref: '#/components/schemas/VariantInventory' + AdminGiftCardsDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted Gift Card + object: + type: string + description: The type of the object that was deleted. + default: gift-card + deleted: + type: boolean + description: Whether the gift card was deleted successfully. + default: true + AdminGiftCardsListRes: + type: object + x-expanded-relations: + field: gift_cards + relations: + - order + - region + eager: + - region.fulfillment_providers + - region.payment_providers + required: + - gift_cards + - count + - offset + - limit + properties: + gift_cards: + type: array + items: + $ref: '#/components/schemas/GiftCard' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: The number of gift cards skipped when retrieving the gift cards. + limit: + type: integer + description: The number of items per page + AdminGiftCardsRes: + type: object + x-expanded-relations: + field: gift_card + relations: + - order + - region + eager: + - region.fulfillment_providers + - region.payment_providers + required: + - gift_card + properties: + gift_card: + description: A gift card's details. + $ref: '#/components/schemas/GiftCard' + AdminInventoryItemsDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted Inventory Item. + object: + type: string + description: The type of the object that was deleted. + format: inventory_item + deleted: + type: boolean + description: Whether or not the Inventory Item was deleted. + default: true + AdminInventoryItemsListRes: + type: object + required: + - inventory_items + - count + - offset + - limit + properties: + inventory_items: + type: array + description: an array of Inventory Item details + items: + $ref: '#/components/schemas/InventoryItemDTO' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: >- + The number of inventory items skipped when retrieving the inventory + items. + limit: + type: integer + description: The number of items per page + AdminInventoryItemsListWithVariantsAndLocationLevelsRes: + type: object + required: + - inventory_items + - count + - offset + - limit + properties: + inventory_items: + type: array + description: an array of Inventory Item details + items: + $ref: '#/components/schemas/DecoratedInventoryItemDTO' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: >- + The number of inventory items skipped when retrieving the inventory + items. + limit: + type: integer + description: The number of items per page + AdminInventoryItemsLocationLevelsRes: + type: object + required: + - inventory_item + properties: + inventory_item: + type: object + required: + - id + - location_levels + properties: + id: + description: The id of the location + location_levels: + description: List of stock levels at a given location + type: array + items: + $ref: '#/components/schemas/InventoryLevelDTO' + AdminInventoryItemsRes: + type: object + required: + - inventory_item + properties: + inventory_item: + description: Inventory Item details + $ref: '#/components/schemas/InventoryItemDTO' + AdminInviteDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted Invite. + object: + type: string + description: The type of the object that was deleted. + default: invite + deleted: + type: boolean + description: Whether or not the invite was deleted. + default: true + AdminListInvitesRes: + type: object + required: + - invites + properties: + invites: + type: array + description: An array of invites + items: + $ref: '#/components/schemas/Invite' + AdminNotesDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted Note. + object: + type: string + description: The type of the object that was deleted. + default: note + deleted: + type: boolean + description: Whether or not the Note was deleted. + default: true + AdminNotesListRes: + type: object + required: + - notes + - count + - offset + - limit + properties: + notes: + type: array + description: An array of notes + items: + $ref: '#/components/schemas/Note' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: The number of notes skipped when retrieving the notes. + limit: + type: integer + description: The number of items per page + AdminNotesRes: + type: object + required: + - note + properties: + note: + description: Note details. + $ref: '#/components/schemas/Note' + AdminNotificationsListRes: + type: object + x-expanded-relations: + field: notifications + relations: + - resends + required: + - notifications + properties: + notifications: + type: array + description: an array of notifications + items: + $ref: '#/components/schemas/Notification' + count: + type: integer + description: The total number of notifications + offset: + type: integer + description: >- + The number of notifications skipped when retrieving the + notifications. + limit: + type: integer + description: The number of notifications per page + AdminNotificationsRes: + type: object + x-expanded-relations: + field: notification + relations: + - resends + required: + - notification + properties: + notification: + description: Notification details + $ref: '#/components/schemas/Notification' + AdminOrderEditDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted Order Edit. + object: + type: string + description: The type of the object that was deleted. + default: order_edit + deleted: + type: boolean + description: Whether or not the Order Edit was deleted. + default: true + AdminOrderEditItemChangeDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted Order Edit Item Change. + object: + type: string + description: The type of the object that was deleted. + default: item_change + deleted: + type: boolean + description: Whether or not the Order Edit Item Change was deleted. + default: true + AdminOrderEditsListRes: + type: object + x-expanded-relations: + field: order_edits + 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_edits + - count + - offset + - limit + properties: + order_edits: + type: array + description: An array of order edit details + items: + $ref: '#/components/schemas/OrderEdit' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: The number of order edits skipped when retrieving the order edits. + limit: + type: integer + description: The number of items per page + AdminOrderEditsRes: + type: object + 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' + AdminOrdersListRes: + type: object + x-expanded-relations: + field: orders + relations: + - billing_address + - claims + - claims.additional_items + - claims.additional_items.variant + - claims.claim_items + - claims.claim_items.images + - claims.claim_items.item + - claims.fulfillments + - claims.fulfillments.tracking_links + - claims.return_order + - claims.return_order.shipping_method + - claims.return_order.shipping_method.tax_lines + - claims.shipping_address + - claims.shipping_methods + - customer + - discounts + - discounts.rule + - fulfillments + - fulfillments.items + - fulfillments.tracking_links + - gift_card_transactions + - gift_cards + - items + - payments + - refunds + - region + - returns + - returns.items + - returns.items.reason + - returns.shipping_method + - returns.shipping_method.tax_lines + - shipping_address + - shipping_methods + eager: + - fulfillments.items + - region.fulfillment_providers + - region.payment_providers + - returns.items + - 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 + required: + - orders + - count + - offset + - limit + properties: + orders: + type: array + description: An array of order details. + items: + $ref: '#/components/schemas/Order' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: The number of orders skipped when retrieving the orders. + limit: + type: integer + description: The number of items per page + AdminOrdersOrderLineItemReservationReq: + type: object + required: + - location_id + properties: + location_id: + description: The ID of the location of the reservation + type: string + quantity: + description: The quantity to reserve + type: number + AdminOrdersRes: + type: object + x-expanded-relations: + field: order + relations: + - billing_address + - claims + - claims.additional_items + - claims.additional_items.variant + - claims.claim_items + - claims.claim_items.images + - claims.claim_items.item + - claims.fulfillments + - claims.fulfillments.tracking_links + - claims.return_order + - claims.return_order.shipping_method + - claims.return_order.shipping_method.tax_lines + - claims.shipping_address + - claims.shipping_methods + - customer + - discounts + - discounts.rule + - fulfillments + - fulfillments.items + - fulfillments.tracking_links + - gift_card_transactions + - gift_cards + - items + - payments + - refunds + - region + - returns + - returns.items + - returns.items.reason + - returns.shipping_method + - returns.shipping_method.tax_lines + - shipping_address + - shipping_methods + eager: + - fulfillments.items + - region.fulfillment_providers + - region.payment_providers + - returns.items + - 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 + required: + - order + properties: + order: + description: Order details. + $ref: '#/components/schemas/Order' + AdminPaymentCollectionDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted Payment Collection. + object: + type: string + description: The type of the object that was deleted. + default: payment_collection + deleted: + type: boolean + description: Whether or not the Payment Collection was deleted. + default: true + AdminPaymentCollectionsRes: + type: object + x-expanded-relations: + field: payment_collection + relations: + - payment_sessions + - payments + - region + eager: + - region.fulfillment_providers + - region.payment_providers + required: + - payment_collection + properties: + payment_collection: + description: Payment Collection details. + $ref: '#/components/schemas/PaymentCollection' + AdminPaymentProvidersList: + type: object + required: + - payment_providers + properties: + payment_providers: + type: array + description: An array of payment providers details. + items: + $ref: '#/components/schemas/PaymentProvider' + AdminPaymentRes: + type: object + required: + - payment + properties: + payment: + description: Payment details + $ref: '#/components/schemas/Payment' + AdminPostAppsReq: + type: object + required: + - application_name + - state + - code + properties: + application_name: + type: string + description: Name of the application for to generate the token for. + state: + type: string + description: State of the application. + code: + type: string + description: The code for the generated token. + AdminPostAuthReq: + type: object + required: + - email + - password + properties: + email: + type: string + description: The user's email. + format: email + password: + type: string + description: The user's password. + format: password + AdminPostBatchesReq: + type: object + required: + - type + - context + properties: + type: + type: string + description: >- + The type of batch job to start, which is defined by the `batchType` + property of the associated batch job strategy. + example: product-export + context: + type: object + description: >- + Additional infomration regarding the batch to be used for + processing. + 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: + type: boolean + description: >- + Set a batch job in dry_run mode, which would delay executing the + batch job until it's confirmed. + default: false + AdminPostCollectionsCollectionReq: + type: object + properties: + title: + type: string + description: The title of the collection. + handle: + type: string + description: >- + An optional handle to be used in slugs. If none is provided, the + kebab-case version of the title will be used. + metadata: + description: An optional set of key-value pairs to hold additional information. + 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 + AdminPostCollectionsReq: + type: object + required: + - title + properties: + title: + type: string + description: The title of the collection. + handle: + type: string + description: >- + An optional handle to be used in slugs. If none is provided, the + kebab-case version of the title will be used. + metadata: + description: An optional set of key-value pairs to hold additional information. + 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 + AdminPostCurrenciesCurrencyReq: + type: object + properties: + includes_tax: + type: boolean + x-featureFlag: tax_inclusive_pricing + description: Tax included in prices of currency. + AdminPostCustomerGroupsGroupCustomersBatchReq: + type: object + required: + - customer_ids + properties: + customer_ids: + description: The ids of the customers to add + type: array + items: + type: object + required: + - id + properties: + id: + description: ID of the customer + type: string + AdminPostCustomerGroupsGroupReq: + type: object + properties: + name: + description: Name of the customer group + type: string + metadata: + description: Metadata of the customer group. + 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 + AdminPostCustomerGroupsReq: + type: object + required: + - name + properties: + name: + type: string + description: Name of the customer group + metadata: + type: object + description: Metadata of the customer group. + externalDocs: + description: >- + Learn about the metadata attribute, and how to delete and update + it. + url: >- + https://docs.medusajs.com/development/entities/overview#metadata-attribute + AdminPostCustomersCustomerReq: + type: object + properties: + email: + type: string + description: >- + The Customer's email. You can't update the email of a registered + customer. + format: email + first_name: + type: string + description: The Customer's first name. + last_name: + type: string + description: The Customer's last name. + phone: + type: string + description: The Customer's phone number. + password: + type: string + description: The Customer's password. + format: password + groups: + type: array + description: A list of customer groups to which the customer belongs. + items: + type: object + required: + - id + properties: + id: + description: The ID of a customer group + type: string + metadata: + description: An optional set of key-value pairs to hold additional information. + 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 + AdminPostCustomersReq: + type: object + required: + - email + - first_name + - last_name + - password + properties: + email: + type: string + description: The customer's email. + format: email + first_name: + type: string + description: The customer's first name. + last_name: + type: string + description: The customer's last name. + password: + type: string + description: The customer's password. + format: password + phone: + type: string + description: The customer's phone number. + metadata: + description: An optional set of key-value pairs to hold additional information. + 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 + AdminPostDiscountsDiscountConditions: + type: object + required: + - operator + properties: + operator: + description: >- + 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 + products: + type: array + description: list of product IDs if the condition's type is `products`. + items: + type: string + product_types: + type: array + description: list of product type IDs if the condition's type is `product_types`. + items: + type: string + product_collections: + type: array + description: >- + list of product collection IDs if the condition's type is + `product_collections`. + items: + type: string + product_tags: + type: array + description: list of product tag IDs if the condition's type is `product_tags`. + items: + type: string + customer_groups: + type: array + description: >- + list of customer group IDs if the condition's type is + `customer_groups`. + items: + type: string + AdminPostDiscountsDiscountConditionsCondition: + type: object + properties: + products: + type: array + description: list of product IDs if the condition's type is `products`. + items: + type: string + product_types: + type: array + description: list of product type IDs if the condition's type is `product_types`. + items: + type: string + product_collections: + type: array + description: >- + list of product collection IDs if the condition's type is + `product_collections`. + items: + type: string + product_tags: + type: array + description: list of product tag IDs if the condition's type is `product_tags` + items: + type: string + customer_groups: + type: array + description: >- + list of customer group IDs if the condition's type is + `customer_groups`. + items: + type: string + AdminPostDiscountsDiscountConditionsConditionBatchReq: + type: object + required: + - resources + properties: + resources: + description: The resources to be added to the discount condition + type: array + items: + type: object + required: + - id + properties: + id: + description: The id of the item + type: string + AdminPostDiscountsDiscountDynamicCodesReq: + type: object + required: + - code + properties: + code: + type: string + description: A unique code that will be used to redeem the Discount + usage_limit: + type: number + description: Maximum number of times the discount code can be used + default: 1 + metadata: + type: object + description: An optional set of key-value pairs to hold additional information. + externalDocs: + description: >- + Learn about the metadata attribute, and how to delete and update + it. + url: >- + https://docs.medusajs.com/development/entities/overview#metadata-attribute + AdminPostDiscountsDiscountReq: + type: object + properties: + code: + type: string + description: A unique code that will be used to redeem the discount + rule: + description: The discount rule that defines how discounts are calculated + type: object + required: + - id + properties: + id: + type: string + description: The ID of the Rule + description: + type: string + description: A short description of the discount + value: + type: number + description: >- + The value that the discount represents. This will depend on the + type of the discount. + allocation: + type: string + description: >- + The scope that the discount should apply to. `total` indicates + that the discount should be applied on the cart total, and + `item` indicates that the discount should be applied to each + discountable item in the cart. + enum: + - total + - item + conditions: + type: array + description: >- + A set of conditions that can be used to limit when the discount + can be used. Only one of `products`, `product_types`, + `product_collections`, `product_tags`, and `customer_groups` + should be provided based on the discount condition's type. + items: + type: object + required: + - operator + properties: + id: + type: string + description: The ID of the condition + operator: + type: string + description: >- + 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. + enum: + - in + - not_in + products: + type: array + description: list of product IDs if the condition's type is `products`. + items: + type: string + product_types: + type: array + description: >- + list of product type IDs if the condition's type is + `product_types`. + items: + type: string + product_collections: + type: array + description: >- + list of product collection IDs if the condition's type is + `product_collections`. + items: + type: string + product_tags: + type: array + description: >- + list of product tag IDs if the condition's type is + `product_tags`. + items: + type: string + customer_groups: + type: array + description: >- + list of customer group IDs if the condition's type is + `customer_groups`. + items: + type: string + is_disabled: + type: boolean + description: >- + Whether the discount code is disabled on creation. If set to `true`, + it will not be available for customers. + starts_at: + type: string + format: date-time + description: The date and time at which the discount should be available. + ends_at: + type: string + format: date-time + description: >- + The date and time at which the discount should no longer be + available. + valid_duration: + type: string + description: The duration the discount runs between + example: P3Y6M4DT12H30M5S + usage_limit: + type: number + description: Maximum number of times the discount can be used + regions: + description: >- + A list of region IDs representing the Regions in which the Discount + can be used. + type: array + items: + type: string + metadata: + description: An object containing metadata of the discount + 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 + AdminPostDiscountsReq: + type: object + required: + - code + - rule + - regions + properties: + code: + type: string + description: A unique code that will be used to redeem the discount + is_dynamic: + type: boolean + description: >- + Whether the discount should have multiple instances of itself, each + with a different code. This can be useful for automatically + generated discount codes that all have to follow a common set of + rules. + default: false + rule: + description: The discount rule that defines how discounts are calculated + type: object + required: + - type + - value + - allocation + properties: + description: + type: string + description: A short description of the discount + type: + type: string + 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. + enum: + - fixed + - percentage + - free_shipping + value: + type: number + description: >- + The value that the discount represents. This will depend on the + type of the discount. + allocation: + type: string + description: >- + The scope that the discount should apply to. `total` indicates + that the discount should be applied on the cart total, and + `item` indicates that the discount should be applied to each + discountable item in the cart. + enum: + - total + - item + conditions: + type: array + description: >- + A set of conditions that can be used to limit when the discount + can be used. Only one of `products`, `product_types`, + `product_collections`, `product_tags`, and `customer_groups` + should be provided based on the discount condition's type. + items: + type: object + required: + - operator + properties: + operator: + type: string + description: >- + 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. + enum: + - in + - not_in + products: + type: array + description: list of product IDs if the condition's type is `products`. + items: + type: string + product_types: + type: array + description: >- + list of product type IDs if the condition's type is + `product_types`. + items: + type: string + product_collections: + type: array + description: >- + list of product collection IDs if the condition's type is + `product_collections`. + items: + type: string + product_tags: + type: array + description: >- + list of product tag IDs if the condition's type is + `product_tags`. + items: + type: string + customer_groups: + type: array + description: >- + list of customer group IDs if the condition's type is + `customer_groups`. + items: + type: string + is_disabled: + type: boolean + description: >- + Whether the discount code is disabled on creation. If set to `true`, + it will not be available for customers. + default: false + starts_at: + type: string + format: date-time + description: The date and time at which the discount should be available. + ends_at: + type: string + format: date-time + description: >- + The date and time at which the discount should no longer be + available. + valid_duration: + type: string + description: The duration the discount runs between + example: P3Y6M4DT12H30M5S + regions: + description: >- + A list of region IDs representing the Regions in which the Discount + can be used. + type: array + items: + type: string + usage_limit: + type: number + description: Maximum number of times the discount can be used + metadata: + description: An optional set of key-value pairs to hold additional information. + 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 + AdminPostDraftOrdersDraftOrderLineItemsItemReq: + type: object + properties: + unit_price: + description: >- + The custom price of the line item. If a `variant_id` is supplied, + the price provided here will override the variant's price. + type: integer + title: + description: The title of the line item if `variant_id` is not provided. + type: string + quantity: + description: The quantity of the line item. + type: integer + metadata: + description: >- + The optional key-value map with additional details about the Line + Item. + 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 + AdminPostDraftOrdersDraftOrderLineItemsReq: + type: object + required: + - quantity + properties: + variant_id: + description: >- + The ID of the Product Variant associated with the line item. If the + line item is custom, the `variant_id` should be omitted. + type: string + unit_price: + description: >- + The custom price of the line item. If a `variant_id` is supplied, + the price provided here will override the variant's price. + type: integer + title: + description: The title of the line item if `variant_id` is not provided. + type: string + default: Custom item + quantity: + description: The quantity of the line item. + type: integer + metadata: + description: >- + The optional key-value map with additional details about the Line + Item. + 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 + AdminPostDraftOrdersDraftOrderRegisterPaymentRes: + type: object + required: + - order + properties: + order: + description: Order's details. + $ref: '#/components/schemas/Order' + AdminPostDraftOrdersDraftOrderReq: + type: object + properties: + region_id: + type: string + description: The ID of the Region to create the Draft Order in. + country_code: + type: string + description: The 2 character ISO code for the Country. + 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 in the Draft Order. + format: email + billing_address: + description: The Address to be used for billing purposes. + anyOf: + - $ref: '#/components/schemas/AddressPayload' + - type: string + shipping_address: + description: The Address to be used for shipping purposes. + anyOf: + - $ref: '#/components/schemas/AddressPayload' + - type: string + discounts: + description: An array of Discount codes to add to the Draft Order. + type: array + items: + type: object + required: + - code + properties: + code: + description: The code that a Discount is identifed by. + type: string + no_notification_order: + description: >- + An optional flag passed to the resulting order that indicates + whether the customer should receive notifications about order + updates. + type: boolean + customer_id: + description: The ID of the customer this draft order is associated with. + type: string + AdminPostDraftOrdersReq: + type: object + required: + - email + - region_id + - shipping_methods + properties: + status: + description: >- + The status of the draft order. The draft order's default status is + `open`. It's changed to `completed` when its payment is marked as + paid. + type: string + enum: + - open + - completed + email: + description: The email of the customer of the draft order + type: string + format: email + billing_address: + description: The Address to be used for billing purposes. + anyOf: + - $ref: '#/components/schemas/AddressPayload' + - type: string + shipping_address: + description: The Address to be used for shipping purposes. + anyOf: + - $ref: '#/components/schemas/AddressPayload' + - type: string + items: + description: The draft order's line items. + type: array + items: + type: object + required: + - quantity + properties: + variant_id: + description: >- + The ID of the Product Variant associated with the line item. + If the line item is custom, the `variant_id` should be + omitted. + type: string + unit_price: + description: >- + The custom price of the line item. If a `variant_id` is + supplied, the price provided here will override the variant's + price. + type: integer + title: + description: The title of the line item if `variant_id` is not provided. + type: string + quantity: + description: The quantity of the line item. + type: integer + metadata: + description: >- + The optional key-value map with additional details about the + line item. + 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 + region_id: + description: The ID of the region for the draft order + type: string + discounts: + description: The discounts to add to the draft order + type: array + items: + type: object + required: + - code + properties: + code: + description: The code of the discount to apply + type: string + customer_id: + description: The ID of the customer this draft order is associated with. + type: string + no_notification_order: + description: >- + An optional flag passed to the resulting order that indicates + whether the customer should receive notifications about order + updates. + type: boolean + shipping_methods: + description: The shipping methods for the draft order + type: array + items: + type: object + required: + - option_id + properties: + option_id: + description: The ID of the shipping option in use + type: string + data: + description: The optional additional data needed for the shipping method + type: object + price: + description: The price of the shipping method. + type: integer + metadata: + description: >- + The optional key-value map with additional details about the Draft + Order. + 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 + AdminPostGiftCardsGiftCardReq: + type: object + properties: + balance: + type: integer + description: The value (excluding VAT) that the Gift Card should represent. + is_disabled: + type: boolean + description: >- + Whether the Gift Card is disabled on creation. If set to `true`, the + gift card will not be available for customers. + ends_at: + type: string + format: date-time + description: >- + The date and time at which the Gift Card should no longer be + available. + region_id: + description: The ID of the Region in which the Gift Card can be used. + type: string + metadata: + description: An optional set of key-value pairs to hold additional information. + 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 + AdminPostGiftCardsReq: + type: object + required: + - region_id + properties: + value: + type: integer + description: The value (excluding VAT) that the Gift Card should represent. + is_disabled: + type: boolean + description: >- + Whether the Gift Card is disabled on creation. If set to `true`, the + gift card will not be available for customers. + ends_at: + type: string + format: date-time + description: >- + The date and time at which the Gift Card should no longer be + available. + region_id: + description: The ID of the Region in which the Gift Card can be used. + type: string + metadata: + description: An optional set of key-value pairs to hold additional information. + 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 + AdminPostInventoryItemsInventoryItemReq: + type: object + properties: + 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 + 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 + AdminPostInventoryItemsItemLocationLevelsLevelReq: + type: object + properties: + stocked_quantity: + description: >- + the total 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 + AdminPostInventoryItemsItemLocationLevelsReq: + type: object + required: + - location_id + - stocked_quantity + properties: + location_id: + description: the ID of the stock location + type: string + stocked_quantity: + description: the stock quantity of the inventory item at this location + type: number + incoming_quantity: + description: the incoming stock quantity of the inventory item at this location + type: number + AdminPostInventoryItemsReq: + type: object + required: + - variant_id + properties: + variant_id: + description: The ID of the variant to create the inventory item for. + type: string + sku: + description: The unique SKU of the associated Product Variant. + type: string + ean: + description: The EAN number of the item. + type: string + upc: + description: The UPC number of the item. + type: string + barcode: + description: A generic GTIN field for the Product Variant. + 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 + inventory_quantity: + description: The amount of stock kept of the associated Product Variant. + type: integer + default: 0 + allow_backorder: + description: >- + Whether the associated Product Variant can be purchased when out of + stock. + type: boolean + manage_inventory: + description: >- + Whether Medusa should keep track of the inventory for the associated + Product Variant. + type: boolean + default: true + weight: + description: >- + The weight 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 + 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 + 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 + 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 + metadata: + description: An optional set of key-value pairs with additional information. + 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 + AdminPostInvitesInviteAcceptReq: + type: object + required: + - token + - user + properties: + token: + description: >- + The token of the invite to accept. This is a unique token generated + when the invite was created or resent. + type: string + user: + description: The details of the user to create. + type: object + required: + - first_name + - last_name + - password + properties: + first_name: + type: string + description: the first name of the User + last_name: + type: string + description: the last name of the User + password: + description: The password for the User + type: string + format: password + AdminPostInvitesReq: + type: object + required: + - user + - role + properties: + user: + description: >- + The email associated with the invite. Once the invite is accepted, + the email will be associated with the created user. + type: string + format: email + role: + description: >- + The role of the user to be created. This does not actually change + the privileges of the user that is eventually created. + type: string + enum: + - admin + - member + - developer + AdminPostNotesNoteReq: + type: object + required: + - value + properties: + value: + type: string + description: The description of the Note. + AdminPostNotesReq: + type: object + required: + - resource_id + - resource_type + - value + properties: + resource_id: + type: string + description: >- + The ID of the resource which the Note relates to. For example, an + order ID. + resource_type: + type: string + description: >- + The type of resource which the Note relates to. For example, + `order`. + value: + type: string + description: The content of the Note to create. + AdminPostNotificationsNotificationResendReq: + type: object + properties: + to: + description: >- + A new address or user identifier that the Notification should be + sent to. If not provided, the previous `to` field of the + notification will be used. + type: string + AdminPostOrderEditsEditLineItemsLineItemReq: + type: object + required: + - quantity + properties: + quantity: + description: The quantity to update + type: number + AdminPostOrderEditsEditLineItemsReq: + type: object + required: + - variant_id + - quantity + properties: + variant_id: + description: The ID of the product variant associated with the item. + type: string + quantity: + description: The quantity of the item. + type: number + metadata: + description: An optional set of key-value pairs to hold additional information. + 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 + AdminPostOrderEditsOrderEditReq: + type: object + properties: + internal_note: + description: An optional note to create or update in the order edit. + type: string + AdminPostOrderEditsReq: + type: object + required: + - order_id + properties: + order_id: + description: The ID of the order to create the edit for. + type: string + internal_note: + description: An optional note to associate with the order edit. + type: string + AdminPostOrdersOrderClaimsClaimFulfillmentsReq: + type: object + properties: + metadata: + description: An optional set of key-value pairs to hold additional information. + 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 + no_notification: + description: >- + If set to `true`, no notification will be sent to the customer + related to this Claim. + type: boolean + AdminPostOrdersOrderClaimsClaimReq: + type: object + properties: + claim_items: + description: The Claim Items that the Claim will consist of. + type: array + items: + type: object + required: + - id + - images + - tags + properties: + id: + description: The ID of the Claim Item. + type: string + item_id: + description: The ID of the Line Item that will be claimed. + type: string + quantity: + description: The number of items that will be returned + type: integer + note: + description: Short text describing the Claim Item in further detail. + type: string + reason: + description: The reason for the Claim + type: string + enum: + - missing_item + - wrong_item + - production_failure + - other + tags: + description: A list o tags to add to the Claim Item + type: array + items: + type: object + properties: + id: + type: string + description: Tag ID + value: + type: string + description: Tag value + images: + description: A list of image URL's that will be associated with the Claim + type: array + items: + type: object + properties: + id: + type: string + description: Image ID + url: + type: string + description: Image URL + metadata: + description: >- + An optional set of key-value pairs to hold additional + information. + 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 + shipping_methods: + description: The Shipping Methods to send the additional Line Items with. + type: array + items: + type: object + properties: + id: + description: The ID of an existing Shipping Method + type: string + option_id: + description: The ID of the Shipping Option to create a Shipping Method from + type: string + price: + description: The price to charge for the Shipping Method + type: integer + data: + description: >- + An optional set of key-value pairs to hold additional + information. + type: object + no_notification: + description: If set to true no notification will be send related to this Swap. + type: boolean + metadata: + description: An optional set of key-value pairs to hold additional information. + 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 + AdminPostOrdersOrderClaimsClaimShipmentsReq: + type: object + required: + - fulfillment_id + properties: + fulfillment_id: + description: The ID of the Fulfillment. + type: string + tracking_numbers: + description: An array of tracking numbers for the shipment. + type: array + items: + type: string + AdminPostOrdersOrderClaimsReq: + type: object + required: + - type + - claim_items + properties: + type: + description: >- + The type of the Claim. This will determine how the Claim is treated: + `replace` Claims will result in a Fulfillment with new items being + created, while a `refund` Claim will refund the amount paid for the + claimed items. + type: string + enum: + - replace + - refund + claim_items: + description: The Claim Items that the Claim will consist of. + type: array + items: + type: object + required: + - item_id + - quantity + properties: + item_id: + description: The ID of the Line Item that will be claimed. + type: string + quantity: + description: The number of items that will be returned + type: integer + note: + description: Short text describing the Claim Item in further detail. + type: string + reason: + description: The reason for the Claim + type: string + enum: + - missing_item + - wrong_item + - production_failure + - other + tags: + description: A list of tags to add to the Claim Item + type: array + items: + type: string + images: + description: A list of image URL's that will be associated with the Claim + items: + type: string + return_shipping: + description: >- + Optional details for the Return Shipping Method, if the items are to + be sent back. Providing this field will result in a return being + created and associated with the claim. + type: object + properties: + option_id: + type: string + description: >- + The ID of the Shipping Option to create the Shipping Method + from. + price: + type: integer + description: The price to charge for the Shipping Method. + additional_items: + description: >- + The new items to send to the Customer. This is only used if the + claim's type is `replace`. + 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 Product Variant. + type: integer + shipping_methods: + description: >- + The Shipping Methods to send the additional Line Items with. This is + only used if the claim's type is `replace`. + type: array + items: + type: object + properties: + id: + description: The ID of an existing Shipping Method + type: string + option_id: + description: The ID of the Shipping Option to create a Shipping Method from + type: string + price: + description: The price to charge for the Shipping Method + type: integer + data: + description: >- + An optional set of key-value pairs to hold additional + information. + type: object + shipping_address: + description: >- + An optional shipping address to send the claimed items to. If not + provided, the parent order's shipping address will be used. + $ref: '#/components/schemas/AddressPayload' + refund_amount: + description: >- + The amount to refund the customer. This is used when the claim's + type is `refund`. + type: integer + no_notification: + description: If set to true no notification will be send related to this Claim. + type: boolean + metadata: + description: An optional set of key-value pairs to hold additional information. + 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 + AdminPostOrdersOrderFulfillmentsReq: + type: object + required: + - items + properties: + items: + description: The Line Items to include in the Fulfillment. + type: array + items: + type: object + required: + - item_id + - quantity + properties: + item_id: + description: The ID of the Line Item to fulfill. + type: string + quantity: + description: The quantity of the Line Item to fulfill. + type: integer + no_notification: + description: >- + If set to `true`, no notification will be sent to the customer + related to this fulfillment. + type: boolean + metadata: + description: An optional set of key-value pairs to hold additional information. + 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 + AdminPostOrdersOrderRefundsReq: + type: object + required: + - amount + - reason + properties: + amount: + description: >- + The amount to refund. It should be less than or equal the + `refundable_amount` of the order. + type: integer + reason: + description: The reason for the Refund. + type: string + note: + description: A note with additional details about the Refund. + type: string + no_notification: + description: >- + If set to `true`, no notification will be sent to the customer + related to this Refund. + type: boolean + AdminPostOrdersOrderReq: + type: object + properties: + email: + description: the email associated with the order + type: string + billing_address: + description: The order's billing address + $ref: '#/components/schemas/AddressPayload' + shipping_address: + description: The order's shipping address + $ref: '#/components/schemas/AddressPayload' + items: + description: The line items of the order + type: array + items: + $ref: '#/components/schemas/LineItem' + region: + description: ID of the region that the order is associated with. + type: string + discounts: + description: The discounts applied to the order + type: array + items: + $ref: '#/components/schemas/Discount' + customer_id: + description: The ID of the customer associated with the order. + type: string + payment_method: + description: The payment method chosen for the order. + type: object + properties: + provider_id: + type: string + description: The ID of the payment provider. + data: + description: Any data relevant for the given payment method. + type: object + shipping_method: + description: The Shipping Method used for shipping the order. + type: object + properties: + provider_id: + type: string + description: The ID of the shipping provider. + profile_id: + type: string + description: The ID of the shipping profile. + price: + type: integer + description: The price of the shipping. + data: + type: object + description: Any data relevant to the specific shipping method. + items: + type: array + items: + $ref: '#/components/schemas/LineItem' + description: Items to ship + no_notification: + description: >- + If set to `true`, no notification will be sent to the customer + related to this order. + type: boolean + AdminPostOrdersOrderReturnsReq: + type: object + required: + - items + properties: + items: + description: The line items that will be returned. + type: array + items: + type: object + required: + - item_id + - quantity + properties: + item_id: + description: The ID of the Line Item. + type: string + reason_id: + description: The ID of the Return Reason to use. + type: string + note: + description: An optional note with information about the Return. + type: string + quantity: + description: The quantity of the Line Item. + type: integer + return_shipping: + description: The Shipping Method to be used to handle the return shipment. + type: object + properties: + option_id: + type: string + description: >- + The ID of the Shipping Option to create the Shipping Method + from. + price: + type: integer + description: The price to charge for the Shipping Method. + note: + description: An optional note with information about the Return. + type: string + receive_now: + description: >- + A flag to indicate if the Return should be registerd as received + immediately. + type: boolean + default: false + no_notification: + description: >- + If set to `true`, no notification will be sent to the customer + related to this Return. + type: boolean + refund: + description: The amount to refund. + type: integer + AdminPostOrdersOrderShipmentReq: + type: object + required: + - fulfillment_id + properties: + fulfillment_id: + description: The ID of the Fulfillment. + type: string + tracking_numbers: + description: The tracking numbers for the shipment. + type: array + items: + type: string + no_notification: + description: >- + If set to true no notification will be send related to this + Shipment. + type: boolean + AdminPostOrdersOrderShippingMethodsReq: + type: object + required: + - price + - option_id + properties: + price: + type: number + description: >- + The price (excluding VAT) that should be charged for the Shipping + Method + option_id: + type: string + description: The ID of the Shipping Option to create the Shipping Method from. + date: + type: object + description: >- + The data required for the Shipping Option to create a Shipping + Method. This depends on the Fulfillment Provider. + AdminPostOrdersOrderSwapsReq: + type: object + required: + - return_items + properties: + return_items: + description: The Line Items to associate with the swap's return. + type: array + items: + type: object + required: + - item_id + - quantity + properties: + item_id: + description: The ID of the Line Item that will be returned. + type: string + quantity: + description: The number of items that will be returned + type: integer + reason_id: + description: The ID of the Return Reason to use. + type: string + note: + description: An optional note with information about the Return. + type: string + return_shipping: + description: The shipping method associated with the swap's return. + type: object + required: + - option_id + properties: + option_id: + type: string + description: >- + The ID of the Shipping Option to create the Shipping Method + from. + price: + type: integer + description: The price to charge for the Shipping Method. + additional_items: + description: The new items to send to the Customer. + 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 Product Variant. + type: integer + custom_shipping_options: + description: >- + An array of custom shipping options to potentially create a Shipping + Method from to send the additional items. + type: array + items: + type: object + required: + - option_id + - price + properties: + option_id: + description: The ID of the Shipping Option. + type: string + price: + description: The custom price of the Shipping Option. + type: integer + no_notification: + description: >- + If set to `true`, no notification will be sent to the customer + related to this Swap. + type: boolean + allow_backorder: + description: If set to `true`, swaps can be completed with items out of stock + type: boolean + default: true + AdminPostOrdersOrderSwapsSwapFulfillmentsReq: + type: object + properties: + metadata: + description: An optional set of key-value pairs to hold additional information. + 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 + no_notification: + description: >- + If set to `true`, no notification will be sent to the customer + related to this swap. + type: boolean + AdminPostOrdersOrderSwapsSwapShipmentsReq: + type: object + required: + - fulfillment_id + properties: + fulfillment_id: + description: The ID of the Fulfillment. + type: string + tracking_numbers: + description: The tracking numbers for the shipment. + type: array + items: + type: string + no_notification: + description: If set to true no notification will be sent related to this Claim. + type: boolean + AdminPostPaymentRefundsReq: + type: object + required: + - amount + - reason + properties: + amount: + description: The amount to refund. + type: integer + reason: + description: The reason for the Refund. + type: string + note: + description: A note with additional details about the Refund. + type: string + AdminPostPriceListPricesPricesReq: + type: object + properties: + prices: + description: The prices to update or add. + type: array + items: + type: object + required: + - amount + - variant_id + properties: + id: + description: The ID of the price. + type: string + region_id: + description: >- + The ID of the Region for which the price is used. This is only + required if `currecny_code` is not provided. + type: string + currency_code: + description: >- + The 3 character ISO currency code for which the price will be + used. This is only required if `region_id` is not provided. + type: string + externalDocs: + url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes + description: See a list of codes. + variant_id: + description: The ID of the Variant for which the price is used. + type: string + amount: + description: The amount to charge for the Product Variant. + type: integer + min_quantity: + description: The minimum quantity for which the price will be used. + type: integer + max_quantity: + description: The maximum quantity for which the price will be used. + type: integer + override: + description: >- + If set to `true`, the prices will replace all existing prices + associated with the Price List. + type: boolean + AdminPostPriceListsPriceListPriceListReq: + type: object + properties: + name: + description: The name of the Price List + type: string + description: + description: The description of the Price List. + type: string + starts_at: + description: The date with timezone that the Price List starts being valid. + type: string + format: date + ends_at: + description: The date with timezone that the Price List ends being valid. + type: string + format: date + type: + description: The type of the Price List. + type: string + enum: + - sale + - override + status: + description: >- + The status of the Price List. If the status is set to `draft`, the + prices created in the price list will not be available of the + customer. + type: string + enum: + - active + - draft + prices: + description: The prices of the Price List. + type: array + items: + type: object + required: + - amount + - variant_id + properties: + id: + description: The ID of the price. + type: string + region_id: + description: >- + The ID of the Region for which the price is used. This is only + required if `currecny_code` is not provided. + type: string + currency_code: + description: >- + The 3 character ISO currency code for which the price will be + used. This is only required if `region_id` is not provided. + type: string + externalDocs: + url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes + description: See a list of codes. + variant_id: + description: The ID of the Variant for which the price is used. + type: string + amount: + description: The amount to charge for the Product Variant. + type: integer + min_quantity: + description: The minimum quantity for which the price will be used. + type: integer + max_quantity: + description: The maximum quantity for which the price will be used. + type: integer + customer_groups: + type: array + description: An array of customer groups that the Price List applies to. + items: + type: object + required: + - id + properties: + id: + description: The ID of a customer group + type: string + includes_tax: + description: Tax included in prices of price list + x-featureFlag: tax_inclusive_pricing + type: boolean + AdminPostPriceListsPriceListReq: + type: object + required: + - name + - description + - type + - prices + properties: + name: + description: The name of the Price List. + type: string + description: + description: The description of the Price List. + type: string + starts_at: + description: The date with timezone that the Price List starts being valid. + type: string + format: date + ends_at: + description: The date with timezone that the Price List ends being valid. + type: string + format: date + type: + description: The type of the Price List. + type: string + enum: + - sale + - override + status: + description: >- + The status of the Price List. If the status is set to `draft`, the + prices created in the price list will not be available of the + customer. + type: string + enum: + - active + - draft + prices: + description: The prices of the Price List. + type: array + items: + type: object + required: + - amount + - variant_id + properties: + region_id: + description: >- + The ID of the Region for which the price is used. This is only + required if `currecny_code` is not provided. + type: string + currency_code: + description: >- + The 3 character ISO currency code for which the price will be + used. This is only required if `region_id` is not provided. + type: string + externalDocs: + url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes + description: See a list of codes. + amount: + description: The amount to charge for the Product Variant. + type: integer + variant_id: + description: The ID of the Variant for which the price is used. + type: string + min_quantity: + description: The minimum quantity for which the price will be used. + type: integer + max_quantity: + description: The maximum quantity for which the price will be used. + type: integer + customer_groups: + type: array + description: An array of customer groups that the Price List applies to. + items: + type: object + required: + - id + properties: + id: + description: The ID of a customer group + type: string + includes_tax: + description: Tax included in prices of price list + x-featureFlag: tax_inclusive_pricing + type: boolean + AdminPostProductCategoriesCategoryProductsBatchReq: + type: object + required: + - product_ids + properties: + product_ids: + description: The IDs of the products to add to the Product Category + type: array + items: + type: object + required: + - id + properties: + id: + type: string + description: The ID of the product + AdminPostProductCategoriesCategoryReq: + type: object + properties: + name: + type: string + description: The name to identify the Product Category by. + description: + type: string + description: An optional text field to describe the Product Category by. + handle: + type: string + description: A handle to be used in slugs. + is_internal: + type: boolean + description: A flag to make product category an internal category for admins + is_active: + type: boolean + description: A flag to make product category visible/hidden in the store front + parent_category_id: + type: string + description: The ID of the parent product category + rank: + type: number + description: The rank of the category in the tree node (starting from 0) + AdminPostProductCategoriesReq: + type: object + required: + - name + properties: + name: + type: string + description: The name of the product category + description: + type: string + description: The description of the product category. + handle: + type: string + description: >- + The handle of the product category. If none is provided, the + kebab-case version of the name will be used. This field can be used + as a slug in URLs. + is_internal: + type: boolean + description: >- + If set to `true`, the product category will only be available to + admins. + is_active: + type: boolean + description: >- + If set to `false`, the product category will not be available in the + storefront. + parent_category_id: + type: string + description: The ID of the parent product category + AdminPostProductsProductMetadataReq: + type: object + required: + - key + - value + properties: + key: + description: The metadata key + type: string + value: + description: The metadata value + type: string + AdminPostProductsProductOptionsOption: + type: object + required: + - title + properties: + title: + description: The title of the Product Option + type: string + AdminPostProductsProductOptionsReq: + type: object + required: + - title + properties: + title: + description: The title the Product Option. + type: string + example: Size + AdminPostProductsProductReq: + type: object + properties: + title: + description: The title of the Product + type: string + subtitle: + description: The subtitle of the Product + type: string + description: + description: The description of the Product. + type: string + discountable: + description: >- + A flag to indicate if discounts can be applied to the Line Items + generated from this Product + type: boolean + images: + description: >- + An array of images of the Product. Each value in the array is a URL + to the image. You can use the upload API Routes to upload the image + and obtain a URL. + type: array + items: + type: string + thumbnail: + description: >- + The thumbnail to use for the Product. The value is a URL to the + thumbnail. You can use the upload API Routes to upload the thumbnail + and obtain a URL. + type: string + handle: + description: >- + A unique handle to identify the Product by. If not provided, the + kebab-case version of the product title will be used. This can be + used as a slug in URLs. + type: string + status: + description: >- + The status of the product. The product is shown to the customer only + if its status is `published`. + type: string + enum: + - draft + - proposed + - published + - rejected + type: + description: The Product Type to associate the Product with. + type: object + required: + - value + properties: + id: + description: >- + The ID of an existing Product Type. If not provided, a new + product type will be created. + type: string + value: + description: The value of the Product Type. + type: string + collection_id: + description: The ID of the Product Collection the Product belongs to. + type: string + tags: + description: Product Tags to associate the Product with. + type: array + items: + type: object + required: + - value + properties: + id: + description: >- + The ID of an existing Product Tag. If not provided, a new + product tag will be created. + type: string + value: + description: >- + The value of the Tag. If the `id` is provided, the value of + the existing tag will be updated. + type: string + sales_channels: + description: Sales channels to associate the Product with. + type: array + items: + type: object + required: + - id + properties: + id: + description: The ID of an existing Sales channel. + type: string + categories: + description: Product categories to add the Product to. + x-featureFlag: product_categories + type: array + items: + required: + - id + properties: + id: + description: The ID of a Product Category. + type: string + variants: + description: >- + An array of Product Variants to create with the Product. Each + product variant must have a unique combination of Product Option + values. + type: array + items: + type: object + properties: + id: + description: >- + The id of an existing product variant. If provided, the + details of the product variant will be updated. If not, a new + product variant will be created. + type: string + title: + description: The title of the product variant. + type: string + sku: + description: The unique SKU of the product variant. + type: string + ean: + description: The EAN number of the product variant. + type: string + upc: + description: The UPC number of the product variant. + type: string + barcode: + description: A generic GTIN field of the product variant. + type: string + hs_code: + description: The Harmonized System code of the product variant. + type: string + inventory_quantity: + description: The amount of stock kept of the product variant. + type: integer + allow_backorder: + description: >- + Whether the product variant can be purchased when out of + stock. + type: boolean + manage_inventory: + description: >- + Whether Medusa should keep track of the inventory of this + product variant. + type: boolean + weight: + description: The weight of the product variant. + type: number + length: + description: The length of the product variant. + type: number + height: + description: The height of the product variant. + type: number + width: + description: The width of the product variant. + type: number + origin_country: + description: The country of origin of the product variant. + type: string + mid_code: + description: The Manufacturer Identification code of the product variant. + type: string + material: + description: The material composition of the product variant. + type: string + metadata: + description: >- + An optional set of key-value pairs with additional + information. + 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 + prices: + type: array + description: >- + An array of product variant prices. A product variant can have + different prices for each region or currency code. + externalDocs: + url: >- + https://docs.medusajs.com/modules/products/admin/manage-products#product-variant-prices + description: Product variant pricing. + items: + type: object + required: + - amount + properties: + id: + description: >- + The ID of the Price. If provided, the existing price + will be updated. Otherwise, a new price will be created. + type: string + region_id: + description: >- + The ID of the Region the price will be used in. This is + only required if `currency_code` is not provided. + type: string + currency_code: + description: >- + The 3 character ISO currency code the price will be used + in. This is only required if `region_id` is not + provided. + type: string + externalDocs: + url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes + description: See a list of codes. + amount: + description: The price amount. + type: integer + min_quantity: + description: >- + The minimum quantity required to be added to the cart + for the price to be used. + type: integer + max_quantity: + description: >- + The maximum quantity required to be added to the cart + for the price to be used. + type: integer + options: + type: array + description: >- + An array of Product Option values that the variant corresponds + to. + items: + type: object + required: + - option_id + - value + properties: + option_id: + description: The ID of the Option. + type: string + value: + description: The value of the Product Option. + type: string + weight: + description: The weight of the Product. + type: number + length: + description: The length of the Product. + type: number + height: + description: The height of the Product. + type: number + width: + description: The width of the Product. + type: number + origin_country: + description: The country of origin of the Product. + type: string + mid_code: + description: The Manufacturer Identification code of the Product. + type: string + material: + description: The material composition of the Product. + type: string + metadata: + description: An optional set of key-value pairs with additional information. + 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 + AdminPostProductsProductVariantsReq: + type: object + required: + - title + - prices + - options + properties: + title: + description: The title of the product variant. + type: string + sku: + description: The unique SKU of the product variant. + type: string + ean: + description: The EAN number of the product variant. + type: string + upc: + description: The UPC number of the product variant. + type: string + barcode: + description: A generic GTIN field of the product variant. + type: string + hs_code: + description: The Harmonized System code of the product variant. + type: string + inventory_quantity: + description: The amount of stock kept of the product variant. + type: integer + default: 0 + allow_backorder: + description: Whether the product variant can be purchased when out of stock. + type: boolean + manage_inventory: + description: >- + Whether Medusa should keep track of the inventory of this product + variant. + type: boolean + default: true + weight: + description: The wieght of the product variant. + type: number + length: + description: The length of the product variant. + type: number + height: + description: The height of the product variant. + type: number + width: + description: The width of the product variant. + type: number + origin_country: + description: The country of origin of the product variant. + type: string + mid_code: + description: The Manufacturer Identification code of the product variant. + type: string + material: + description: The material composition of the product variant. + type: string + metadata: + description: An optional set of key-value pairs with additional information. + 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 + prices: + type: array + description: >- + An array of product variant prices. A product variant can have + different prices for each region or currency code. + externalDocs: + url: >- + https://docs.medusajs.com/modules/products/admin/manage-products#product-variant-prices + description: Product variant pricing. + items: + type: object + required: + - amount + properties: + region_id: + description: >- + The ID of the Region the price will be used in. This is only + required if `currency_code` is not provided. + type: string + currency_code: + description: >- + The 3 character ISO currency code the price will be used in. + This is only required if `region_id` is not provided. + type: string + externalDocs: + url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes + description: See a list of codes. + amount: + description: The price amount. + type: integer + min_quantity: + description: >- + The minimum quantity required to be added to the cart for the + price to be used. + type: integer + max_quantity: + description: >- + The maximum quantity required to be added to the cart for the + price to be used. + type: integer + options: + type: array + description: An array of Product Option values that the variant corresponds to. + items: + type: object + required: + - option_id + - value + properties: + option_id: + description: The ID of the Product Option. + type: string + value: + description: A value to give to the Product Option. + type: string + AdminPostProductsProductVariantsVariantReq: + type: object + properties: + title: + description: The title of the product variant. + type: string + sku: + description: The unique SKU of the product variant. + type: string + ean: + description: The EAN number of the item. + type: string + upc: + description: The UPC number of the item. + type: string + barcode: + description: A generic GTIN field of the product variant. + type: string + hs_code: + description: The Harmonized System code of the product variant. + type: string + inventory_quantity: + description: The amount of stock kept of the product variant. + type: integer + allow_backorder: + description: Whether the product variant can be purchased when out of stock. + type: boolean + manage_inventory: + description: >- + Whether Medusa should keep track of the inventory of this product + variant. + type: boolean + weight: + description: The weight of the product variant. + type: number + length: + description: The length of the product variant. + type: number + height: + description: The height of the product variant. + type: number + width: + description: The width of the product variant. + type: number + origin_country: + description: The country of origin of the product variant. + type: string + mid_code: + description: The Manufacturer Identification code of the product variant. + type: string + material: + description: The material composition of the product variant. + type: string + metadata: + description: An optional set of key-value pairs with additional information. + 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 + prices: + type: array + description: >- + An array of product variant prices. A product variant can have + different prices for each region or currency code. + externalDocs: + url: >- + https://docs.medusajs.com/modules/products/admin/manage-products#product-variant-prices + description: Product variant pricing. + items: + type: object + required: + - amount + properties: + id: + description: >- + The ID of the price. If provided, the existing price will be + updated. Otherwise, a new price will be created. + type: string + region_id: + description: >- + The ID of the Region the price will be used in. This is only + required if `currency_code` is not provided. + type: string + currency_code: + description: >- + The 3 character ISO currency code the price will be used in. + This is only required if `region_id` is not provided. + type: string + externalDocs: + url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes + description: See a list of codes. + amount: + description: The price amount. + type: integer + min_quantity: + description: >- + The minimum quantity required to be added to the cart for the + price to be used. + type: integer + max_quantity: + description: >- + The maximum quantity required to be added to the cart for the + price to be used. + type: integer + options: + type: array + description: An array of Product Option values that the variant corresponds to. + items: + type: object + required: + - option_id + - value + properties: + option_id: + description: The ID of the Product Option. + type: string + value: + description: The value of the Product Option. + type: string + AdminPostProductsReq: + type: object + required: + - title + properties: + title: + description: The title of the Product + type: string + subtitle: + description: The subtitle of the Product + type: string + description: + description: The description of the Product. + type: string + is_giftcard: + description: >- + A flag to indicate if the Product represents a Gift Card. Purchasing + Products with this flag set to `true` will result in a Gift Card + being created. + type: boolean + default: false + discountable: + description: >- + A flag to indicate if discounts can be applied to the Line Items + generated from this Product + type: boolean + default: true + images: + description: >- + An array of images of the Product. Each value in the array is a URL + to the image. You can use the upload API Routes to upload the image + and obtain a URL. + type: array + items: + type: string + thumbnail: + description: >- + The thumbnail to use for the Product. The value is a URL to the + thumbnail. You can use the upload API Routes to upload the thumbnail + and obtain a URL. + type: string + handle: + description: >- + A unique handle to identify the Product by. If not provided, the + kebab-case version of the product title will be used. This can be + used as a slug in URLs. + type: string + status: + description: >- + The status of the product. The product is shown to the customer only + if its status is `published`. + type: string + enum: + - draft + - proposed + - published + - rejected + default: draft + type: + description: The Product Type to associate the Product with. + type: object + required: + - value + properties: + id: + description: >- + The ID of an existing Product Type. If not provided, a new + product type will be created. + type: string + value: + description: The value of the Product Type. + type: string + collection_id: + description: The ID of the Product Collection the Product belongs to. + type: string + tags: + description: Product Tags to associate the Product with. + type: array + items: + type: object + required: + - value + properties: + id: + description: >- + The ID of an existing Product Tag. If not provided, a new + product tag will be created. + type: string + value: + description: >- + The value of the Tag. If the `id` is provided, the value of + the existing tag will be updated. + type: string + sales_channels: + description: Sales channels to associate the Product with. + type: array + items: + type: object + required: + - id + properties: + id: + description: The ID of an existing Sales channel. + type: string + categories: + description: Product categories to add the Product to. + x-featureFlag: product_categories + type: array + items: + type: object + required: + - id + properties: + id: + description: The ID of a Product Category. + type: string + options: + description: >- + The Options that the Product should have. A new product option will + be created for every item in the array. + type: array + items: + type: object + required: + - title + properties: + title: + description: The title of the Product Option. + type: string + variants: + description: >- + An array of Product Variants to create with the Product. Each + product variant must have a unique combination of Product Option + values. + type: array + items: + type: object + required: + - title + properties: + title: + description: The title of the Product Variant. + type: string + sku: + description: The unique SKU of the Product Variant. + type: string + ean: + description: The EAN number of the item. + type: string + upc: + description: The UPC number of the item. + type: string + barcode: + description: A generic GTIN field of the Product Variant. + type: string + hs_code: + description: The Harmonized System code of the Product Variant. + type: string + inventory_quantity: + description: The amount of stock kept of the Product Variant. + type: integer + default: 0 + allow_backorder: + description: >- + Whether the Product Variant can be purchased when out of + stock. + type: boolean + manage_inventory: + description: >- + Whether Medusa should keep track of the inventory of this + Product Variant. + type: boolean + weight: + description: The wieght of the Product Variant. + type: number + length: + description: The length of the Product Variant. + type: number + height: + description: The height of the Product Variant. + type: number + width: + description: The width of the Product Variant. + type: number + origin_country: + description: The country of origin of the Product Variant. + type: string + mid_code: + description: The Manufacturer Identification code of the Product Variant. + type: string + material: + description: The material composition of the Product Variant. + type: string + metadata: + description: >- + An optional set of key-value pairs with additional + information. + 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 + prices: + type: array + description: >- + An array of product variant prices. A product variant can have + different prices for each region or currency code. + externalDocs: + url: >- + https://docs.medusajs.com/modules/products/admin/manage-products#product-variant-prices + description: Product variant pricing. + items: + type: object + required: + - amount + properties: + region_id: + description: >- + The ID of the Region the price will be used in. This is + only required if `currency_code` is not provided. + type: string + currency_code: + description: >- + The 3 character ISO currency code the price will be used + in. This is only required if `region_id` is not + provided. + type: string + externalDocs: + url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes + description: See a list of codes. + amount: + description: The price amount. + type: integer + min_quantity: + description: >- + The minimum quantity required to be added to the cart + for the price to be used. + type: integer + max_quantity: + description: >- + The maximum quantity required to be added to the cart + for the price to be used. + type: integer + options: + type: array + description: >- + An array of Product Option values that the variant corresponds + to. The option values should be added into the array in the + same index as in the `options` field of the product. + externalDocs: + url: >- + https://docs.medusajs.com/modules/products/admin/manage-products#create-a-product + description: Example of how to create a product with options and variants + items: + type: object + required: + - value + properties: + value: + description: >- + The value to give for the Product Option at the same + index in the Product's `options` field. + type: string + weight: + description: The weight of the Product. + type: number + length: + description: The length of the Product. + type: number + height: + description: The height of the Product. + type: number + width: + description: The width of the Product. + type: number + hs_code: + description: The Harmonized System code of the Product. + type: string + origin_country: + description: The country of origin of the Product. + type: string + mid_code: + description: The Manufacturer Identification code of the Product. + type: string + material: + description: The material composition of the Product. + type: string + metadata: + description: An optional set of key-value pairs with additional information. + 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 + AdminPostProductsToCollectionReq: + type: object + required: + - product_ids + properties: + product_ids: + description: An array of Product IDs to add to the Product Collection. + type: array + items: + description: The ID of a Product to add to the Product Collection. + type: string + AdminPostPublishableApiKeySalesChannelsBatchReq: + type: object + required: + - sales_channel_ids + properties: + sales_channel_ids: + description: The IDs of the sales channels to add to the publishable API key + type: array + items: + type: object + required: + - id + properties: + id: + type: string + description: The ID of the sales channel + AdminPostPublishableApiKeysPublishableApiKeyReq: + type: object + properties: + title: + description: The title of the Publishable API Key. + type: string + AdminPostPublishableApiKeysReq: + type: object + required: + - title + properties: + title: + description: The title of the publishable API key + type: string + AdminPostRegionsRegionCountriesReq: + type: object + required: + - country_code + properties: + country_code: + description: The 2 character ISO code for the Country. + type: string + externalDocs: + url: >- + https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements + description: See a list of codes. + AdminPostRegionsRegionFulfillmentProvidersReq: + type: object + required: + - provider_id + properties: + provider_id: + description: The ID of the Fulfillment Provider. + type: string + AdminPostRegionsRegionPaymentProvidersReq: + type: object + required: + - provider_id + properties: + provider_id: + description: The ID of the Payment Provider. + type: string + AdminPostRegionsRegionReq: + type: object + properties: + name: + description: The name of the Region + type: string + currency_code: + description: The 3 character ISO currency code to use in the Region. + type: string + externalDocs: + url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes + description: See a list of codes. + automatic_taxes: + description: >- + If set to `true`, the Medusa backend will automatically calculate + taxes for carts in this region. If set to `false`, the taxes must be + calculated manually. + externalDocs: + url: >- + https://docs.medusajs.com/modules/taxes/storefront/manual-calculation + description: How to calculate taxes in a storefront. + type: boolean + gift_cards_taxable: + description: If set to `true`, taxes will be applied on gift cards. + type: boolean + tax_provider_id: + description: >- + The ID of the tax provider to use. If none provided, the system tax + provider is used. + type: string + tax_code: + description: The tax code of the Region. + type: string + tax_rate: + description: The tax rate to use in the Region. + type: number + includes_tax: + x-featureFlag: tax_inclusive_pricing + description: Whether taxes are included in the prices of the region. + type: boolean + payment_providers: + description: A list of Payment Provider IDs that can be used in the Region + type: array + items: + type: string + fulfillment_providers: + description: A list of Fulfillment Provider IDs that can be used in the Region + type: array + items: + type: string + countries: + description: >- + A list of countries' 2 ISO characters that should be included in the + Region. + type: array + items: + type: string + AdminPostRegionsReq: + type: object + required: + - name + - currency_code + - tax_rate + - payment_providers + - fulfillment_providers + - countries + properties: + name: + description: The name of the Region + type: string + currency_code: + description: The 3 character ISO currency code to use in the Region. + type: string + externalDocs: + url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes + description: See a list of codes. + tax_code: + description: The tax code of the Region. + type: string + tax_rate: + description: The tax rate to use in the Region. + type: number + payment_providers: + description: A list of Payment Provider IDs that can be used in the Region + type: array + items: + type: string + fulfillment_providers: + description: A list of Fulfillment Provider IDs that can be used in the Region + type: array + items: + type: string + countries: + description: >- + A list of countries' 2 ISO characters that should be included in the + Region. + example: + - US + type: array + items: + type: string + includes_tax: + x-featureFlag: tax_inclusive_pricing + description: Whether taxes are included in the prices of the region. + type: boolean + AdminPostReservationsReq: + type: object + required: + - location_id + - inventory_item_id + - quantity + properties: + line_item_id: + description: The ID of the line item of the reservation. + 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 is associated with. + type: string + quantity: + description: The quantity to reserve. + type: number + metadata: + description: An optional set of key-value pairs with additional information. + 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 + AdminPostReservationsReservationReq: + type: object + properties: + location_id: + description: The ID of the location associated with the reservation. + type: string + quantity: + description: The quantity to reserve. + type: number + metadata: + description: An optional set of key-value pairs with additional information. + 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 + AdminPostReturnReasonsReasonReq: + type: object + properties: + label: + description: The label to display to the Customer. + type: string + value: + description: A unique value of the return reason. + type: string + description: + description: The description of the Reason. + type: string + metadata: + description: An optional set of key-value pairs with additional information. + 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 + AdminPostReturnReasonsReq: + type: object + required: + - label + - value + properties: + label: + description: The label to display to the Customer. + type: string + value: + description: A unique value of the return reason. + type: string + parent_return_reason_id: + description: The ID of the parent return reason. + type: string + description: + description: The description of the Reason. + type: string + metadata: + description: An optional set of key-value pairs with additional information. + 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 + AdminPostReturnsReturnReceiveReq: + type: object + required: + - items + properties: + items: + description: The Line Items that have been received. + type: array + items: + type: object + required: + - item_id + - quantity + properties: + item_id: + description: The ID of the Line Item. + type: string + quantity: + description: The quantity of the Line Item. + type: integer + refund: + description: The amount to refund. + type: number + AdminPostSalesChannelsChannelProductsBatchReq: + type: object + required: + - product_ids + properties: + product_ids: + description: The IDs of the products to add to the Sales Channel + type: array + items: + type: object + required: + - id + properties: + id: + type: string + description: The ID of the product + AdminPostSalesChannelsChannelStockLocationsReq: + type: object + required: + - location_id + properties: + location_id: + description: The ID of the stock location + type: string + AdminPostSalesChannelsReq: + type: object + required: + - name + properties: + name: + description: The name of the Sales Channel + type: string + description: + description: The description of the Sales Channel + type: string + is_disabled: + description: Whether the Sales Channel is disabled. + type: boolean + AdminPostSalesChannelsSalesChannelReq: + type: object + properties: + name: + type: string + description: The name of the sales channel + description: + type: string + description: The description of the sales channel. + is_disabled: + type: boolean + description: Whether the Sales Channel is disabled. + AdminPostShippingOptionsOptionReq: + type: object + required: + - requirements + properties: + name: + description: The name of the Shipping Option + type: string + amount: + description: >- + The amount to charge for the Shipping Option. If the `price_type` of + the shipping option is `calculated`, this amount will not actually + be used. + type: integer + admin_only: + description: >- + If set to `true`, the shipping option can only be used when creating + draft orders. + type: boolean + metadata: + description: An optional set of key-value pairs with additional information. + 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 + requirements: + description: >- + The requirements that must be satisfied for the Shipping Option to + be available. + type: array + items: + type: object + required: + - type + - amount + properties: + id: + description: >- + The ID of an existing requirement. If an ID is passed, the + existing requirement's details are updated. Otherwise, a new + requirement is created. + type: string + type: + description: The type of the requirement + type: string + enum: + - max_subtotal + - min_subtotal + amount: + description: The amount to compare with. + type: integer + includes_tax: + description: Tax included in prices of shipping option + x-featureFlag: tax_inclusive_pricing + type: boolean + AdminPostShippingOptionsReq: + type: object + required: + - name + - region_id + - provider_id + - data + - price_type + properties: + name: + description: The name of the Shipping Option + type: string + region_id: + description: The ID of the Region in which the Shipping Option will be available. + type: string + provider_id: + description: The ID of the Fulfillment Provider that handles the Shipping Option. + type: string + profile_id: + description: The ID of the Shipping Profile to add the Shipping Option to. + type: number + data: + description: >- + The data needed for the Fulfillment Provider to handle shipping with + this Shipping Option. + type: object + price_type: + description: >- + The type of the Shipping Option price. `flat_rate` indicates fixed + pricing, whereas `calculated` indicates that the price will be + calculated each time by the fulfillment provider. + type: string + enum: + - flat_rate + - calculated + amount: + description: >- + The amount to charge for the Shipping Option. If the `price_type` is + set to `calculated`, this amount will not actually be used. + type: integer + requirements: + description: >- + The requirements that must be satisfied for the Shipping Option to + be available. + type: array + items: + type: object + required: + - type + - amount + properties: + type: + description: The type of the requirement + type: string + enum: + - max_subtotal + - min_subtotal + amount: + description: The amount to compare with. + type: integer + is_return: + description: >- + Whether the Shipping Option can be used for returns or during + checkout. + type: boolean + default: false + admin_only: + description: >- + If set to `true`, the shipping option can only be used when creating + draft orders. + type: boolean + default: false + metadata: + description: An optional set of key-value pairs with additional information. + 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 + includes_tax: + description: Tax included in prices of shipping option + x-featureFlag: tax_inclusive_pricing + type: boolean + AdminPostShippingProfilesProfileReq: + type: object + properties: + name: + description: The name of the Shipping Profile + type: string + metadata: + description: An optional set of key-value pairs with additional information. + 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 + type: + description: The type of the Shipping Profile + type: string + enum: + - default + - gift_card + - custom + products: + description: product IDs to associate with the Shipping Profile + type: array + shipping_options: + description: Shipping option IDs to associate with the Shipping Profile + type: array + AdminPostShippingProfilesReq: + type: object + required: + - name + - type + properties: + name: + description: The name of the Shipping Profile + type: string + type: + description: The type of the Shipping Profile + type: string + enum: + - default + - gift_card + - custom + AdminPostStockLocationsLocationReq: + type: object + properties: + name: + description: the name of the stock location + type: string + address_id: + description: the stock location address ID + type: string + metadata: + type: object + description: An optional key-value map with additional details + 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 + address: + $ref: '#/components/schemas/StockLocationAddressInput' + AdminPostStockLocationsReq: + type: object + required: + - name + properties: + name: + description: the name of the stock location + type: string + address_id: + description: >- + the ID of an existing stock location address to associate with the + stock location. Only required if `address` is not provided. + type: string + metadata: + type: object + description: An optional key-value map with additional details + 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 + address: + description: >- + A new stock location address to create and associate with the stock + location. Only required if `address_id` is not provided. + $ref: '#/components/schemas/StockLocationAddressInput' + AdminPostStockLocationsReqAddress: + 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 + company: + type: string + description: Stock location address' company + city: + type: string + description: Stock location address' city + example: Mexico city + country_code: + description: The 2 character ISO code for the country. + type: string + externalDocs: + url: >- + https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements + description: See a list of codes. + 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 + AdminPostStoreReq: + type: object + properties: + name: + description: The name of the Store + type: string + swap_link_template: + description: >- + A template for Swap links - use `{{cart_id}}` to insert the Swap + Cart ID + type: string + example: http://example.com/swaps/{{cart_id}} + payment_link_template: + description: >- + A template for payment links - use `{{cart_id}}` to insert the Cart + ID + example: http://example.com/payments/{{cart_id}} + type: string + invite_link_template: + description: >- + A template for invite links - use `{{invite_token}}` to insert the + invite token + example: http://example.com/invite?token={{invite_token}} + type: string + default_currency_code: + description: The default currency code of the Store. + type: string + externalDocs: + url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes + description: See a list of codes. + currencies: + description: >- + Array of available currencies in the store. Each currency is in 3 + character ISO code format. + type: array + items: + type: string + externalDocs: + url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes + description: See a list of codes. + metadata: + description: An optional set of key-value pairs with additional information. + 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 + AdminPostTaxRatesReq: + type: object + required: + - code + - name + - region_id + properties: + code: + type: string + description: The code of the tax rate. + name: + type: string + description: The name of the tax rate. + region_id: + type: string + description: The ID of the Region that the tax rate belongs to. + rate: + type: number + description: The numeric rate to charge. + products: + type: array + description: The IDs of the products associated with this tax rate. + items: + type: string + shipping_options: + type: array + description: The IDs of the shipping options associated with this tax rate + items: + type: string + product_types: + type: array + description: The IDs of the types of products associated with this tax rate + items: + type: string + AdminPostTaxRatesTaxRateProductTypesReq: + type: object + required: + - product_types + properties: + product_types: + type: array + description: The IDs of the types of products to associate with this tax rate + items: + type: string + AdminPostTaxRatesTaxRateProductsReq: + type: object + required: + - products + properties: + products: + type: array + description: The IDs of the products to associate with this tax rate + items: + type: string + AdminPostTaxRatesTaxRateReq: + type: object + properties: + code: + type: string + description: The code of the tax rate. + name: + type: string + description: The name of the tax rate. + region_id: + type: string + description: The ID of the Region that the tax rate belongs to. + rate: + type: number + description: The numeric rate to charge. + products: + type: array + description: The IDs of the products associated with this tax rate + items: + type: string + shipping_options: + type: array + description: The IDs of the shipping options associated with this tax rate + items: + type: string + product_types: + type: array + description: The IDs of the types of product types associated with this tax rate + items: + type: string + AdminPostTaxRatesTaxRateShippingOptionsReq: + type: object + required: + - shipping_options + properties: + shipping_options: + type: array + description: The IDs of the shipping options to associate with this tax rate + items: + type: string + AdminPostUploadsDownloadUrlReq: + type: object + required: + - file_key + properties: + file_key: + description: >- + key of the file to obtain the download link for. This is obtained + when you first uploaded the file, or by the file service if you used + it directly. + type: string + AdminPriceListDeleteBatchRes: + type: object + required: + - ids + - object + - deleted + properties: + ids: + type: array + items: + type: string + description: The IDs of the deleted prices. + object: + type: string + description: >- + The type of the object that was deleted. A price is also named + `money-amount`. + default: money-amount + deleted: + type: boolean + description: Whether or not the items were deleted. + default: true + AdminPriceListDeleteProductPricesRes: + type: object + required: + - ids + - object + - deleted + properties: + ids: + type: array + description: The IDs of the deleted prices. + items: + type: string + object: + type: string + description: >- + The type of the object that was deleted. A price is also named + `money-amount`. + default: money-amount + deleted: + type: boolean + description: Whether or not the items were deleted. + default: true + AdminPriceListDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted Price List. + object: + type: string + description: The type of the object that was deleted. + default: price-list + deleted: + type: boolean + description: Whether or not the items were deleted. + default: true + AdminPriceListDeleteVariantPricesRes: + type: object + required: + - ids + - object + - deleted + properties: + ids: + type: array + description: The IDs of the deleted prices. + items: + type: string + object: + type: string + description: >- + The type of the object that was deleted. A price is also named + `money-amount`. + default: money-amount + deleted: + type: boolean + description: Whether or not the items were deleted. + default: true + AdminPriceListRes: + type: object + x-expanded-relations: + field: price_list + relations: + - customer_groups + - prices + required: + - price_list + properties: + price_list: + description: Price List details. + $ref: '#/components/schemas/PriceList' + AdminPriceListsListRes: + type: object + required: + - price_lists + - count + - offset + - limit + properties: + price_lists: + type: array + description: An array of price lists details. + items: + $ref: '#/components/schemas/PriceList' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: The number of price lists skipped when retrieving the price lists. + limit: + type: integer + description: The number of items per page + AdminPriceListsProductsListRes: + type: object + x-expanded-relations: + field: products + relations: + - categories + - collection + - images + - options + - tags + - type + - variants + - variants.options + required: + - products + - count + - offset + - limit + properties: + products: + type: array + description: An array of products details. + items: + $ref: '#/components/schemas/Product' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: The number of price lists skipped when retrieving the price lists. + limit: + type: integer + description: The number of items per page + AdminProductCategoriesCategoryDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted product category + object: + type: string + description: The type of the object that was deleted. + default: product-category + deleted: + type: boolean + description: Whether or not the items were deleted. + default: true + AdminProductCategoriesCategoryRes: + type: object + 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' + AdminProductCategoriesListRes: + type: object + 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 category 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 + AdminProductTagsListRes: + type: object + required: + - product_tags + - count + - offset + - limit + properties: + product_tags: + type: array + description: An array of product tag 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 + AdminProductTypesListRes: + 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 + AdminProductsDeleteOptionRes: + type: object + x-expanded-relations: + field: product + relations: + - collection + - images + - options + - tags + - type + - variants + - variants.options + - variants.prices + required: + - option_id + - object + - deleted + - product + properties: + option_id: + type: string + description: The ID of the deleted Product Option + object: + type: string + description: The type of the object that was deleted. + default: option + deleted: + type: boolean + description: Whether or not the items were deleted. + default: true + product: + description: Product details. + $ref: '#/components/schemas/PricedProduct' + AdminProductsDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted Product. + object: + type: string + description: The type of the object that was deleted. + default: product + deleted: + type: boolean + description: Whether or not the items were deleted. + default: true + AdminProductsDeleteVariantRes: + type: object + x-expanded-relations: + field: product + relations: + - collection + - images + - options + - tags + - type + - variants + - variants.options + - variants.prices + required: + - variant_id + - object + - deleted + - product + properties: + variant_id: + type: string + description: The ID of the deleted Product Variant. + object: + type: string + description: The type of the object that was deleted. + default: product-variant + deleted: + type: boolean + description: Whether or not the items were deleted. + default: true + product: + description: Product details. + $ref: '#/components/schemas/PricedProduct' + AdminProductsListRes: + type: object + x-expanded-relations: + field: products + relations: + - collection + - images + - options + - 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 + AdminProductsListTagsRes: + type: object + required: + - tags + properties: + tags: + description: An array of product tags details. + type: array + items: + type: object + required: + - id + - usage_count + - value + properties: + id: + description: The ID of the tag. + type: string + usage_count: + description: The number of products that use this tag. + type: string + value: + description: The value of the tag. + type: string + AdminProductsListTypesRes: + type: object + required: + - types + properties: + types: + type: array + description: An array of product types details. + items: + $ref: '#/components/schemas/ProductType' + AdminProductsListVariantsRes: + type: object + required: + - variants + - count + - offset + - limit + properties: + variants: + type: array + description: An array of product variants details. + items: + $ref: '#/components/schemas/ProductVariant' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: >- + The number of product variants skipped when retrieving the product + variants. + limit: + type: integer + description: The number of items per page + AdminProductsRes: + type: object + x-expanded-relations: + field: product + relations: + - collection + - images + - options + - tags + - type + - variants + - variants.options + - variants.prices + required: + - product + properties: + product: + description: Product details. + $ref: '#/components/schemas/PricedProduct' + AdminPublishableApiKeyDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted publishable API key. + object: + type: string + description: The type of the object that was deleted. + default: publishable_api_key + deleted: + type: boolean + description: Whether the publishable API key was deleted. + default: true + AdminPublishableApiKeysListRes: + type: object + required: + - publishable_api_keys + - count + - offset + - limit + properties: + publishable_api_keys: + type: array + description: An array of publishable API keys details. + items: + $ref: '#/components/schemas/PublishableApiKey' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: >- + The number of publishable API keys skipped when retrieving the + publishable API keys. + limit: + type: integer + description: The number of items per page + AdminPublishableApiKeysListSalesChannelsRes: + type: object + required: + - sales_channels + properties: + sales_channels: + description: An array of sales channels details. + type: array + items: + $ref: '#/components/schemas/SalesChannel' + AdminPublishableApiKeysRes: + type: object + required: + - publishable_api_key + properties: + publishable_api_key: + description: Publishable API key details. + $ref: '#/components/schemas/PublishableApiKey' + AdminRefundRes: + type: object + required: + - refund + properties: + refund: + description: Refund details + $ref: '#/components/schemas/Refund' + AdminRegionsDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted Region. + object: + type: string + description: The type of the object that was deleted. + default: region + deleted: + type: boolean + description: Whether or not the items were deleted. + default: true + AdminRegionsListRes: + type: object + x-expanded-relations: + field: regions + relations: + - countries + - fulfillment_providers + - payment_providers + eager: + - fulfillment_providers + - payment_providers + required: + - regions + - count + - offset + - limit + 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 + AdminRegionsRes: + type: object + x-expanded-relations: + field: region + relations: + - countries + - fulfillment_providers + - payment_providers + eager: + - fulfillment_providers + - payment_providers + required: + - region + properties: + region: + description: Region details. + $ref: '#/components/schemas/Region' + AdminReservationsDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted Reservation. + object: + type: string + description: The type of the object that was deleted. + default: reservation + deleted: + type: boolean + description: Whether or not the Reservation was deleted. + default: true + AdminReservationsListRes: + type: object + required: + - reservations + - count + - offset + - limit + properties: + reservations: + type: array + description: An array of reservations details. + items: + $ref: '#/components/schemas/ExtendedReservationItem' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: The number of reservations skipped when retrieving the reservations. + limit: + type: integer + description: The number of items per page + AdminReservationsRes: + type: object + required: + - reservation + properties: + reservation: + description: Reservation details. + $ref: '#/components/schemas/ReservationItemDTO' + AdminResetPasswordRequest: + type: object + required: + - token + - password + properties: + email: + description: The User's email. + type: string + format: email + token: + description: >- + The password-reset token generated when the password reset was + requested. + type: string + password: + description: The User's new password. + type: string + format: password + AdminResetPasswordTokenRequest: + type: object + required: + - email + properties: + email: + description: The User's email. + type: string + format: email + AdminReturnReasonsDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted return reason + object: + type: string + description: The type of the object that was deleted. + default: return_reason + deleted: + type: boolean + description: Whether or not the items were deleted. + default: true + AdminReturnReasonsListRes: + type: object + x-expanded-relations: + field: return_reasons + relations: + - parent_return_reason + - return_reason_children + required: + - return_reasons + properties: + return_reasons: + type: array + items: + $ref: '#/components/schemas/ReturnReason' + AdminReturnReasonsRes: + type: object + x-expanded-relations: + field: return_reason + relations: + - parent_return_reason + - return_reason_children + required: + - return_reason + properties: + return_reason: + $ref: '#/components/schemas/ReturnReason' + AdminReturnsCancelRes: + type: object + x-expanded-relations: + field: order + relations: + - billing_address + - claims + - claims.additional_items + - claims.additional_items.variant + - claims.claim_items + - claims.claim_items.images + - claims.claim_items.item + - claims.fulfillments + - claims.fulfillments.tracking_links + - claims.return_order + - claims.return_order.shipping_method + - claims.return_order.shipping_method.tax_lines + - claims.shipping_address + - claims.shipping_methods + - customer + - discounts + - discounts.rule + - fulfillments + - fulfillments.items + - fulfillments.tracking_links + - gift_card_transactions + - gift_cards + - items + - payments + - refunds + - region + - returns + - returns.items + - returns.items.reason + - returns.shipping_method + - returns.shipping_method.tax_lines + - shipping_address + - shipping_methods + - swaps + - swaps.additional_items + - swaps.additional_items.variant + - swaps.fulfillments + - swaps.fulfillments.tracking_links + - swaps.payment + - swaps.return_order + - swaps.return_order.shipping_method + - swaps.return_order.shipping_method.tax_lines + - swaps.shipping_address + - swaps.shipping_methods + - swaps.shipping_methods.tax_lines + required: + - order + properties: + order: + description: Order details. + $ref: '#/components/schemas/Order' + AdminReturnsListRes: + type: object + x-expanded-relation: + field: returns + relations: + - order + - swap + required: + - returns + - count + - offset + - limit + properties: + returns: + type: array + description: An array of returns details. + items: + $ref: '#/components/schemas/Return' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: The number of returns skipped when retrieving the returns. + limit: + type: integer + description: The number of items per page + AdminReturnsRes: + type: object + x-expanded-relation: + field: return + relations: + - swap + required: + - return + properties: + return: + description: Return details. + $ref: '#/components/schemas/Return' + AdminSalesChannelsDeleteLocationRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the removed stock location from a sales channel + object: + type: string + description: The type of the object that was removed. + default: stock-location + deleted: + type: boolean + description: Whether or not the items were deleted. + default: true + AdminSalesChannelsDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted sales channel + object: + type: string + description: The type of the object that was deleted. + default: sales-channel + deleted: + type: boolean + description: Whether or not the items were deleted. + default: true + AdminSalesChannelsListRes: + type: object + required: + - sales_channels + - count + - offset + - limit + properties: + sales_channels: + type: array + description: An array of sales channels details. + items: + $ref: '#/components/schemas/SalesChannel' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: The number of items skipped before the returned results + limit: + type: integer + description: The number of items per page + AdminSalesChannelsRes: + type: object + required: + - sales_channel + properties: + sales_channel: + description: Sales Channel's details. + $ref: '#/components/schemas/SalesChannel' + AdminShippingOptionsDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted Shipping Option. + object: + type: string + description: The type of the object that was deleted. + default: shipping-option + deleted: + type: boolean + description: Whether or not the items were deleted. + default: true + AdminShippingOptionsListRes: + type: object + x-expanded-relations: + field: shipping_options + relations: + - profile + - region + - requirements + eager: + - region.fulfillment_providers + - region.payment_providers + required: + - shipping_options + - count + - offset + - limit + properties: + shipping_options: + type: array + description: An array of shipping options details. + items: + $ref: '#/components/schemas/ShippingOption' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: >- + The number of shipping options skipped when retrieving the shipping + options. + limit: + type: integer + description: The number of items per page + AdminShippingOptionsRes: + type: object + x-expanded-relations: + field: shipping_option + relations: + - profile + - region + - requirements + eager: + - region.fulfillment_providers + - region.payment_providers + required: + - shipping_option + properties: + shipping_option: + description: Shipping option details. + $ref: '#/components/schemas/ShippingOption' + AdminShippingProfilesListRes: + type: object + required: + - shipping_profiles + properties: + shipping_profiles: + type: array + description: An array of shipping profiles details. + items: + $ref: '#/components/schemas/ShippingProfile' + AdminShippingProfilesRes: + type: object + x-expanded-relations: + field: shipping_profile + relations: + - products + - shipping_options + required: + - shipping_profile + properties: + shipping_profile: + description: Shipping profile details. + $ref: '#/components/schemas/ShippingProfile' + AdminStockLocationsDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted Stock Location. + object: + type: string + description: The type of the object that was deleted. + default: stock_location + deleted: + type: boolean + description: Whether or not the items were deleted. + default: true + AdminStockLocationsListRes: + type: object + required: + - stock_locations + - count + - offset + - limit + properties: + stock_locations: + type: array + items: + $ref: '#/components/schemas/StockLocationExpandedDTO' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: >- + The number of stock locations skipped when retrieving the stock + locations. + limit: + type: integer + description: The number of items per page + AdminStockLocationsRes: + type: object + required: + - stock_location + properties: + stock_location: + description: Stock location details. + $ref: '#/components/schemas/StockLocationExpandedDTO' + AdminStoresRes: + type: object + required: + - store + properties: + store: + description: Store details. + $ref: '#/components/schemas/Store' + AdminSwapsListRes: + type: object + required: + - swaps + - count + - offset + - limit + properties: + swaps: + type: array + description: An array of swaps details. + items: + $ref: '#/components/schemas/Swap' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: The number of swaps skipped when retrieving the swaps. + limit: + type: integer + description: The number of items per page + AdminSwapsRes: + type: object + x-expanded-relations: + field: swap + relations: + - additional_items + - additional_items.adjustments + - cart + - cart.items + - cart.items.adjustments + - cart.items.variant + - fulfillments + - order + - payment + - return_order + - shipping_address + - shipping_methods + eager: + - fulfillments.items + - shipping_methods.shipping_option + required: + - swap + properties: + swap: + description: Swap details. + $ref: '#/components/schemas/Swap' + AdminTaxProvidersList: + type: object + required: + - tax_providers + properties: + tax_providers: + type: array + description: An array of tax providers details. + items: + $ref: '#/components/schemas/TaxProvider' + AdminTaxRatesDeleteRes: + type: object + required: + - id + - object + - deleted + properties: + id: + type: string + description: The ID of the deleted Shipping Option. + object: + type: string + description: The type of the object that was deleted. + default: tax-rate + deleted: + type: boolean + description: Whether or not the items were deleted. + default: true + AdminTaxRatesListRes: + type: object + required: + - tax_rates + - count + - offset + - limit + properties: + tax_rates: + type: array + description: An array of tax rate details. + items: + $ref: '#/components/schemas/TaxRate' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: The number of tax rates to skip when retrieving the tax rates. + limit: + type: integer + description: The number of items per page + AdminTaxRatesRes: + type: object + required: + - tax_rate + properties: + tax_rate: + description: Tax rate details. + $ref: '#/components/schemas/TaxRate' + AdminUpdatePaymentCollectionsReq: + type: object + properties: + description: + description: A description to create or update the payment collection. + type: string + metadata: + description: A set of key-value pairs to hold additional information. + 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 + AdminUpdateUserRequest: + type: object + properties: + first_name: + description: The first name of the User. + type: string + last_name: + description: The last name of the User. + type: string + role: + description: >- + The role assigned to the user. These roles don't provide any + different privileges. + type: string + enum: + - admin + - member + - developer + api_token: + description: The API token of the User. + type: string + metadata: + description: An optional set of key-value pairs with additional information. + 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 + AdminUploadsDownloadUrlRes: + type: object + required: + - download_url + properties: + download_url: + description: The Download URL of the file + type: string + AdminUploadsRes: + type: object + required: + - uploads + properties: + uploads: + type: array + description: Uploaded files details. + items: + type: object + required: + - url + - key + properties: + url: + description: The URL of the uploaded file. + type: string + format: uri + key: + description: >- + The key of the file that is identifiable by the file service. + It can be used later to retrieve or manipulate the file. + type: string + AdminUserRes: + type: object + required: + - user + properties: + user: + description: User details. + $ref: '#/components/schemas/User' + AdminUsersListRes: + type: object + required: + - users + properties: + users: + type: array + description: An array of users details. + items: + $ref: '#/components/schemas/User' + AdminVariantsListRes: + type: object + x-expanded-relations: + field: variants + relations: + - options + - prices + - product + totals: + - purchasable + required: + - variants + - count + - offset + - limit + properties: + variants: + type: array + description: An array of product variant details. + items: + $ref: '#/components/schemas/PricedVariant' + count: + type: integer + description: The total number of items available + offset: + type: integer + description: >- + The number of product variants skipped when retrieving the product + variants. + limit: + type: integer + description: The number of items per page + AdminVariantsRes: + type: object + x-expanded-relations: + field: variant + relations: + - options + - prices + - product + required: + - variant + properties: + variant: + description: Product variant's details. + $ref: '#/components/schemas/PricedVariant' + 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 + 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 + DecoratedInventoryItemDTO: + type: object + allOf: + - $ref: '#/components/schemas/InventoryItemDTO' + - type: object + required: + - stocked_quantity + - reserved_quantity + properties: + location_levels: + type: array + description: An array of location level details + items: + $ref: '#/components/schemas/InventoryLevelDTO' + variants: + type: array + description: An array of product variant details + items: + $ref: '#/components/schemas/ProductVariant' + stocked_quantity: + type: number + description: The total quantity of the item in stock across levels + reserved_quantity: + type: number + description: The total quantity of the item available across levels + 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 + ExtendedReservationItem: + type: object + allOf: + - $ref: '#/components/schemas/ReservationItemDTO' + - type: object + properties: + line_item: + description: The line item associated with the reservation. + $ref: '#/components/schemas/LineItem' + inventory_item: + description: The inventory item associated with the reservation. + $ref: '#/components/schemas/InventoryItemDTO' + ExtendedStoreDTO: + allOf: + - $ref: '#/components/schemas/Store' + - type: object + required: + - payment_providers + - fulfillment_providers + - feature_flags + - modules + properties: + payment_providers: + $ref: '#/components/schemas/PaymentProvider' + fulfillment_providers: + $ref: '#/components/schemas/FulfillmentProvider' + feature_flags: + $ref: '#/components/schemas/FeatureFlagsResponse' + modules: + $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: + 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 + 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 3 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: + 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 + - 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 + 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 + 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 + properties: + 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 + 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 3 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 + ResponseInventoryItem: + allOf: + - $ref: '#/components/schemas/InventoryItemDTO' + - type: object + properties: + location_levels: + type: array + description: The inventory's location levels. + items: + allOf: + - $ref: '#/components/schemas/InventoryItemDTO' + - type: object + required: + - available_quantity + properties: + available_quantity: + description: The available quantity in the inventory location. + type: number + 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 + 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: + $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_currency_code: + description: The 3 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 + 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 + 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 + VariantInventory: + type: object + required: + - id + - inventory + - sales_channel_availability + properties: + id: + description: the ID of the variant + type: string + inventory: + description: The inventory details. + $ref: '#/components/schemas/ResponseInventoryItem' + sales_channel_availability: + type: array + description: >- + An array of details about the variant's inventory availability in + sales channels. + items: + type: object + required: + - channel_name + - channel_id + - available_quantity + properties: + channel_name: + description: Sales channel's name + type: string + channel_id: + description: Sales channel's ID + type: string + available_quantity: + description: Available quantity in the sales channel + type: number diff --git a/www/apps/api-reference/specs/store/openapi.full.yaml b/www/apps/api-reference/specs/store/openapi.full.yaml new file mode 100644 index 0000000000000..d0c1366451f83 --- /dev/null +++ b/www/apps/api-reference/specs/store/openapi.full.yaml @@ -0,0 +1,14440 @@ +openapi: 3.0.0 +info: + version: 1.0.0 + title: Medusa Storefront API + license: + name: MIT + url: https://github.com/medusajs/medusa/blob/master/LICENSE +tags: + - name: Auth + description: > + Authentication API Routes allow customers to manage their session, such as + login or log out. + + When a customer is logged in, the cookie header is set indicating the + customer's login session. + externalDocs: + description: How to implement customer profiles in your storefront + url: >- + https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles + - name: Carts + description: > + A cart is a virtual shopping bag that customers can use to add items they + want to purchase. + + A cart is then used to checkout and place an order. + externalDocs: + description: How to implement cart functionality in your storefront + url: >- + https://docs.medusajs.com/modules/carts-and-checkout/storefront/implement-cart + - name: Customers + description: > + A customer can register and manage their information such as addresses, + orders, payment methods, and more. + externalDocs: + description: How to implement customer profiles in your storefront + url: >- + https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles + - name: Gift Cards + description: > + Customers can use gift cards during checkout to deduct the gift card's + balance from the checkout total. + + The Gift Card API Routes allow retrieving a gift card's details by its + code. A gift card can be applied to a cart using the Carts API Routes. + externalDocs: + description: How to use gift cards in a storefront + url: https://docs.medusajs.com/modules/gift-cards/storefront/use-gift-cards + - name: Orders + description: > + Orders are purchases made by customers, typically through a storefront. + + Orders are placed and created using the Carts API Routes. The Orders API + Routes allow retrieving and claiming orders. + externalDocs: + description: How to retrieve order details in a storefront + url: >- + https://docs.medusajs.com/modules/orders/storefront/retrieve-order-details + - name: Order Edits + description: > + Order edits are changes made to items in an order such as adding, updating + their quantity, or deleting them. Order edits are created by the admin. + + A customer can review order edit requests created by an admin and confirm + or decline them. + externalDocs: + description: How to handle order edits in a storefront + url: https://docs.medusajs.com/modules/orders/storefront/handle-order-edits + - name: Payment Collections + description: > + A payment collection is useful for managing additional payments, such as + for Order Edits, or installment payments. + - name: Products + description: > + Products are saleable items in a store. This also includes [saleable gift + cards](https://docs.medusajs.com/modules/gift-cards/storefront/use-gift-cards) + in a store. + + Using these API Routes, you can filter products by categories, + collections, sales channels, and more. + externalDocs: + description: How to show products in a storefront + url: https://docs.medusajs.com/modules/products/storefront/show-products + - name: Product Variants + description: > + Product variants are the actual salable item in your store. Each variant + is a combination of the different option values available on the product. + - name: Product Categories + description: > + Products can be categoriezed into categories. A product can be associated + more than one category. + + Using these API Routes, you can list or retrieve a category's details and + products. + externalDocs: + description: How to use product categories in a storefront + url: https://docs.medusajs.com/modules/products/storefront/use-categories + - name: Product Collections + description: > + A product collection is used to organize products for different purposes + such as marketing or discount purposes. For example, you can create a + Summer Collection. + + Using these API Routes, you can list or retrieve a collection's details + and products. + - name: Product Tags + description: | + Product tags are string values that can be used to filter products by. + Products can have more than one tag, and products can share tags. + - name: Product Types + description: | + Product types are string values that can be used to filter products by. + Products can have more than one tag, and products can share types. + - name: Regions + description: > + Regions are different countries or geographical regions that the commerce + store serves customers in. + + Customers can choose what region they're in, which can be used to change + the prices shown based on the region and its currency. + externalDocs: + description: How to use regions in a storefront + url: >- + https://docs.medusajs.com/modules/regions-and-currencies/storefront/use-regions + - name: Returns + description: | + A return can be created by a customer to return items in an order. + externalDocs: + description: How to create a return in a storefront + url: https://docs.medusajs.com/modules/orders/storefront/create-return + - name: Return Reasons + description: > + Return reasons are key-value pairs that are used to specify why an order + return is being created. + - name: Shipping Options + description: > + A shipping option is used to define the available shipping methods during + checkout or when creating a return. + externalDocs: + description: Shipping Option architecture + url: >- + https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-option + - name: Swaps + description: > + A swap is created by a customer or an admin to exchange an item with a new + one. + + Creating a swap implicitely includes creating a return for the item being + exchanged. + externalDocs: + description: How to create a swap in a storefront + url: https://docs.medusajs.com/modules/orders/storefront/create-swap +servers: + - url: https://api.medusa-commerce.com +paths: + /store/auth: + get: + operationId: GetAuth + summary: Get Current Customer + description: Retrieve the currently logged in Customer's details. + x-authenticated: true + x-codegen: + method: getSession + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + // must be previously logged + + medusa.auth.getSession() + + .then(({ customer }) => { + console.log(customer.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/store/auth' \ + -H 'Authorization: Bearer {access_token}' + security: + - cookie_auth: [] + - jwt_token: [] + tags: + - Auth + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StoreAuthRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + post: + operationId: PostAuth + summary: Customer Login + description: >- + Log a customer in and includes the Cookie session in the response + 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/StorePostAuthReq' + x-codegen: + method: authenticate + 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.auth.authenticate({ + email: "user@example.com", + password: "user@example.com" + }) + + .then(({ customer }) => { + console.log(customer.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/store/auth' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "email": "user@example.com", + "password": "supersecret" + }' + tags: + - Auth + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StoreAuthRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/incorrect_credentials' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + delete: + operationId: DeleteAuth + summary: Customer Log out + description: Delete the current session for the logged in customer. + x-authenticated: true + x-codegen: + method: deleteSession + x-codeSamples: + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/store/auth' \ + -H 'Authorization: Bearer {access_token}' + security: + - cookie_auth: [] + - jwt_token: [] + tags: + - Auth + responses: + '200': + description: OK + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /store/auth/token: + post: + operationId: PostToken + summary: Customer Login (JWT) + x-authenticated: false + description: >- + After a successful login, a JWT token is returned, which can be used to + send authenticated requests. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StorePostAuthReq' + x-codegen: + method: getToken + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + medusa.auth.getToken({ + email: 'user@example.com', + password: 'supersecret' + }) + + .then(({ access_token }) => { + console.log(access_token); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/store/auth/token' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "email": "user@example.com", + "password": "supersecret" + }' + tags: + - Auth + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StoreBearerAuthRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/incorrect_credentials' + '404': + $ref: '#/components/responses/not_found_error' + '409': + $ref: '#/components/responses/invalid_state_error' + '422': + $ref: '#/components/responses/invalid_request_error' + '500': + $ref: '#/components/responses/500_error' + /store/auth/{email}: + get: + operationId: GetAuthEmail + summary: Check if Email Exists + description: Check if there's a customer already registered with the provided email. + parameters: + - in: path + name: email + schema: + type: string + format: email + required: true + description: The email to check. + x-codegen: + method: exists + 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.auth.exists("user@example.com") + - lang: Shell + label: cURL + source: | + curl '{backend_url}/store/auth/user@example.com' + tags: + - Auth + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StoreGetAuthEmailRes' + '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: + post: + operationId: PostCart + summary: Create a Cart + description: > + Create a Cart. Although optional, specifying the cart's region and sales + channel can affect the cart's pricing and + + the products that can be added to the cart respectively. So, make sure + to set those early on and change them if necessary, such as when the + customer changes their region. + + + If a customer is logged in, the cart's customer ID and email will + automatically be set. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StorePostCartReq' + 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.carts.create() + + .then(({ cart }) => { + console.log(cart.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/store/carts' + tags: + - Carts + responses: + '200': + description: Successfully created a new Cart + 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}: + get: + operationId: GetCartsCart + summary: Get a Cart + description: Retrieve a Cart's details. This includes recalculating its totals. + parameters: + - in: path + name: id + required: true + description: The ID of the Cart. + 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.carts.retrieve(cartId) + + .then(({ cart }) => { + console.log(cart.id); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/store/carts/{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' + post: + operationId: PostCartsCart + summary: Update a Cart + description: >- + Update a Cart's details. If the cart has payment sessions and the region + was not changed, the payment sessions are updated. The cart's totals are + also recalculated. + parameters: + - in: path + name: id + required: true + description: The ID of the Cart. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StorePostCartsCartReq' + 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 }) + + medusa.carts.update(cartId, { + email: "user@example.com" + }) + + .then(({ cart }) => { + console.log(cart.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/store/carts/{id}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "email": "user@example.com" + }' + 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}/complete: + post: + summary: Complete a Cart + operationId: PostCartsCartComplete + description: > + Complete a cart and place an order or create a swap, based on what the + cart is created for. This includes attempting to authorize the cart's + payment. + + If authorizing the payment requires more action, the cart will not be + completed and the order will not be placed or the swap will not be + created. + + + An idempotency key will be generated if none is provided in the header + `Idempotency-Key` and added to + + the response. If an error occurs during cart completion or the request + is interrupted for any reason, the cart completion can be retried by + passing the idempotency + + key in the `Idempotency-Key` header. + externalDocs: + description: Cart completion overview + url: >- + https://docs.medusajs.com/modules/carts-and-checkout/cart#cart-completion + parameters: + - in: path + name: id + required: true + description: The Cart ID. + schema: + type: string + x-codegen: + method: complete + 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.complete(cartId) + + .then(({ cart }) => { + console.log(cart.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/store/carts/{id}/complete' + tags: + - Carts + responses: + '200': + description: >- + If the payment of the cart was successfully authorized, but requires + further action from the customer, the response body will contain the + cart with an updated payment session. Otherwise, if the payment was + authorized and the cart was successfully completed, the response + body will contain either the newly created order or swap, depending + on what the cart was created for. + content: + application/json: + schema: + $ref: '#/components/schemas/StoreCompleteCartRes' + '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}/discounts/{code}: + delete: + operationId: DeleteCartsCartDiscountsDiscount + summary: Remove Discount + description: >- + Remove a Discount from a Cart. This only removes the application of the + discount, and not completely delete it. The totals will be re-calculated + and the payment sessions will be refreshed after the removal. + parameters: + - in: path + name: id + required: true + description: The ID of the Cart. + schema: + type: string + - in: path + name: code + required: true + description: The unique discount code. + schema: + type: string + x-codegen: + method: deleteDiscount + 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.deleteDiscount(cartId, code) + + .then(({ cart }) => { + console.log(cart.id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/store/carts/{id}/discounts/{code}' + 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}/line-items: + post: + operationId: PostCartsCartLineItems + summary: Add a Line Item + description: >- + Generates a Line Item with a given Product Variant and adds it to the + Cart + parameters: + - in: path + name: id + required: true + description: The id of the Cart to add the Line Item to. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StorePostCartsCartLineItemsReq' + x-codegen: + method: createLineItem + 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.lineItems.create(cart_id, { + variant_id, + quantity: 1 + }) + + .then(({ cart }) => { + console.log(cart.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/store/carts/{id}/line-items' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "variant_id": "{variant_id}", + "quantity": 1 + }' + 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}/line-items/{line_id}: + post: + operationId: PostCartsCartLineItemsItem + summary: Update a Line Item + description: Update a line item's quantity. + parameters: + - in: path + name: id + required: true + description: The ID of the Cart. + schema: + type: string + - in: path + name: line_id + required: true + description: The ID of the Line Item. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StorePostCartsCartLineItemsItemReq' + x-codegen: + method: updateLineItem + x-codeSamples: + - lang: JavaScript + label: JS Client + source: > + import Medusa from "@medusajs/medusa-js" + + const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: + 3 }) + + medusa.carts.lineItems.update(cartId, lineId, { + quantity: 1 + }) + + .then(({ cart }) => { + console.log(cart.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/store/carts/{id}/line-items/{line_id}' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "quantity": 1 + }' + 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: DeleteCartsCartLineItemsItem + summary: Delete a Line Item + description: >- + Delete a Line Item from a Cart. The payment sessions will be updated and + the totals will be recalculated. + parameters: + - in: path + name: id + required: true + description: The ID of the Cart. + schema: + type: string + - in: path + name: line_id + required: true + description: The ID of the Line Item. + schema: + type: string + x-codegen: + method: deleteLineItem + 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.lineItems.delete(cartId, lineId) + + .then(({ cart }) => { + console.log(cart.id); + }); + - lang: Shell + label: cURL + source: | + curl -X DELETE '{backend_url}/store/carts/{id}/line-items/{line_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-session: + post: + operationId: PostCartsCartPaymentSession + summary: Select a Payment Session + description: >- + Select the Payment Session that will be used to complete the cart. This + is typically used when the customer chooses their preferred payment + method during checkout. The totals of the cart will be recalculated. + parameters: + - in: path + name: id + required: true + description: The ID of the Cart. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StorePostCartsCartPaymentSessionReq' + x-codegen: + method: setPaymentSession + 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.setPaymentSession(cartId, { + provider_id: "manual" + }) + + .then(({ cart }) => { + console.log(cart.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/store/carts/{id}/payment-sessions' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "provider_id": "manual" + }' + 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: + post: + operationId: PostCartsCartPaymentSessions + summary: Create Payment Sessions + description: >- + Create Payment Sessions for each of the available Payment Providers in + the Cart's Region. If there only one payment session is created, it will + be selected by default. The creation of the payment session uses the + payment provider and may require sending requests to third-party + services. + parameters: + - in: path + name: id + required: true + description: The ID of the Cart. + schema: + type: string + x-codegen: + method: createPaymentSessions + 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.createPaymentSessions(cartId) + + .then(({ cart }) => { + console.log(cart.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/store/carts/{id}/payment-sessions' + 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}: + post: + operationId: PostCartsCartPaymentSessionUpdate + summary: Update a Payment Session + description: >- + Update a Payment Session with additional data. This can be useful + depending on the payment provider used. All payment sessions are updated + and cart totals are recalculated afterwards. + 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. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StorePostCartsCartPaymentSessionUpdateReq' + x-codegen: + method: updatePaymentSession + 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.updatePaymentSession(cartId, "manual", { + data: { + + } + }) + + .then(({ cart }) => { + console.log(cart.id); + }); + - 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: 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: 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: 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: Shell + label: cURL + source: | + curl '{backend_url}/store/collections' + tags: + - Product Collections + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StoreCollectionsListRes' + '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/{id}: + get: + operationId: GetCollectionsCollection + summary: Get a Collection + description: Retrieve a Product Collection's details. + parameters: + - in: path + name: id + required: true + description: The id of the Product Collection + 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.collections.retrieve(collectionId) + + .then(({ collection }) => { + console.log(collection.id); + }); + - 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: 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: 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: 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: Shell + label: cURL + source: | + curl '{backend_url}/store/customers/me/orders' \ + -H 'Authorization: Bearer {access_token}' + security: + - cookie_auth: [] + - jwt_token: [] + tags: + - Customers + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StoreCustomersListOrdersRes' + '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/payment-methods: + get: + operationId: GetCustomersCustomerPaymentMethods + summary: Get Saved Payment Methods + description: >- + Retrieve the logged-in customer's saved payment methods. This API Route + only works with payment providers created with the deprecated Payment + Service interface. The payment methods are saved using the Payment + Service's third-party service, and not on the Medusa backend. So, + they're retrieved from the third-party service. + x-authenticated: true + deprecated: true + x-codegen: + method: listPaymentMethods + 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.paymentMethods.list() + + .then(({ payment_methods }) => { + console.log(payment_methods.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/store/customers/me/payment-methods' \ + -H 'Authorization: Bearer {access_token}' + security: + - cookie_auth: [] + - jwt_token: [] + tags: + - Customers + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StoreCustomersListPaymentMethodsRes' + '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/password-reset: + post: + operationId: PostCustomersResetPassword + summary: Reset Password + description: >- + Reset a Customer's password using a password token created by a previous + request to the Request Password Reset API Route. If the password token + expired, you must create a new one. + externalDocs: + description: How to reset password + url: >- + https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles#reset-password + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StorePostCustomersResetPasswordReq' + x-codegen: + method: resetPassword + 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.resetPassword({ + email: "user@example.com", + password: "supersecret", + token: "supersecrettoken" + }) + + .then(({ customer }) => { + console.log(customer.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/store/customers/password-reset' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "email": "user@example.com", + "password": "supersecret", + "token": "supersecrettoken" + }' + tags: + - Customers + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StoreCustomersResetPasswordRes' + '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/password-token: + post: + operationId: PostCustomersCustomerPasswordToken + summary: Request Password Reset + description: >- + Create a reset password token to be used in a subsequent Reset Password + API Route. This emits the event `customer.password_reset`. If a + notification provider is installed in the Medusa backend and is + configured to handle this event, a notification to the customer, such as + an email, may be sent with reset instructions. + externalDocs: + description: How to reset password + url: >- + https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles#reset-password + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StorePostCustomersCustomerPasswordTokenReq' + x-codegen: + method: generatePasswordToken + 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.generatePasswordToken({ + email: "user@example.com" + }) + + .then(() => { + // successful + }) + + .catch(() => { + // failed + }) + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/store/customers/password-token' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "email": "user@example.com" + }' + tags: + - Customers + responses: + '204': + 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/gift-cards/{code}: + get: + operationId: GetGiftCardsCode + summary: Get Gift Card by Code + description: Retrieve a Gift Card's details by its associated unique code. + parameters: + - in: path + name: code + required: true + description: The unique Gift Card code. + 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.giftCards.retrieve(code) + + .then(({ gift_card }) => { + console.log(gift_card.id); + }); + - 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: Shell + label: cURL + source: | + curl '{backend_url}/store/order-edits/{id}' + tags: + - Order Edits + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StoreOrderEditsRes' + '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/order-edits/{id}/complete: + post: + operationId: PostOrderEditsOrderEditComplete + summary: Complete an Order Edit + description: >- + Complete an Order Edit and reflect its changes on the original order. + Any additional payment required must be authorized first using the + Payment Collection API Routes. + externalDocs: + description: How to handle order edits in a storefront + url: https://docs.medusajs.com/modules/orders/storefront/handle-order-edits + parameters: + - in: path + name: id + required: true + description: The ID of the Order Edit. + schema: + type: string + x-codegen: + method: complete + 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.complete(orderEditId) + .then(({ order_edit }) => { + console.log(order_edit.id) + }) + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/store/order-edits/{id}/complete' + tags: + - Order Edits + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StoreOrderEditsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '500': + $ref: '#/components/responses/500_error' + /store/order-edits/{id}/decline: + post: + operationId: PostOrderEditsOrderEditDecline + summary: Decline an Order Edit + description: >- + Decline an Order Edit. The changes are not reflected on the original + order. + parameters: + - in: path + name: id + required: true + description: The ID of the OrderEdit. + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StorePostOrderEditsOrderEditDecline' + x-codegen: + method: decline + 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.decline(orderEditId) + .then(({ order_edit }) => { + console.log(order_edit.id); + }) + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/store/order-edits/{id}/decline' + tags: + - Order Edits + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StoreOrderEditsRes' + '400': + $ref: '#/components/responses/400_error' + '401': + $ref: '#/components/responses/unauthorized' + '404': + $ref: '#/components/responses/not_found_error' + '500': + $ref: '#/components/responses/500_error' + /store/orders: + get: + operationId: GetOrders + summary: Look Up an Order + description: >- + Look up an order using filters. If the filters don't narrow down the + results to a single order, a 404 response is returned with no orders. + parameters: + - in: query + name: display_id + required: true + description: Filter by ID. + schema: + type: number + - 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 expanded in the returned + order. + schema: + type: string + - in: query + name: email + style: form + explode: false + description: Filter by email. + required: true + schema: + type: string + format: email + - in: query + name: shipping_address + style: form + explode: false + description: Filter by the shipping address's postal code. + schema: + type: object + properties: + postal_code: + type: string + description: The postal code of the shipping address + x-codegen: + method: lookupOrder + queryParams: StoreGetOrdersParams + 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.lookupOrder({ + display_id: 1, + email: "user@example.com" + }) + + .then(({ order }) => { + console.log(order.id); + }); + - 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: 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: 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: 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: 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: 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: 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 Collections. + 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: 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: 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: 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 Collections. + 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: 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: Shell + label: cURL + source: | + curl '{backend_url}/store/product-categories' \ + -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/StoreGetProductCategoriesRes' + '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/{id}: + get: + operationId: GetProductCategoriesCategory + summary: Get a Product Category + description: Retrieve a Product Category's details. + x-featureFlag: product_categories + parameters: + - in: path + name: id + required: true + description: The ID of the Product Category + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be expanded in the returned + product category. + schema: + type: string + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + product category. + schema: + type: string + x-codegen: + method: retrieve + queryParams: StoreGetProductCategoriesCategoryParams + 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.productCategories.retrieve(productCategoryId) + .then(({ product_category }) => { + console.log(product_category.id); + }); + - 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: Shell + label: cURL + source: | + curl '{backend_url}/store/product-tags' + tags: + - Product Tags + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StoreProductTagsListRes' + '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-types: + get: + operationId: GetProductTypes + summary: List Product Types + description: >- + Retrieve a list of product types. The product types can be filtered by + fields such as `value` or `q`. The product types can also be sorted or + paginated. + x-authenticated: true + parameters: + - in: query + name: limit + description: Limit the number of product types returned. + schema: + type: integer + default: 20 + - in: query + name: offset + description: >- + The number of product types to skip when retrieving the product + types. + schema: + type: integer + default: 0 + - in: query + name: order + description: A product-type field to sort-order the retrieved product types by. + schema: + type: string + - in: query + name: discount_condition_id + description: >- + Filter by the ID of a discount condition. When provided, only types + that the discount condition applies for will be retrieved. + schema: + type: string + - in: query + name: value + style: form + explode: false + description: Filter by type 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 type'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-codegen: + method: list + queryParams: StoreGetProductTypesParams + 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.productTypes.list() + + .then(({ product_types }) => { + console.log(product_types.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/store/product-types' + security: + - api_token: [] + - cookie_auth: [] + - jwt_token: [] + tags: + - Product Types + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StoreProductTypesListRes' + '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/products: + get: + operationId: GetProducts + summary: List Products + description: > + Retrieves a list of products. The products can be filtered by fields + such as `id` or `q`. The products can also be sorted or paginated. + + This API Route can also be used to retrieve a product by its handle. + + + For accurate and correct pricing of the products 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 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 retrieve a product by its handle + url: >- + https://docs.medusajs.com/modules/products/storefront/show-products#retrieve-product-by-handle + parameters: + - in: query + name: q + description: >- + term used to search products' title, description, variant's title, + variant's sku, and collection's title. + schema: + type: string + - in: query + name: id + style: form + explode: false + description: Filter by IDs. + schema: + oneOf: + - type: string + - type: array + items: + type: string + - in: query + name: sales_channel_id + style: form + explode: false + 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: array + items: + type: string + - in: query + name: collection_id + style: form + explode: false + description: >- + Filter by product collection IDs. When provided, only products that + belong to the specified product collections are retrieved. + schema: + type: array + items: + type: string + - in: query + name: type_id + style: form + explode: false + description: >- + Filter by product type IDs. When provided, only products that belong + to the specified product types are retrieved. + schema: + type: array + items: + type: string + - in: query + name: tags + style: form + explode: false + description: >- + Filter by product tag IDs. When provided, only products that belong + to the specified product tags are retrieved. + schema: + type: array + items: + type: string + - in: query + name: title + description: Filter by title. + schema: + type: string + - in: query + name: description + description: Filter by description + schema: + type: string + - in: query + name: handle + description: Filter by handle. + schema: + type: string + - in: query + name: is_giftcard + description: Whether to retrieve regular products or gift-card products. + schema: + type: boolean + - in: query + name: created_at + description: Filter by a creation date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: updated_at + description: Filter by an update date range. + schema: + type: object + properties: + lt: + type: string + description: filter by dates less than this date + format: date + gt: + type: string + description: filter by dates greater than this date + format: date + lte: + type: string + description: filter by dates less than or equal to this date + format: date + gte: + type: string + description: filter by dates greater than or equal to this date + format: date + - in: query + name: category_id + style: form + explode: false + description: >- + Filter by product category IDs. When provided, only products that + belong to the specified product categories are retrieved. + schema: + type: array + x-featureFlag: product_categories + items: + type: string + - in: query + name: include_category_children + style: form + explode: false + description: >- + Whether to include child product categories when filtering using the + `category_id` field. + schema: + type: boolean + x-featureFlag: product_categories + - in: query + name: offset + description: The number of products to skip when retrieving the products. + schema: + type: integer + default: 0 + - in: query + name: limit + description: Limit the number of products returned. + schema: + type: integer + default: 100 + - in: query + name: expand + description: >- + Comma-separated relations that should be expanded in the returned + products. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + products. + schema: + type: string + - in: query + name: order + description: A product field to sort-order the retrieved products by. + 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: list + queryParams: StoreGetProductsParams + 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.products.list() + + .then(({ products, limit, offset, count }) => { + console.log(products.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/store/products' + tags: + - Products + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StoreProductsListRes' + '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/products/search: + post: + operationId: PostProductsSearch + summary: Search Products + description: >- + Run a search query on products using the search service installed on the + Medusa backend. The searching is handled through the search service, so + the returned data's format depends on the search service you're using. + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StorePostSearchReq' + x-codegen: + method: search + 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.products.search({ + q: "Shirt" + }) + + .then(({ hits }) => { + console.log(hits.length); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/store/products/search' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "q": "Shirt" + }' + tags: + - Products + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StorePostSearchRes' + '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/products/{id}: + get: + operationId: GetProductsProduct + summary: Get a Product + description: > + Retrieve a Product's details. For accurate and correct pricing of the + product 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 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. + schema: + type: string + - in: query + name: sales_channel_id + description: >- + The ID of the sales channel the customer is viewing the product + 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: expand + description: >- + Comma-separated relations that should be expanded in the returned + product. + schema: + type: string + - in: query + name: fields + description: >- + Comma-separated fields that should be included in the returned + product. + 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: StoreGetProductsProductParams + 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.products.retrieve(productId) + + .then(({ product }) => { + console.log(product.id); + }); + - 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 }) => { + console.log(regions.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/store/regions' + tags: + - Regions + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StoreRegionsListRes' + '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/{id}: + get: + operationId: GetRegionsRegion + summary: Get a Region + description: Retrieve a Region's details. + parameters: + - in: path + name: id + required: true + description: The ID of the Region. + 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.regions.retrieve(regionId) + + .then(({ region }) => { + console.log(region.id); + }); + - 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: Shell + label: cURL + source: | + curl '{backend_url}/store/return-reasons' + tags: + - Return Reasons + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StoreReturnReasonsListRes' + '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/{id}: + get: + operationId: GetReturnReasonsReason + summary: Get a Return Reason + description: Retrieve a Return Reason's details. + parameters: + - in: path + name: id + required: true + description: The id of the Return Reason. + 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.returnReasons.retrieve(reasonId) + + .then(({ return_reason }) => { + console.log(return_reason.id); + }); + - 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: 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: Shell + label: cURL + source: | + curl '{backend_url}/store/shipping-options' + tags: + - Shipping Options + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StoreShippingOptionsListRes' + '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/{cart_id}: + get: + operationId: GetShippingOptionsCartId + summary: List for Cart + description: Retrieve a list of Shipping Options available for a cart. + externalDocs: + description: How to implement shipping step in checkout + url: >- + https://docs.medusajs.com/modules/carts-and-checkout/storefront/implement-checkout-flow#shipping-step + parameters: + - in: path + name: cart_id + required: true + description: The ID of the Cart. + schema: + type: string + x-codegen: + method: listCartOptions + 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.listCartOptions(cartId) + + .then(({ shipping_options }) => { + console.log(shipping_options.length); + }); + - lang: Shell + label: cURL + source: | + curl '{backend_url}/store/shipping-options/{cart_id}' + tags: + - Shipping Options + responses: + '200': + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StoreCartShippingOptionsListRes' + '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/swaps: + post: + operationId: PostSwaps + summary: Create a Swap + description: > + Create a Swap for an Order. This will also create a return and associate + it with the swap. If a return shipping option is specified, the return + will automatically be fulfilled. + + To complete the swap, you must use the Complete Cart API Route passing + it the ID of the swap's cart. + + + An idempotency key will be generated if none is provided in the header + `Idempotency-Key` and added to + + the response. If an error occurs during swap creation or the request is + interrupted for any reason, the swap creation can be retried by passing + the idempotency + + key in the `Idempotency-Key` header. + externalDocs: + description: How to create a swap + url: https://docs.medusajs.com/modules/orders/storefront/create-swap + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StorePostSwapsReq' + 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.swaps.create({ + order_id, + return_items: [ + { + item_id, + quantity: 1 + } + ], + additional_items: [ + { + variant_id, + quantity: 1 + } + ] + }) + + .then(({ swap }) => { + console.log(swap.id); + }); + - lang: Shell + label: cURL + source: | + curl -X POST '{backend_url}/store/swaps' \ + -H 'Content-Type: application/json' \ + --data-raw '{ + "order_id": "{order_id}", + "return_items": [ + { + "item_id": "{item_id}", + "quantity": 1 + } + ], + "additional_items": [ + { + "variant_id": "{variant_id}", + "quantity": 1 + } + ] + }' + 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/swaps/{cart_id}: + get: + operationId: GetSwapsSwapCartId + summary: Get by Cart ID + description: Retrieve a Swap's details by the ID of its cart. + parameters: + - in: path + name: cart_id + required: true + description: The id of the 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.swaps.retrieveByCartId(cartId) + + .then(({ swap }) => { + console.log(swap.id); + }); + - 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: 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: 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 + 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 + 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: + $ref: '#/components/schemas/PaymentProvider' + fulfillment_providers: + $ref: '#/components/schemas/FulfillmentProvider' + feature_flags: + $ref: '#/components/schemas/FeatureFlagsResponse' + modules: + $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: + 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 + 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 3 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: + 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 + - 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 + 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 + 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 + properties: + 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 + 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 3 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 + 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: + $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_currency_code: + description: The 3 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 + 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 + 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 + 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 + 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 + 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 + required: + - collection + properties: + collection: + description: Product collection details. + $ref: '#/components/schemas/ProductCollection' + StoreCompleteCartRes: + type: object + 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 + 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 + required: + - payment_methods + properties: + payment_methods: + type: array + description: An array of saved payment method details. + 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 + 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 + required: + - exists + properties: + exists: + description: Whether email exists or not. + type: boolean + StoreGetProductCategoriesCategoryRes: + type: object + 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 + 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: + type: object + required: + - gift_card + properties: + gift_card: + description: Gift card details. + $ref: '#/components/schemas/GiftCard' + StoreOrderEditsRes: + type: object + 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 + 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 + required: + - provider_id + properties: + provider_id: + type: string + description: The ID of the Payment Provider. + StorePaymentCollectionsRes: + type: object + 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 + 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 + 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 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. + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + properties: + declined_reason: + type: string + description: The reason for declining the Order Edit. + StorePostPaymentCollectionsBatchSessionsAuthorizeReq: + type: object + required: + - session_ids + properties: + session_ids: + description: List of Payment Session IDs to authorize. + type: array + items: + type: string + StorePostPaymentCollectionsBatchSessionsReq: + type: object + required: + - sessions + properties: + sessions: + description: >- + An array of 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 + 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: + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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 + 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