asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

chore(docs): Updated API Reference (v2) (#8870)

Browse Source 
Automated changes by [create-pull-request](https://github.com/peter-evans/create-pull-request) GitHub action

Co-authored-by: Oli Juhl <59018053+olivermrbl@users.noreply.github.com>
This commit is contained in:
github-actions[bot]
2024-08-29 13:05:50 +00:00
committed by GitHub
parent 9290ce88bf
commit 4e6e81f445
4 changed files with 1049 additions and 149 deletions
Download Patch File Download Diff File Expand all files Collapse all files

508
www/apps/api-reference/specs/admin/openapi.yaml
View File

@@ -4,20 +4,65 @@ 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
servers:
- url: http://localhost:9000
- url: https://api.medusa-commerce.com
- url: https://api.medusajs.com
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.yaml
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.yaml
- name: Currencies
@@ -25,87 +70,350 @@ 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.
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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- name: Regions
@@ -113,18 +421,52 @@ 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.yaml
- 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.yaml
- 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.yaml
- name: Sales Channels
@@ -132,35 +474,161 @@ 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
- 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.yaml
paths:
/admin/api-keys:
$ref: paths/admin_api-keys.yaml