chore(docs): Updated API Reference (v2) (#8870)
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]
committed by
GitHub
GitHub
parent
9290ce88bf
commit
4e6e81f445
@@ -7,48 +7,138 @@ info:
|
||||
url: https://github.com/medusajs/medusa/blob/master/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 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.yaml
|
||||
- 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.yaml
|
||||
- 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.yaml
|
||||
- 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.yaml
|
||||
- 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.yaml
|
||||
- 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.yaml
|
||||
- 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.yaml
|
||||
- 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.yaml
|
||||
- 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.yaml
|
||||
- name: Regions
|
||||
@@ -56,21 +146,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.yaml
|
||||
- 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.yaml
|
||||
- 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.yaml
|
||||
- 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.yaml
|
||||
paths:
|
||||
@@ -155,64 +274,3 @@ components:
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user