507 lines
16 KiB
YAML
507 lines
16 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
version: 1.0.0
|
|
title: Medusa Admin API
|
|
description: >
|
|
API reference for Medusa's Admin endpoints. All endpoints are prefixed with
|
|
`/admin`.
|
|
|
|
|
|
## Authentication
|
|
|
|
|
|
There are two ways to send authenticated requests to the Medusa server:
|
|
Using a user's API token, or using a 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 admin Users and manages their
|
|
sessions.
|
|
- name: App
|
|
description: App endpoints that allow handling apps in Medusa.
|
|
x-resourceId: OAuth
|
|
- name: Batch Job
|
|
description: Batch Job endpoints that allow handling batch jobs in Medusa.
|
|
x-resourceId: batch_job
|
|
- name: Claim
|
|
description: Claim endpoints that allow handling claims in Medusa.
|
|
x-resourceId: claim_order
|
|
- 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: Customer Group
|
|
description: Customer Group endpoints that allow handling customer groups in Medusa.
|
|
x-resourceId: customer_group
|
|
- name: Discount
|
|
description: Discount endpoints that allow handling discounts in Medusa.
|
|
x-resourceId: discount
|
|
- name: Discount Condition
|
|
description: >-
|
|
Discount Condition endpoints that allow handling discount conditions in
|
|
Medusa.
|
|
x-resourceId: discount_condition
|
|
- name: Draft Order
|
|
description: Draft Order endpoints that allow handling draft orders in Medusa.
|
|
x-resourceId: draft-order
|
|
- name: Gift Card
|
|
description: Gift Card endpoints that allow handling gift cards in Medusa.
|
|
x-resourceId: gift_card
|
|
- name: Invite
|
|
description: Invite endpoints that allow handling invites in Medusa.
|
|
x-resourceId: invite
|
|
- name: Note
|
|
description: Note endpoints that allow handling notes in Medusa.
|
|
x-resourceId: note
|
|
- name: Notification
|
|
description: Notification endpoints that allow handling notifications in Medusa.
|
|
x-resourceId: notification
|
|
- name: Order
|
|
description: Order endpoints that allow handling orders in Medusa.
|
|
x-resourceId: order
|
|
- name: Price List
|
|
description: Price List endpoints that allow handling price lists in Medusa.
|
|
x-resourceId: price_list
|
|
- name: Product
|
|
description: Product endpoints that allow handling products in Medusa.
|
|
x-resourceId: product
|
|
- name: Product Tag
|
|
description: Product Tag endpoints that allow handling product tags in Medusa.
|
|
x-resourceId: product_tag
|
|
- name: Product Type
|
|
description: Product Types endpoints that allow handling product types in Medusa.
|
|
x-resourceId: product_type
|
|
- 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: Sales Channel
|
|
description: Sales Channel endpoints that allow handling sales channels in Medusa.
|
|
x-resourceId: sales_channel
|
|
- name: Shipping Option
|
|
description: Shipping Option endpoints that allow handling shipping options in Medusa.
|
|
x-resourceId: shipping_option
|
|
- name: Shipping Profile
|
|
description: >-
|
|
Shipping Profile endpoints that allow handling shipping profiles in
|
|
Medusa.
|
|
x-resourceId: shipping_profile
|
|
- name: Store
|
|
description: Store endpoints that allow handling stores in Medusa.
|
|
x-resourceId: store
|
|
- name: Swap
|
|
description: Swap endpoints that allow handling swaps in Medusa.
|
|
x-resourceId: swap
|
|
- name: Tax Rate
|
|
description: Tax Rate endpoints that allow handling tax rates in Medusa.
|
|
x-resourceId: tax_rate
|
|
- name: Upload
|
|
description: Upload endpoints that allow handling uploads in Medusa.
|
|
- name: User
|
|
description: User endpoints that allow handling users in Medusa.
|
|
x-resourceId: user
|
|
servers:
|
|
- url: https://api.medusa-commerce.com/admin
|
|
paths:
|
|
/apps/authorizations:
|
|
$ref: paths/apps_authorizations.yaml
|
|
/apps:
|
|
$ref: paths/apps.yaml
|
|
/auth:
|
|
$ref: paths/auth.yaml
|
|
/batch-jobs/{id}/cancel:
|
|
$ref: paths/batch-jobs_{id}_cancel.yaml
|
|
/batch-jobs/{id}/confirm:
|
|
$ref: paths/batch-jobs_{id}_confirm.yaml
|
|
/batch-jobs:
|
|
$ref: paths/batch-jobs.yaml
|
|
/batch-jobs/{id}:
|
|
$ref: paths/batch-jobs_{id}.yaml
|
|
/collections/{id}/products/batch:
|
|
$ref: paths/collections_{id}_products_batch.yaml
|
|
/collections:
|
|
$ref: paths/collections.yaml
|
|
/collections/{id}:
|
|
$ref: paths/collections_{id}.yaml
|
|
/currencies:
|
|
$ref: paths/currencies.yaml
|
|
/currencies/{code}:
|
|
$ref: paths/currencies_{code}.yaml
|
|
/customer-groups/{id}/customers/batch:
|
|
$ref: paths/customer-groups_{id}_customers_batch.yaml
|
|
/customer-groups:
|
|
$ref: paths/customer-groups.yaml
|
|
/customer-groups/{id}:
|
|
$ref: paths/customer-groups_{id}.yaml
|
|
/customer-groups/{id}/customers:
|
|
$ref: paths/customer-groups_{id}_customers.yaml
|
|
/customers:
|
|
$ref: paths/customers.yaml
|
|
/customers/{id}:
|
|
$ref: paths/customers_{id}.yaml
|
|
/discounts/{id}/regions/{region_id}:
|
|
$ref: paths/discounts_{id}_regions_{region_id}.yaml
|
|
/discounts/{discount_id}/conditions:
|
|
$ref: paths/discounts_{discount_id}_conditions.yaml
|
|
/discounts:
|
|
$ref: paths/discounts.yaml
|
|
/discounts/{id}/dynamic-codes:
|
|
$ref: paths/discounts_{id}_dynamic-codes.yaml
|
|
/discounts/{discount_id}/conditions/{condition_id}:
|
|
$ref: paths/discounts_{discount_id}_conditions_{condition_id}.yaml
|
|
/discounts/{id}:
|
|
$ref: paths/discounts_{id}.yaml
|
|
/discounts/{id}/dynamic-codes/{code}:
|
|
$ref: paths/discounts_{id}_dynamic-codes_{code}.yaml
|
|
/discounts/code/{code}:
|
|
$ref: paths/discounts_code_{code}.yaml
|
|
/draft-orders:
|
|
$ref: paths/draft-orders.yaml
|
|
/draft-orders/{id}/line-items:
|
|
$ref: paths/draft-orders_{id}_line-items.yaml
|
|
/draft-orders/{id}:
|
|
$ref: paths/draft-orders_{id}.yaml
|
|
/draft-orders/{id}/line-items/{line_id}:
|
|
$ref: paths/draft-orders_{id}_line-items_{line_id}.yaml
|
|
/draft-orders/{id}/pay:
|
|
$ref: paths/draft-orders_{id}_pay.yaml
|
|
/admin/draft-orders/{id}:
|
|
$ref: paths/admin_draft-orders_{id}.yaml
|
|
/gift-cards:
|
|
$ref: paths/gift-cards.yaml
|
|
/gift-cards/{id}:
|
|
$ref: paths/gift-cards_{id}.yaml
|
|
/invites/accept:
|
|
$ref: paths/invites_accept.yaml
|
|
/invites:
|
|
$ref: paths/invites.yaml
|
|
/invites/{invite_id}:
|
|
$ref: paths/invites_{invite_id}.yaml
|
|
/invites/{invite_id}/resend:
|
|
$ref: paths/invites_{invite_id}_resend.yaml
|
|
/notes:
|
|
$ref: paths/notes.yaml
|
|
/notes/{id}:
|
|
$ref: paths/notes_{id}.yaml
|
|
/notifications:
|
|
$ref: paths/notifications.yaml
|
|
/notifications/{id}/resend:
|
|
$ref: paths/notifications_{id}_resend.yaml
|
|
/orders/{id}/shipping-methods:
|
|
$ref: paths/orders_{id}_shipping-methods.yaml
|
|
/orders/{id}/archive:
|
|
$ref: paths/orders_{id}_archive.yaml
|
|
/orders/{id}/claims/{claim_id}/cancel:
|
|
$ref: paths/orders_{id}_claims_{claim_id}_cancel.yaml
|
|
/orders/{id}/claims/{claim_id}/fulfillments/{fulfillment_id}/cancel:
|
|
$ref: >-
|
|
paths/orders_{id}_claims_{claim_id}_fulfillments_{fulfillment_id}_cancel.yaml
|
|
/orders/{id}/swaps/{swap_id}/fulfillments/{fulfillment_id}/cancel:
|
|
$ref: >-
|
|
paths/orders_{id}_swaps_{swap_id}_fulfillments_{fulfillment_id}_cancel.yaml
|
|
/orders/{id}/fulfillments/{fulfillment_id}/cancel:
|
|
$ref: paths/orders_{id}_fulfillments_{fulfillment_id}_cancel.yaml
|
|
/orders/{id}/cancel:
|
|
$ref: paths/orders_{id}_cancel.yaml
|
|
/orders/{id}/swaps/{swap_id}/cancel:
|
|
$ref: paths/orders_{id}_swaps_{swap_id}_cancel.yaml
|
|
/orders/{id}/capture:
|
|
$ref: paths/orders_{id}_capture.yaml
|
|
/orders/{id}/complete:
|
|
$ref: paths/orders_{id}_complete.yaml
|
|
/orders/{id}/claims/{claim_id}/shipments:
|
|
$ref: paths/orders_{id}_claims_{claim_id}_shipments.yaml
|
|
/order/{id}/claims:
|
|
$ref: paths/order_{id}_claims.yaml
|
|
/orders/{id}/fulfillment:
|
|
$ref: paths/orders_{id}_fulfillment.yaml
|
|
/orders/{id}/shipment:
|
|
$ref: paths/orders_{id}_shipment.yaml
|
|
/orders/{id}/swaps/{swap_id}/shipments:
|
|
$ref: paths/orders_{id}_swaps_{swap_id}_shipments.yaml
|
|
/order/{id}/swaps:
|
|
$ref: paths/order_{id}_swaps.yaml
|
|
/orders/{id}/claims/{claim_id}/fulfillments:
|
|
$ref: paths/orders_{id}_claims_{claim_id}_fulfillments.yaml
|
|
/orders/{id}/swaps/{swap_id}/fulfillments:
|
|
$ref: paths/orders_{id}_swaps_{swap_id}_fulfillments.yaml
|
|
/orders/{id}:
|
|
$ref: paths/orders_{id}.yaml
|
|
/orders:
|
|
$ref: paths/orders.yaml
|
|
/orders/{id}/swaps/{swap_id}/process-payment:
|
|
$ref: paths/orders_{id}_swaps_{swap_id}_process-payment.yaml
|
|
/orders/{id}/refund:
|
|
$ref: paths/orders_{id}_refund.yaml
|
|
/orders/{id}/return:
|
|
$ref: paths/orders_{id}_return.yaml
|
|
/order/{id}/claims/{claim_id}:
|
|
$ref: paths/order_{id}_claims_{claim_id}.yaml
|
|
/price-lists/{id}/prices/batch:
|
|
$ref: paths/price-lists_{id}_prices_batch.yaml
|
|
/price-lists:
|
|
$ref: paths/price-lists.yaml
|
|
/price-lists/{id}:
|
|
$ref: paths/price-lists_{id}.yaml
|
|
/price-lists/{id}/products/{product_id}/prices:
|
|
$ref: paths/price-lists_{id}_products_{product_id}_prices.yaml
|
|
/price-lists/{id}/variants/{variant_id}/prices:
|
|
$ref: paths/price-lists_{id}_variants_{variant_id}_prices.yaml
|
|
/price-lists/{id}/products:
|
|
$ref: paths/price-lists_{id}_products.yaml
|
|
/product-tags:
|
|
$ref: paths/product-tags.yaml
|
|
/product-types:
|
|
$ref: paths/product-types.yaml
|
|
/products/{id}/options:
|
|
$ref: paths/products_{id}_options.yaml
|
|
/products:
|
|
$ref: paths/products.yaml
|
|
/products/{id}/variants:
|
|
$ref: paths/products_{id}_variants.yaml
|
|
/products/{id}/options/{option_id}:
|
|
$ref: paths/products_{id}_options_{option_id}.yaml
|
|
/products/{id}:
|
|
$ref: paths/products_{id}.yaml
|
|
/products/{id}/variants/{variant_id}:
|
|
$ref: paths/products_{id}_variants_{variant_id}.yaml
|
|
/products/tag-usage:
|
|
$ref: paths/products_tag-usage.yaml
|
|
/products/types:
|
|
$ref: paths/products_types.yaml
|
|
/products/{id}/metadata:
|
|
$ref: paths/products_{id}_metadata.yaml
|
|
/regions/{id}/countries:
|
|
$ref: paths/regions_{id}_countries.yaml
|
|
/regions/{id}/fulfillment-providers:
|
|
$ref: paths/regions_{id}_fulfillment-providers.yaml
|
|
/regions/{id}/payment-providers:
|
|
$ref: paths/regions_{id}_payment-providers.yaml
|
|
/regions:
|
|
$ref: paths/regions.yaml
|
|
/regions/{id}:
|
|
$ref: paths/regions_{id}.yaml
|
|
/regions/{id}/fulfillment-options:
|
|
$ref: paths/regions_{id}_fulfillment-options.yaml
|
|
/regions/{id}/countries/{country_code}:
|
|
$ref: paths/regions_{id}_countries_{country_code}.yaml
|
|
/regions/{id}/fulfillment-providers/{provider_id}:
|
|
$ref: paths/regions_{id}_fulfillment-providers_{provider_id}.yaml
|
|
/regions/{id}/payment-providers/{provider_id}:
|
|
$ref: paths/regions_{id}_payment-providers_{provider_id}.yaml
|
|
/return-reasons:
|
|
$ref: paths/return-reasons.yaml
|
|
/return-reasons/{id}:
|
|
$ref: paths/return-reasons_{id}.yaml
|
|
/returns/{id}/cancel:
|
|
$ref: paths/returns_{id}_cancel.yaml
|
|
/returns:
|
|
$ref: paths/returns.yaml
|
|
/returns/{id}/receive:
|
|
$ref: paths/returns_{id}_receive.yaml
|
|
/sales-channels/{id}/products/batch:
|
|
$ref: paths/sales-channels_{id}_products_batch.yaml
|
|
/sales-channels:
|
|
$ref: paths/sales-channels.yaml
|
|
/sales-channels/{id}:
|
|
$ref: paths/sales-channels_{id}.yaml
|
|
/shipping-options:
|
|
$ref: paths/shipping-options.yaml
|
|
/shipping-options/{id}:
|
|
$ref: paths/shipping-options_{id}.yaml
|
|
/shipping-profiles:
|
|
$ref: paths/shipping-profiles.yaml
|
|
/shipping-profiles/{id}:
|
|
$ref: paths/shipping-profiles_{id}.yaml
|
|
/store/currencies/{code}:
|
|
$ref: paths/store_currencies_{code}.yaml
|
|
/store:
|
|
$ref: paths/store.yaml
|
|
/store/payment-providers:
|
|
$ref: paths/store_payment-providers.yaml
|
|
/store/tax-providers:
|
|
$ref: paths/store_tax-providers.yaml
|
|
/swaps/{id}:
|
|
$ref: paths/swaps_{id}.yaml
|
|
/swaps:
|
|
$ref: paths/swaps.yaml
|
|
/tax-rates/{id}/product-types/batch:
|
|
$ref: paths/tax-rates_{id}_product-types_batch.yaml
|
|
/tax-rates/{id}/products/batch:
|
|
$ref: paths/tax-rates_{id}_products_batch.yaml
|
|
/tax-rates/{id}/shipping-options/batch:
|
|
$ref: paths/tax-rates_{id}_shipping-options_batch.yaml
|
|
/tax-rates:
|
|
$ref: paths/tax-rates.yaml
|
|
/tax-rates/{id}:
|
|
$ref: paths/tax-rates_{id}.yaml
|
|
/uploads:
|
|
$ref: paths/uploads.yaml
|
|
/users:
|
|
$ref: paths/users.yaml
|
|
/users/{id}:
|
|
$ref: paths/users_{id}.yaml
|
|
/users/password-token:
|
|
$ref: paths/users_password-token.yaml
|
|
/users/reset-password:
|
|
$ref: paths/users_reset-password.yaml
|
|
/variants:
|
|
$ref: paths/variants.yaml
|
|
components:
|
|
securitySchemes:
|
|
api_token:
|
|
type: http
|
|
x-displayName: API Token
|
|
description: >
|
|
Use a user's API Token to send authenticated requests.
|
|
|
|
|
|
### How to Add API Token to a User
|
|
|
|
|
|
At the moment, there's no direct way of adding an API Token for a user.
|
|
The only way it can be done is through directly editing the database.
|
|
|
|
|
|
If you're using a PostgreSQL database, you can run the following
|
|
commands in your command line to add API token:
|
|
|
|
|
|
```bash
|
|
|
|
psql -d <DB_NAME> -U <DB_USER>
|
|
|
|
UPDATE public.user SET api_token='<API_TOKEN>' WHERE
|
|
email='<USER_EMAIL>';
|
|
|
|
```
|
|
|
|
|
|
Where:
|
|
|
|
- `<DB_NAME>` is the name of the database schema you use for the Medusa
|
|
server.
|
|
|
|
- `<DB_USER>` is the name of the user that has privileges over the
|
|
database schema.
|
|
|
|
- `<API_TOKEN>` is the API token you want to associate with the user.
|
|
You can use [this tool to generate a random
|
|
token](https://randomkeygen.com/).
|
|
|
|
- `<USER_EMAIL>` is the email address of the admin user you want to have
|
|
this API token.
|
|
|
|
|
|
### How to Use the API Token
|
|
|
|
|
|
The API token can be used for Bearer Authentication. It's passed in the
|
|
`Authorization` header as the following:
|
|
|
|
|
|
```
|
|
|
|
Authorization: Bearer {api_token}
|
|
|
|
```
|
|
|
|
|
|
In this API reference, you'll find in the cURL request samples the use
|
|
of `{api_token}`. This is where you must pass the API token.
|
|
|
|
|
|
If you're alternatively following along with the JS Client request
|
|
samples, you must provide the `apiKey` option when creating the Medusa
|
|
client:
|
|
|
|
|
|
```js
|
|
|
|
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3,
|
|
apiKey: '{api_token}' })
|
|
|
|
```
|
|
scheme: bearer
|
|
cookie_auth:
|
|
type: apiKey
|
|
in: cookie
|
|
name: connect.sid
|
|
x-displayName: Cookie Session ID
|
|
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 admin user 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
|
|
user](#tag/Auth/operation/PostAuth) and pass the cURL option `-v`:
|
|
|
|
|
|
```bash
|
|
|
|
curl -v --location --request POST 'https://medusa-url.com/admin/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/admin/products' \
|
|
|
|
--header 'Cookie: connect.sid={sid}'
|
|
|
|
```
|
|
|
|
|
|
Where `{sid}` is the value of `connect.sid` that you copied.
|