227 lines
7.7 KiB
YAML
227 lines
7.7 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
version: 1.0.0
|
|
title: Medusa Storefront API
|
|
description: |
|
|
API reference for Medusa's Storefront endpoints. All endpoints are prefixed with `/store`.
|
|
|
|
## Authentication
|
|
|
|
To send requests as an authenticated customer, you must use the Cookie Session ID.
|
|
|
|
<!-- ReDoc-Inject: <SecurityDefinitions> -->
|
|
license:
|
|
name: MIT
|
|
url: https://github.com/medusajs/medusa/blob/master/LICENSE
|
|
tags:
|
|
- name: Auth
|
|
description: Auth endpoints that allow authorization of customers and manages their
|
|
sessions.
|
|
- name: Cart
|
|
description: Cart endpoints that allow handling carts in Medusa.
|
|
x-resourceId: cart
|
|
- name: Collection
|
|
description: Collection endpoints that allow handling collections in Medusa.
|
|
x-resourceId: product_collection
|
|
- name: Customer
|
|
description: Customer endpoints that allow handling customers in Medusa.
|
|
x-resourceId: customer
|
|
- name: Gift Card
|
|
description: Gift Card endpoints that allow handling gift cards in Medusa.
|
|
x-resourceId: gift_card
|
|
- name: Order
|
|
description: Order endpoints that allow handling orders in Medusa.
|
|
x-resourceId: order
|
|
- name: Product
|
|
description: Product endpoints that allow handling products in Medusa.
|
|
x-resourceId: product
|
|
- name: Product Variant
|
|
description: Product Variant endpoints that allow handling product variants in Medusa.
|
|
x-resourceId: product_variant
|
|
- name: Region
|
|
description: Region endpoints that allow handling regions in Medusa.
|
|
x-resourceId: region
|
|
- name: Return Reason
|
|
description: Return Reason endpoints that allow handling return reasons in Medusa.
|
|
x-resourceId: return_reason
|
|
- name: Return
|
|
description: Return endpoints that allow handling returns in Medusa.
|
|
x-resourceId: return
|
|
- name: Shipping Option
|
|
description: Shipping Option endpoints that allow handling shipping options in Medusa.
|
|
x-resourceId: shipping_option
|
|
- name: Swap
|
|
description: Swap endpoints that allow handling swaps in Medusa.
|
|
x-resourceId: swap
|
|
servers:
|
|
- url: https://api.medusa-commerce.com/store
|
|
paths: {}
|
|
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/multiple_errors"
|
|
examples:
|
|
not_allowed:
|
|
$ref: "#/components/examples/not_allowed_error"
|
|
invalid_data:
|
|
$ref: "#/components/examples/invalid_data_error"
|
|
multiple_errors:
|
|
$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:
|
|
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. |