docs: improvements to base OAS (#8835)
* docs: improve base OAS * extra new lines + design fixes
This commit is contained in:
Shahed Nasser
GitHub
@@ -128,12 +128,12 @@ const TagSection = ({ tag }: TagSectionProps) => {
|
||||
</Section>
|
||||
)}
|
||||
{tag.externalDocs && (
|
||||
<>
|
||||
Related guide:{" "}
|
||||
<p className="mt-1">
|
||||
<span className="text-medium-plus">Related guide:</span>{" "}
|
||||
<Link href={tag.externalDocs.url} target="_blank">
|
||||
{tag.externalDocs.description || "Read More"}
|
||||
</Link>
|
||||
</>
|
||||
</p>
|
||||
)}
|
||||
<Feedback
|
||||
event="survey_api-ref"
|
||||
@@ -144,6 +144,7 @@ const TagSection = ({ tag }: TagSectionProps) => {
|
||||
pathName={pathname}
|
||||
reportLink={formatReportLink(area, tag.name)}
|
||||
vertical
|
||||
question="Was this section helpful?"
|
||||
/>
|
||||
</SectionContainer>
|
||||
}
|
||||
|
||||
@@ -4,17 +4,53 @@ info:
|
||||
title: Medusa Admin API
|
||||
license:
|
||||
name: MIT
|
||||
url: https://github.com/medusajs/medusa/blob/master/LICENSE
|
||||
url: https://github.com/medusajs/medusa/blob/develop/LICENSE
|
||||
tags:
|
||||
- name: Auth
|
||||
description: >
|
||||
Auth API routes allow you to manage an admin user's authentication.
|
||||
externalDocs:
|
||||
description: Learn more about the Auth Module
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/auth
|
||||
- name: Api Keys
|
||||
description: >
|
||||
API keys can be used for authentication or resource-scoping.
|
||||
|
||||
|
||||
A secret API key can be used to authenticate admin users.
|
||||
A publishable API key can be used to scope client requests to one or more sales channels.
|
||||
|
||||
|
||||
These API routes allow admin users to manage both publishable and secret API keys.
|
||||
externalDocs:
|
||||
description: Learn more about the API Key Module
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/api-key
|
||||
- name: Campaigns
|
||||
description: >
|
||||
A campaign is a group of promotions that have the same conditions, such as start and end dates.
|
||||
|
||||
|
||||
These API routes allow admin users to manage campaigns, their conditions, and promotions that belong to them.
|
||||
externalDocs:
|
||||
description: Learn more about campaigns.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/promotion/campaign
|
||||
- name: Claims
|
||||
description: >
|
||||
An admin creates a claim for an order when a customer reports that an item is defective or incorrect.
|
||||
|
||||
|
||||
Using these API routes, admin users manage order claims, their items, and more.
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminClaim"
|
||||
externalDocs:
|
||||
description: Learn more about order claims.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/order/claim
|
||||
- name: Collections
|
||||
description: >
|
||||
A product collection organizes products into a collection for marketing purposes. For example, a summer collection.
|
||||
|
||||
|
||||
These API routes allow admin users to manage collections and the products in them.
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminCollection"
|
||||
- name: Currencies
|
||||
@@ -22,85 +58,322 @@ tags:
|
||||
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.
|
||||
|
||||
Currencies are defined by the Currency Module. 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
|
||||
description: Learn more about the Currency Module
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/currency
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminCurrency"
|
||||
- name: Customer Groups
|
||||
description: >
|
||||
Customers can be organized into groups. These groups are useful for segregation and marketing purposes.
|
||||
|
||||
|
||||
For example, you can provide different prices for specific customers by creating a price list conditioned to their
|
||||
group.
|
||||
|
||||
|
||||
These API routes allow admin users to manage groups and the customers in them.
|
||||
externalDocs:
|
||||
description: Learn more about the Customer Module
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/customer
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminCustomerGroup"
|
||||
- name: Customers
|
||||
description: >
|
||||
Customers can either be created when they register through the Store APIs,
|
||||
or created by the admin using the Admin APIs.
|
||||
|
||||
|
||||
These API routes allow admin users to manage customers in their store.
|
||||
externalDocs:
|
||||
description: How to manage customers
|
||||
url: https://docs.medusajs.com/modules/customers/admin/manage-customers
|
||||
description: Learn more about the Customer Module
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/customer
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminCustomer"
|
||||
- name: Draft Orders
|
||||
description: >
|
||||
A draft order is an order created by the admin user. This is useful for orders created offline or
|
||||
from clients other than a storefront, such as a third-party integration.
|
||||
|
||||
|
||||
These API routes allow admin users to create and manage draft orders.
|
||||
externalDocs:
|
||||
description: Learn more about the Order Module
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/order
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminOrder"
|
||||
- name: Exchanges
|
||||
description: >
|
||||
An exchange is the replacement of an item that the customer ordered with another.
|
||||
|
||||
|
||||
These API routes allow admin users t create and manage exchanges.
|
||||
externalDocs:
|
||||
description: Learn more about the order exchanges.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/order/exchange
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminExchange"
|
||||
- name: Fulfillment Providers
|
||||
description: >
|
||||
A fulfillment provider is a third-party integration or custom logic used to
|
||||
fulfill an order's items.
|
||||
|
||||
|
||||
Fulfillment providers are installed as module providers.
|
||||
externalDocs:
|
||||
description: Learn more about the fulfillment providers and how to create them.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/fulfillment-provider
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminFulfillmentProvider"
|
||||
- name: Fulfillment Sets
|
||||
description: >
|
||||
A fulfillment set is a general form or way of fulfillment, such as "shipping" or "pick up".
|
||||
|
||||
|
||||
All fulfillment-related configurations in a store are related to a fulfillment set.
|
||||
|
||||
|
||||
These API routes allow admin users to manage fulfillment sets.
|
||||
externalDocs:
|
||||
description: Learn more about fulfillment sets.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/concepts
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminFulfillmentSet"
|
||||
- name: Fulfillments
|
||||
description: >
|
||||
A fulfillment is created for items in an order, return, exchanges, or claims to deliver items to/from the customer.
|
||||
|
||||
|
||||
These API routes allow admin users to manage fulfillments.
|
||||
externalDocs:
|
||||
description: Learn more about fulfillments.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/item-fulfillment
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminFulfillment"
|
||||
- name: Inventory Items
|
||||
description: >
|
||||
An inventory item is a stock-kept product whose inventory is managed.
|
||||
|
||||
|
||||
These API routes allow admin users to manage inventory items.
|
||||
externalDocs:
|
||||
description: Learn more about inventory items.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/inventory/concepts
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminInventoryItem"
|
||||
- name: Invites
|
||||
description: >
|
||||
An admin can invite new users to manage their team. This would allow new
|
||||
An admin can invite new users to manage their team. This allows new
|
||||
users to authenticate as admins and perform admin functionalities.
|
||||
|
||||
|
||||
These API routes allow admin users to manage invites.
|
||||
externalDocs:
|
||||
description: How to manage invites
|
||||
url: https://docs.medusajs.com/modules/users/admin/manage-invites
|
||||
description: Learn more about the User Module
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/user
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminInvite"
|
||||
- name: Notifications
|
||||
description: >
|
||||
A notification informs an admin user of store changes or status changes of background tasks.
|
||||
|
||||
|
||||
These API routes allow admin users to view and manage notifications.
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminNotification"
|
||||
- name: Order Edits
|
||||
description: >
|
||||
An order edit is a change to an order's details, such as items, shipping methods, and more.
|
||||
|
||||
|
||||
Changes made by an order edit are only applied on the order once they're confirmed.
|
||||
|
||||
|
||||
The order's previous version is retained due to versioning.
|
||||
|
||||
|
||||
These API routes allow admin users to make edits to an order and manage those edits.
|
||||
externalDocs:
|
||||
description: Learn more about the Order Module
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/order
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/OrderChange"
|
||||
- name: Orders
|
||||
description: >
|
||||
An order is a purchase made by a customer through a storefront.
|
||||
|
||||
|
||||
Orders can also originally be created as draft orders.
|
||||
|
||||
|
||||
These API routes allow admin users to view and manage orders.
|
||||
externalDocs:
|
||||
description: Learn more about the orders
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/order/concepts
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminOrder"
|
||||
- name: Payment Collections
|
||||
description: >
|
||||
A payment collection is one or more payments of an order. They're also used for outstanding payments due to
|
||||
order exchanges or claims.
|
||||
|
||||
|
||||
Every purchase or request for payment starts with a payment collection.
|
||||
|
||||
|
||||
A payment collection holds the payment sessions used to authorize the payment amount, and the payments to be
|
||||
captured / refunded.
|
||||
|
||||
|
||||
These API routes allow admin users to manage payment collections.
|
||||
externalDocs:
|
||||
description: Learn more about payment collections.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/payment/payment-collection
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminPaymentCollection"
|
||||
- name: Payments
|
||||
description: >
|
||||
A payment is created when a payment amount is authorized. The payment can then be captured or refunded.
|
||||
|
||||
|
||||
A payment is created from the payment session that was authorized, and it belongs to the payment session's collection.
|
||||
|
||||
|
||||
These API routes allow admin users to manage payments.
|
||||
externalDocs:
|
||||
description: Learn more about payments.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/payment/payment
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminPayment"
|
||||
- name: Price Lists
|
||||
description: >
|
||||
A price list is a group of prices applied if the specified conditions and rules are satisfied.
|
||||
|
||||
|
||||
Price lists are useful for sales or special prices for special conditions, such as applying prices for a set of customers.
|
||||
|
||||
|
||||
These API routes allow admin users to manage price lists.
|
||||
externalDocs:
|
||||
description: Learn more about price lists.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/pricing/concepts#price-list
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminPriceList"
|
||||
- name: Price Preferences
|
||||
description: >
|
||||
A price preference is used to specify whether tax-inclusiveness is enabled for a context, such as a region or currency code.
|
||||
|
||||
|
||||
These API routes allow admin users to manage whether a region or currency is tax inclusive.
|
||||
externalDocs:
|
||||
description: Learn more about tax-inclusiveness and the role of a price preference.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/pricing/tax-inclusive-pricing
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminPricePreference"
|
||||
- name: Product Categories
|
||||
description: >
|
||||
Products can be categorized into categories.
|
||||
|
||||
|
||||
Categories are nested and their heirarchy can be managed, giving admin users flexibility in how they categorize
|
||||
their products.
|
||||
|
||||
|
||||
These API routes allow admin users to manage categories and the products in them.
|
||||
externalDocs:
|
||||
description: Learn more about the Product Module
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/product
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminProductCategory"
|
||||
- name: Product Tags
|
||||
description: >
|
||||
A tag is another way of organizing a product. Each tag has a name and a value.
|
||||
|
||||
|
||||
Products are organized into the same tag if they have the same value.
|
||||
|
||||
|
||||
These API routes allow admin users to manage product tags.
|
||||
externalDocs:
|
||||
description: Learn more about the Product Module
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/product
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminProductTag"
|
||||
- name: Product Types
|
||||
description: >
|
||||
Products can be organized into types. Each type has a name and a value.
|
||||
|
||||
|
||||
Products are organized into the same type if they have the same value.
|
||||
|
||||
|
||||
These API routes allow admin users to manage product types.
|
||||
externalDocs:
|
||||
description: Learn more about the Product Module
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/product
|
||||
- name: Product Variants
|
||||
description: >
|
||||
A product variant is a saleable form of the product.
|
||||
|
||||
|
||||
Each variant has different option values. For example, a "Shirt" product may have a
|
||||
"Blue" variant and a "Green" variant. Customers choose from these variants when they buy
|
||||
the product.
|
||||
|
||||
|
||||
These API routes allow admin users to manage product variants.
|
||||
externalDocs:
|
||||
description: Learn more about the Product Module
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/product
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminProductVariant"
|
||||
- name: Products
|
||||
description: >
|
||||
A product is a set of variants that the customer chooses from when making a purchase.
|
||||
|
||||
|
||||
A product can be organized into categories or collections.
|
||||
|
||||
|
||||
A product can have many options, and variants for each of these options' values.
|
||||
|
||||
|
||||
These API routes allow admin users to manage products.
|
||||
externalDocs:
|
||||
description: Learn more about the Product Module
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/product
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminProduct"
|
||||
- name: Promotions
|
||||
description: >
|
||||
A promotion discounts an amount or percentage off a cart's items, shipping methods, or the entire order.
|
||||
|
||||
|
||||
Promotions have different types, such as a `standard` promotion that just discounts an amount, or a `buyget`
|
||||
promotion to enforce a "buy X get Y" promotion.
|
||||
|
||||
|
||||
A promotion has rules to restrict how and when they're applied.
|
||||
|
||||
|
||||
Promotions belong to a campaign, which sets conditions on the promotion such as when it starts and ends.
|
||||
|
||||
|
||||
These API routes allow admin users to manage promotions.
|
||||
externalDocs:
|
||||
description: Learn more about promotions.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/promotion/concepts
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminPromotion"
|
||||
- name: Refund Reasons
|
||||
description: >
|
||||
A refund reason is a possible reason used when issuing a refund to the customer, such as when returning an item
|
||||
and refunding the customer.
|
||||
|
||||
|
||||
These API routes allow admin users to manage refund reasons.
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminRefundReason"
|
||||
- name: Regions
|
||||
@@ -108,17 +381,48 @@ tags:
|
||||
Regions are different countries or geographical regions that the commerce
|
||||
store serves customers in.
|
||||
|
||||
Admins can manage these regions, their providers, and more.
|
||||
|
||||
These API routes allow admin users to manage regions, their providers, and more.
|
||||
externalDocs:
|
||||
description: How to manage regions
|
||||
url: https://docs.medusajs.com/modules/regions-and-currencies/admin/manage-regions
|
||||
description: Learn more about the Region Module.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/region
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminRegion"
|
||||
- name: Reservations
|
||||
description: >
|
||||
A reservation is unavailable quantity of an inventory item in a location.
|
||||
|
||||
|
||||
A reservation is created automatically for variants in an order whose `manage_inventory` is enabled.
|
||||
Admin users can also create reservations manually.
|
||||
|
||||
|
||||
These API routes allow admin users to manage reservations.
|
||||
externalDocs:
|
||||
description: Learn more about reservations and other inventory concepts.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/inventory/concepts
|
||||
- name: Return Reasons
|
||||
description: >
|
||||
A return reason is a possible reason that an item is returned from the customer, such as when returning an item.
|
||||
|
||||
|
||||
These API routes allow admin users to manage return reasons.
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminReturnReason"
|
||||
- name: Returns
|
||||
description: >
|
||||
Admin users create a return when a customer returns an item to them.
|
||||
|
||||
|
||||
Returns can also be created by customers through the storefront, and admins will
|
||||
be able to manage them and make refunds, if necessary. Refunds are made
|
||||
through the [Payment API Routes](#payment)
|
||||
|
||||
|
||||
These API routes allow admin users to manage returns.
|
||||
externalDocs:
|
||||
description: Learn more about order returns.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/order/return
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminReturn"
|
||||
- name: Sales Channels
|
||||
@@ -126,38 +430,146 @@ tags:
|
||||
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.
|
||||
|
||||
These API routes allow admins to 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
|
||||
description: Learn more about the Sales Channel Module.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/sales-channel
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminSalesChannel"
|
||||
- name: Shipping Options
|
||||
description: >
|
||||
A shipping option is a way of shipping an item to or from the customer.
|
||||
|
||||
|
||||
Shipping options are associated with the fulfillment provider used to handle their fulfillment.
|
||||
|
||||
|
||||
Shipping options can be restricted geographically by service zones, and by custom rules, such as an item's
|
||||
weight or the customer's group.
|
||||
|
||||
|
||||
These API routes allow admins to manage shipping options.
|
||||
externalDocs:
|
||||
description: Learn more about shipping options.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/shipping-option
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminShippingOption"
|
||||
- name: Shipping Profiles
|
||||
description: >
|
||||
A shipping profile defines a type of items that are shipping in a similar manner. For example,
|
||||
digital products may have a `digital` shipping profile.
|
||||
|
||||
|
||||
These API routes allow admin users to manage shipping profiles.
|
||||
externalDocs:
|
||||
description: Learn more about shipping profiles and other fulfillment concepts.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/concepts#shipping-profile
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminShippingProfile"
|
||||
- name: Stock Locations
|
||||
description: >
|
||||
A stock location is where stock-kept items (products) are kept.
|
||||
|
||||
|
||||
Stock locations are linked to fulfillment providers used to fulfill items from this location.
|
||||
|
||||
|
||||
A stock location is also link to a fulfillment set, indicating where an item is fulfilled from
|
||||
when an order is placed.
|
||||
|
||||
|
||||
These API routes allow admin users to manage stock locations and their linked data.
|
||||
externalDocs:
|
||||
description: Learn more about stock locations.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/stock-location/concepts
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminStockLocation"
|
||||
- name: Stores
|
||||
description: >
|
||||
A store holds the main configuration and information of your commerce store, such as supported currencies or default sales channel.
|
||||
|
||||
|
||||
By default, the Medusa application has one default store. There are no API routes to create more stores. Instead, you'd have
|
||||
to handle that customization manually.
|
||||
|
||||
|
||||
These API routes allow admin users to manage their store.
|
||||
externalDocs:
|
||||
description: Learn more about the Store Module.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/store
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminStore"
|
||||
- name: Tax Rates
|
||||
description: >
|
||||
A tax rate is a percentage amount used to calculate the tax amount of each taxable item's price, such as line items or shipping methods.
|
||||
|
||||
|
||||
Each tax region has a default tax rate. You can create tax rates that override the default using tax rules.
|
||||
|
||||
|
||||
These API routes allow admin users to manage tax rates and their rules.
|
||||
externalDocs:
|
||||
description: Learn more about tax rates and rules.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/tax/tax-rates-and-rules
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminTaxRate"
|
||||
- name: Tax Regions
|
||||
description: >
|
||||
A tax region is a region's tax settings. It has tax rates and rules. So, after you create a region,
|
||||
you must create a tax region for it.
|
||||
|
||||
|
||||
A tax region can extend settings from a parent tax region.
|
||||
|
||||
|
||||
These API routes allow admin users to manage tax regions.
|
||||
externalDocs:
|
||||
description: Learn more about tax regions.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/tax/tax-region
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminTaxRegion"
|
||||
- name: Uploads
|
||||
description: >
|
||||
Use these API routes to upload files to your Medusa application using the installed file module provider.
|
||||
|
||||
|
||||
You can upload public files, such as product images, or private files, such as CSV files used to import products.
|
||||
externalDocs:
|
||||
description: Check out available file module providers.
|
||||
url: https://docs.medusajs.com/v2/resources/architectural-modules/file
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminFile"
|
||||
- name: Users
|
||||
description: >
|
||||
A user is an admin user that can authenticate and perform functionalities as an admin user.
|
||||
|
||||
|
||||
An admin user can invite other users to join their team. Once they accept the invite, they'll
|
||||
become admin users as well.
|
||||
|
||||
|
||||
These API routes allow admin users to manage their team.
|
||||
externalDocs:
|
||||
description: Learn more about the User Module.
|
||||
url: https://docs.medusajs.com/v2/resources/commerce-modules/user
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminUser"
|
||||
- name: Workflows Executions
|
||||
description: >
|
||||
These API routes allow you to track workflow executions in your Medusa application.
|
||||
|
||||
|
||||
Depending on the workflow engine you use, executions may only be retained for a short while, or
|
||||
only until the Medusa application is restarted.
|
||||
externalDocs:
|
||||
description: Check out available Workflow Engine Modules
|
||||
url: https://docs.medusajs.com/v2/resources/architectural-modules/workflow-engine
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/AdminWorkflowExecution"
|
||||
servers:
|
||||
- url: http://localhost:9000
|
||||
- url: https://api.medusa-commerce.com
|
||||
- url: https://api.medusajs.com
|
||||
paths: {}
|
||||
components:
|
||||
schemas:
|
||||
|
||||
@@ -9,42 +9,123 @@ tags:
|
||||
- name: Auth
|
||||
description: >
|
||||
Auth API routes allow you to manage a customer's authentication.
|
||||
externalDocs:
|
||||
description: How to register a customer in a storefront.
|
||||
url: https://docs.medusajs.com/v2/resources/storefront-development/customers/register
|
||||
- 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.
|
||||
|
||||
|
||||
These API routes allow customers to create and manage their cart, 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
|
||||
description: How to implement cart functionality in a storefront.
|
||||
url: https://docs.medusajs.com/v2/resources/storefront-development/cart
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/StoreCart"
|
||||
- name: Collections
|
||||
description: >
|
||||
A product collection organizes products into a collection for marketing purposes. For example, a summer collection.
|
||||
|
||||
|
||||
These API routes allow customers to browse collections and their products.
|
||||
externalDocs:
|
||||
description: How to list product collections in a storefront.
|
||||
url: https://docs.medusajs.com/v2/resources/storefront-development/products/collections/list
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/StoreCollection"
|
||||
- name: Currencies
|
||||
description: >
|
||||
A store has multiple currencies, and product prices can be different for each currency.
|
||||
|
||||
|
||||
When retrieving product variant prices, you specify either the ID of a region or a currency that the customer selected.
|
||||
|
||||
|
||||
These API routes allow customers to browse currencies.
|
||||
externalDocs:
|
||||
description: How to retrieve product variant prices in a storefront.
|
||||
url: https://docs.medusajs.com/v2/resources/storefront-development/products/price
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/StoreCurrency"
|
||||
- name: Customers
|
||||
description: >
|
||||
Customers can place orders as guest customers or register.
|
||||
|
||||
|
||||
When a customer registers, they can manage their profile, save addresses for later usage, and more.
|
||||
|
||||
|
||||
These API routes allow customers to create and manage their accounts.
|
||||
externalDocs:
|
||||
description: How to implement customer account functionalities in a storefront.
|
||||
url: https://docs.medusajs.com/v2/resources/storefront-development/customers
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/StoreCustomer"
|
||||
- name: Orders
|
||||
description: >
|
||||
Guest and registered customers can view orders they placed.
|
||||
|
||||
|
||||
These API routes allow customers to view their orders.
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/StoreOrder"
|
||||
- name: Payment Collections
|
||||
description: >
|
||||
A payment collection is useful for managing additional payments, such as
|
||||
for Order Edits, or installment payments.
|
||||
A cart must have a payment collection with an authorized payment session.
|
||||
|
||||
|
||||
Use these API routes during checkout to set the cart's payment provider and authorize its
|
||||
payment session.
|
||||
externalDocs:
|
||||
description: How to implement payment during checkout.
|
||||
url: https://docs.medusajs.com/v2/resources/storefront-development/checkout/payment
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/StorePaymentCollection"
|
||||
- name: Payment Providers
|
||||
description: >
|
||||
Each region has a set of payment providers enabled.
|
||||
|
||||
|
||||
During checkout, you retrieve the available payment providers in the customer's region to
|
||||
show them to the customer. Customers then choose their preferred provider to authorize their
|
||||
payment and place their order.
|
||||
|
||||
|
||||
These API routes allow customers to view available payment providers in their region.
|
||||
externalDocs:
|
||||
description: How to implement payment during checkout.
|
||||
url: https://docs.medusajs.com/v2/resources/storefront-development/checkout/payment
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/StorePaymentProvider"
|
||||
- name: Product Categories
|
||||
description: >
|
||||
Products can be categorized into categories.
|
||||
|
||||
|
||||
These API routes allow customers to browse categories and their products.
|
||||
externalDocs:
|
||||
description: How to list product categories in a storefront.
|
||||
url: https://docs.medusajs.com/v2/resources/storefront-development/products/categories/list
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/StoreProductCategory"
|
||||
- name: Products
|
||||
description: >
|
||||
Customers browse products for their purchase.
|
||||
|
||||
|
||||
A product has variants for different option values. The customer chooses from these variants
|
||||
before adding it to the cart.
|
||||
|
||||
|
||||
These API routes allow customers to browse products.
|
||||
externalDocs:
|
||||
description: How to list products, get their prices, and more in a storefront.
|
||||
url: https://docs.medusajs.com/v2/resources/storefront-development/products
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/StoreProduct"
|
||||
- name: Regions
|
||||
@@ -52,24 +133,50 @@ tags:
|
||||
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.
|
||||
|
||||
Customers can choose what region they're in to view prices of that region's currency.
|
||||
|
||||
|
||||
Use these API routes to retrieve available regions in the store.
|
||||
externalDocs:
|
||||
description: How to use regions in a storefront
|
||||
url: https://docs.medusajs.com/modules/regions-and-currencies/storefront/use-regions
|
||||
description: How to retrieve and store selected region in a storefront.
|
||||
url: https://docs.medusajs.com/v2/resources/storefront-development/regions
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/StoreRegion"
|
||||
- name: Return
|
||||
description: >
|
||||
Customers can request to return items in their order. The admin user then receives and handles the return.
|
||||
|
||||
|
||||
These API routes allows customers to create a return.
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/StoreReturn"
|
||||
- name: Return Reasons
|
||||
description: >
|
||||
A return reason is a possible reason a customer wants to return an item.
|
||||
|
||||
|
||||
Use these API routes when implementing return creation flow in your storefront to allow customers to
|
||||
select their return reason.
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/StoreReturnReason"
|
||||
- name: Shipping Options
|
||||
description: >
|
||||
A shipping option is a way of shipping an item to or from the customer.
|
||||
|
||||
|
||||
During the checkout flow, the customer selects their preferred shipping option to receive their order.
|
||||
|
||||
|
||||
These API routes allow customers to retrieve available shipping options for their context.
|
||||
externalDocs:
|
||||
description: How to implement shipping during checkout.
|
||||
url: https://docs.medusajs.com/v2/resources/storefront-development/checkout/shipping
|
||||
x-associatedSchema:
|
||||
$ref: "#/components/schemas/StoreShippingOption"
|
||||
servers:
|
||||
- url: http://localhost:9000
|
||||
- url: https://api.medusa-commerce.com
|
||||
- url: https://api.medusajs.com
|
||||
paths: {}
|
||||
components:
|
||||
schemas:
|
||||
@@ -242,57 +349,4 @@ components:
|
||||
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.
|
||||
name: connect.sid
|
||||
Reference in New Issue
Block a user