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
www/apps/api-reference/specs/store/openapi.full.yaml
+92 -41
View File
@@ -7,62 +7,147 @@ 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'
- 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
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.
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'
paths:
@@ -25856,37 +25941,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.
www/apps/api-reference/specs/store/openapi.yaml
+130 -72
View File
@@ -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.