985 lines
29 KiB
YAML
985 lines
29 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> -->
|
|
|
|
|
|
## Expanding Fields
|
|
|
|
|
|
In many endpoints you'll find an `expand` query parameter that can be passed
|
|
to the endpoint. You can use the `expand` query parameter to unpack an
|
|
entity's relations and return them in the response.
|
|
|
|
|
|
Please note that the relations you pass to `expand` replace any relations
|
|
that are expanded by default in the request.
|
|
|
|
|
|
### Expanding One Relation
|
|
|
|
|
|
For example, when you retrieve products, you can retrieve their collection
|
|
by passing to the `expand` query parameter the value `collection`:
|
|
|
|
|
|
```bash
|
|
|
|
curl "http://localhost:9000/admin/products?expand=collection" \
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
### Expanding Multiple Relations
|
|
|
|
|
|
You can expand more than one relation by separating the relations in the
|
|
`expand` query parameter with a comma.
|
|
|
|
|
|
For example, to retrieve both the variants and the collection of products,
|
|
pass to the `expand` query parameter the value `variants,collection`:
|
|
|
|
|
|
```bash
|
|
|
|
curl "http://localhost:9000/admin/products?expand=variants,collection" \
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
### Prevent Expanding Relations
|
|
|
|
|
|
Some requests expand relations by default. You can prevent that by passing
|
|
an empty expand value to retrieve an entity without any extra relations.
|
|
|
|
|
|
For example:
|
|
|
|
|
|
```bash
|
|
|
|
curl "http://localhost:9000/admin/products?expand" \
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
This would retrieve each product with only its properties, without any
|
|
relations like `collection`.
|
|
|
|
|
|
## Selecting Fields
|
|
|
|
|
|
In many endpoints you'll find a `fields` query parameter that can be passed
|
|
to the endpoint. You can use the `fields` query parameter to specify which
|
|
fields in the entity should be returned in the response.
|
|
|
|
|
|
Please note that if you pass a `fields` query parameter, only the fields you
|
|
pass in the value along with the `id` of the entity will be returned in the
|
|
response.
|
|
|
|
|
|
Also, the `fields` query parameter does not affect the expanded relations.
|
|
You'll have to use the `expand` parameter instead.
|
|
|
|
|
|
### Selecting One Field
|
|
|
|
|
|
For example, when you retrieve a list of products, you can retrieve only the
|
|
titles of the products by passing `title` as a value to the `fields` query
|
|
parameter:
|
|
|
|
|
|
```bash
|
|
|
|
curl "http://localhost:9000/admin/products?fields=title" \
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
As mentioned above, the expanded relations such as `variants` will still be
|
|
returned as they're not affected by the `fields` parameter.
|
|
|
|
|
|
You can ensure that only the `title` field is returned by passing an empty
|
|
value to the `expand` query parameter. For example:
|
|
|
|
|
|
```bash
|
|
|
|
curl "http://localhost:9000/admin/products?fields=title&expand" \
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
### Selecting Multiple Fields
|
|
|
|
|
|
You can pass more than one field by seperating the field names in the
|
|
`fields` query parameter with a comma.
|
|
|
|
|
|
For example, to select the `title` and `handle` of products:
|
|
|
|
|
|
```bash
|
|
|
|
curl "http://localhost:9000/admin/products?fields=title,handle" \
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
### Retrieve Only the ID
|
|
|
|
|
|
You can pass an empty `fields` query parameter to return only the ID of an
|
|
entity. For example:
|
|
|
|
|
|
```bash
|
|
|
|
curl "http://localhost:9000/admin/products?fields" \
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
You can also pair with an empty `expand` query parameter to ensure that the
|
|
relations aren't retrieved as well. For example:
|
|
|
|
|
|
```bash
|
|
|
|
curl "http://localhost:9000/admin/products?fields&expand" \
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
## Query Parameter Types
|
|
|
|
|
|
This section covers how to pass some common data types as query parameters.
|
|
This is useful if you're sending requests to the API endpoints and not using
|
|
our JS Client. For example, when using cURL or Postman.
|
|
|
|
|
|
### Strings
|
|
|
|
|
|
You can pass a string value in the form of `<parameter_name>=<value>`.
|
|
|
|
|
|
For example:
|
|
|
|
|
|
```bash
|
|
|
|
curl "http://localhost:9000/admin/products?title=Shirt" \
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
If the string has any characters other than letters and numbers, you must
|
|
encode them.
|
|
|
|
|
|
For example, if the string has spaces, you can encode the space with `+` or
|
|
`%20`:
|
|
|
|
|
|
```bash
|
|
|
|
curl "http://localhost:9000/admin/products?title=Blue%20Shirt" \
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
You can use tools like [this one](https://www.urlencoder.org/) to learn how
|
|
a value can be encoded.
|
|
|
|
|
|
### Integers
|
|
|
|
|
|
You can pass an integer value in the form of `<parameter_name>=<value>`.
|
|
|
|
|
|
For example:
|
|
|
|
|
|
```bash
|
|
|
|
curl "http://localhost:9000/admin/products?offset=1" \
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
### Boolean
|
|
|
|
|
|
You can pass a boolean value in the form of `<parameter_name>=<value>`.
|
|
|
|
|
|
For example:
|
|
|
|
|
|
```bash
|
|
|
|
curl "http://localhost:9000/admin/products?is_giftcard=true" \
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
### Date and DateTime
|
|
|
|
|
|
You can pass a date value in the form `<parameter_name>=<value>`. The date
|
|
must be in the format `YYYY-MM-DD`.
|
|
|
|
|
|
For example:
|
|
|
|
|
|
```bash
|
|
|
|
curl -g "http://localhost:9000/admin/products?created_at[lt]=2023-02-17" \
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
You can also pass the time using the format `YYYY-MM-DDTHH:MM:SSZ`. Please
|
|
note that the `T` and `Z` here are fixed.
|
|
|
|
|
|
For example:
|
|
|
|
|
|
```bash
|
|
|
|
curl -g
|
|
"http://localhost:9000/admin/products?created_at[lt]=2023-02-17T07:22:30Z" \
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
### Array
|
|
|
|
|
|
Each array value must be passed as a separate query parameter in the form
|
|
`<parameter_name>[]=<value>`. You can also specify the index of each
|
|
parameter in the brackets `<parameter_name>[0]=<value>`.
|
|
|
|
|
|
For example:
|
|
|
|
|
|
```bash
|
|
|
|
curl -g
|
|
"http://localhost:9000/admin/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7"
|
|
\
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
Note that the `-g` parameter passed to `curl` disables errors being thrown
|
|
for using the brackets. Read more
|
|
[here](https://curl.se/docs/manpage.html#-g).
|
|
|
|
|
|
### Object
|
|
|
|
|
|
Object parameters must be passed as separate query parameters in the form
|
|
`<parameter_name>[<key>]=<value>`.
|
|
|
|
|
|
For example:
|
|
|
|
|
|
```bash
|
|
|
|
curl -g
|
|
"http://localhost:9000/admin/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17"
|
|
\
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
## Pagination
|
|
|
|
|
|
### Query Parameters
|
|
|
|
|
|
In listing endpoints, such as list customers or list products, you can
|
|
control the pagination using the query parameters `limit` and `offset`.
|
|
|
|
|
|
`limit` is used to specify the maximum number of items that can be return in
|
|
the response. `offset` is used to specify how many items to skip before
|
|
returning the resulting entities.
|
|
|
|
|
|
You can use the `offset` query parameter to change between pages. For
|
|
example, if the limit is 50, at page 1 the offset should be 0; at page 2 the
|
|
offset should be 50, and so on.
|
|
|
|
|
|
For example, to limit the number of products returned in the List Products
|
|
endpoint:
|
|
|
|
|
|
```bash
|
|
|
|
curl "http://localhost:9000/admin/products?limit=5" \
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
### Response Fields
|
|
|
|
|
|
In the response of listing endpoints, aside from the entities retrieved,
|
|
there are three pagination-related fields returned: `count`, `limit`, and
|
|
`offset`.
|
|
|
|
|
|
Similar to the query parameters, `limit` is the maximum number of items that
|
|
can be returned in the response, and `field` is the number of items that
|
|
were skipped before the entities in the result.
|
|
|
|
|
|
`count` is the total number of available items of this entity. It can be
|
|
used to determine how many pages are there.
|
|
|
|
|
|
For example, if the `count` is 100 and the `limit` is 50, you can divide the
|
|
`count` by the `limit` to get the number of pages: `100/50 = 2 pages`.
|
|
|
|
|
|
### Sort Order
|
|
|
|
|
|
The `order` field available on endpoints supporting pagination allows you to
|
|
sort the retrieved items by an attribute of that item. For example, you can
|
|
sort products by their `created_at` attribute by setting `order` to
|
|
`created_at`:
|
|
|
|
|
|
```bash
|
|
|
|
curl "http://localhost:9000/admin/products?order=created_at" \
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
By default, the sort direction will be ascending. To change it to
|
|
descending, pass a dash (`-`) before the attribute name. For example:
|
|
|
|
|
|
```bash
|
|
|
|
curl "http://localhost:9000/admin/products?order=-created_at" \
|
|
|
|
-H 'Authorization: Bearer {api_token}'
|
|
|
|
```
|
|
|
|
|
|
This sorts the products by their `created_at` attribute in the descending
|
|
order.
|
|
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: Apps
|
|
description: App endpoints that allow handling apps in Medusa.
|
|
- name: Batch Jobs
|
|
description: Batch Job endpoints that allow handling batch jobs in Medusa.
|
|
- name: Collections
|
|
description: Collection endpoints that allow handling collections in Medusa.
|
|
- name: Customers
|
|
description: Customer endpoints that allow handling customers in Medusa.
|
|
- name: Customer Groups
|
|
description: Customer Group endpoints that allow handling customer groups in Medusa.
|
|
- name: Discounts
|
|
description: Discount endpoints that allow handling discounts in Medusa.
|
|
- name: Draft Orders
|
|
description: Draft Order endpoints that allow handling draft orders in Medusa.
|
|
- name: Gift Cards
|
|
description: Gift Card endpoints that allow handling gift cards in Medusa.
|
|
- name: Invites
|
|
description: Invite endpoints that allow handling invites in Medusa.
|
|
- name: Notes
|
|
description: Note endpoints that allow handling notes in Medusa.
|
|
- name: Notifications
|
|
description: Notification endpoints that allow handling notifications in Medusa.
|
|
- name: Orders
|
|
description: Order endpoints that allow handling orders in Medusa.
|
|
- name: Price Lists
|
|
description: Price List endpoints that allow handling price lists in Medusa.
|
|
- name: Products
|
|
description: Product endpoints that allow handling products in Medusa.
|
|
- name: Product Tags
|
|
description: Product Tag endpoints that allow handling product tags in Medusa.
|
|
- name: Product Types
|
|
description: Product Types endpoints that allow handling product types in Medusa.
|
|
- name: Regions
|
|
description: Region endpoints that allow handling regions in Medusa.
|
|
- name: Return Reasons
|
|
description: Return Reason endpoints that allow handling return reasons in Medusa.
|
|
- name: Returns
|
|
description: Return endpoints that allow handling returns in Medusa.
|
|
- name: Sales Channels
|
|
description: Sales Channel endpoints that allow handling sales channels in Medusa.
|
|
- name: Shipping Options
|
|
description: Shipping Option endpoints that allow handling shipping options in Medusa.
|
|
- name: Shipping Profiles
|
|
description: >-
|
|
Shipping Profile endpoints that allow handling shipping profiles in
|
|
Medusa.
|
|
- name: Store
|
|
description: Store endpoints that allow handling stores in Medusa.
|
|
- name: Swaps
|
|
description: Swap endpoints that allow handling swaps in Medusa.
|
|
- name: Tax Rates
|
|
description: Tax Rate endpoints that allow handling tax rates in Medusa.
|
|
- name: Uploads
|
|
description: Upload endpoints that allow handling uploads in Medusa.
|
|
- name: Users
|
|
description: User endpoints that allow handling users in Medusa.
|
|
- name: Variants
|
|
description: Product Variant endpoints that allow handling product variants in Medusa.
|
|
servers:
|
|
- url: https://api.medusa-commerce.com
|
|
paths:
|
|
/admin/apps:
|
|
$ref: paths/admin_apps.yaml
|
|
/admin/apps/authorizations:
|
|
$ref: paths/admin_apps_authorizations.yaml
|
|
/admin/auth:
|
|
$ref: paths/admin_auth.yaml
|
|
/admin/batch-jobs:
|
|
$ref: paths/admin_batch-jobs.yaml
|
|
/admin/batch-jobs/{id}:
|
|
$ref: paths/admin_batch-jobs_{id}.yaml
|
|
/admin/batch-jobs/{id}/cancel:
|
|
$ref: paths/admin_batch-jobs_{id}_cancel.yaml
|
|
/admin/batch-jobs/{id}/confirm:
|
|
$ref: paths/admin_batch-jobs_{id}_confirm.yaml
|
|
/admin/collections:
|
|
$ref: paths/admin_collections.yaml
|
|
/admin/collections/{id}:
|
|
$ref: paths/admin_collections_{id}.yaml
|
|
/admin/collections/{id}/products/batch:
|
|
$ref: paths/admin_collections_{id}_products_batch.yaml
|
|
/admin/currencies:
|
|
$ref: paths/admin_currencies.yaml
|
|
/admin/currencies/{code}:
|
|
$ref: paths/admin_currencies_{code}.yaml
|
|
/admin/customer-groups:
|
|
$ref: paths/admin_customer-groups.yaml
|
|
/admin/customer-groups/{id}:
|
|
$ref: paths/admin_customer-groups_{id}.yaml
|
|
/admin/customer-groups/{id}/customers:
|
|
$ref: paths/admin_customer-groups_{id}_customers.yaml
|
|
/admin/customer-groups/{id}/customers/batch:
|
|
$ref: paths/admin_customer-groups_{id}_customers_batch.yaml
|
|
/admin/customers:
|
|
$ref: paths/admin_customers.yaml
|
|
/admin/customers/{id}:
|
|
$ref: paths/admin_customers_{id}.yaml
|
|
/admin/discounts:
|
|
$ref: paths/admin_discounts.yaml
|
|
/admin/discounts/code/{code}:
|
|
$ref: paths/admin_discounts_code_{code}.yaml
|
|
/admin/discounts/{discount_id}/conditions:
|
|
$ref: paths/admin_discounts_{discount_id}_conditions.yaml
|
|
/admin/discounts/{discount_id}/conditions/{condition_id}:
|
|
$ref: paths/admin_discounts_{discount_id}_conditions_{condition_id}.yaml
|
|
/admin/discounts/{discount_id}/conditions/{condition_id}/batch:
|
|
$ref: paths/admin_discounts_{discount_id}_conditions_{condition_id}_batch.yaml
|
|
/admin/discounts/{id}:
|
|
$ref: paths/admin_discounts_{id}.yaml
|
|
/admin/discounts/{id}/dynamic-codes:
|
|
$ref: paths/admin_discounts_{id}_dynamic-codes.yaml
|
|
/admin/discounts/{id}/dynamic-codes/{code}:
|
|
$ref: paths/admin_discounts_{id}_dynamic-codes_{code}.yaml
|
|
/admin/discounts/{id}/regions/{region_id}:
|
|
$ref: paths/admin_discounts_{id}_regions_{region_id}.yaml
|
|
/admin/draft-orders:
|
|
$ref: paths/admin_draft-orders.yaml
|
|
/admin/draft-orders/{id}:
|
|
$ref: paths/admin_draft-orders_{id}.yaml
|
|
/admin/draft-orders/{id}/line-items:
|
|
$ref: paths/admin_draft-orders_{id}_line-items.yaml
|
|
/admin/draft-orders/{id}/line-items/{line_id}:
|
|
$ref: paths/admin_draft-orders_{id}_line-items_{line_id}.yaml
|
|
/admin/draft-orders/{id}/pay:
|
|
$ref: paths/admin_draft-orders_{id}_pay.yaml
|
|
/admin/gift-cards:
|
|
$ref: paths/admin_gift-cards.yaml
|
|
/admin/gift-cards/{id}:
|
|
$ref: paths/admin_gift-cards_{id}.yaml
|
|
/admin/inventory-items:
|
|
$ref: paths/admin_inventory-items.yaml
|
|
/admin/inventory-items/{id}:
|
|
$ref: paths/admin_inventory-items_{id}.yaml
|
|
/admin/inventory-items/{id}/location-levels:
|
|
$ref: paths/admin_inventory-items_{id}_location-levels.yaml
|
|
/admin/inventory-items/{id}/location-levels/{location_id}:
|
|
$ref: paths/admin_inventory-items_{id}_location-levels_{location_id}.yaml
|
|
/admin/invites:
|
|
$ref: paths/admin_invites.yaml
|
|
/admin/invites/accept:
|
|
$ref: paths/admin_invites_accept.yaml
|
|
/admin/invites/{invite_id}:
|
|
$ref: paths/admin_invites_{invite_id}.yaml
|
|
/admin/invites/{invite_id}/resend:
|
|
$ref: paths/admin_invites_{invite_id}_resend.yaml
|
|
/admin/notes:
|
|
$ref: paths/admin_notes.yaml
|
|
/admin/notes/{id}:
|
|
$ref: paths/admin_notes_{id}.yaml
|
|
/admin/notifications:
|
|
$ref: paths/admin_notifications.yaml
|
|
/admin/notifications/{id}/resend:
|
|
$ref: paths/admin_notifications_{id}_resend.yaml
|
|
/admin/order-edits:
|
|
$ref: paths/admin_order-edits.yaml
|
|
/admin/order-edits/{id}:
|
|
$ref: paths/admin_order-edits_{id}.yaml
|
|
/admin/order-edits/{id}/cancel:
|
|
$ref: paths/admin_order-edits_{id}_cancel.yaml
|
|
/admin/order-edits/{id}/changes/{change_id}:
|
|
$ref: paths/admin_order-edits_{id}_changes_{change_id}.yaml
|
|
/admin/order-edits/{id}/confirm:
|
|
$ref: paths/admin_order-edits_{id}_confirm.yaml
|
|
/admin/order-edits/{id}/items:
|
|
$ref: paths/admin_order-edits_{id}_items.yaml
|
|
/admin/order-edits/{id}/items/{item_id}:
|
|
$ref: paths/admin_order-edits_{id}_items_{item_id}.yaml
|
|
/admin/order-edits/{id}/request:
|
|
$ref: paths/admin_order-edits_{id}_request.yaml
|
|
/admin/orders:
|
|
$ref: paths/admin_orders.yaml
|
|
/admin/orders/{id}:
|
|
$ref: paths/admin_orders_{id}.yaml
|
|
/admin/orders/{id}/archive:
|
|
$ref: paths/admin_orders_{id}_archive.yaml
|
|
/admin/orders/{id}/cancel:
|
|
$ref: paths/admin_orders_{id}_cancel.yaml
|
|
/admin/orders/{id}/capture:
|
|
$ref: paths/admin_orders_{id}_capture.yaml
|
|
/admin/orders/{id}/claims:
|
|
$ref: paths/admin_orders_{id}_claims.yaml
|
|
/admin/orders/{id}/claims/{claim_id}:
|
|
$ref: paths/admin_orders_{id}_claims_{claim_id}.yaml
|
|
/admin/orders/{id}/claims/{claim_id}/cancel:
|
|
$ref: paths/admin_orders_{id}_claims_{claim_id}_cancel.yaml
|
|
/admin/orders/{id}/claims/{claim_id}/fulfillments:
|
|
$ref: paths/admin_orders_{id}_claims_{claim_id}_fulfillments.yaml
|
|
/admin/orders/{id}/claims/{claim_id}/fulfillments/{fulfillment_id}/cancel:
|
|
$ref: >-
|
|
paths/admin_orders_{id}_claims_{claim_id}_fulfillments_{fulfillment_id}_cancel.yaml
|
|
/admin/orders/{id}/claims/{claim_id}/shipments:
|
|
$ref: paths/admin_orders_{id}_claims_{claim_id}_shipments.yaml
|
|
/admin/orders/{id}/complete:
|
|
$ref: paths/admin_orders_{id}_complete.yaml
|
|
/admin/orders/{id}/fulfillment:
|
|
$ref: paths/admin_orders_{id}_fulfillment.yaml
|
|
/admin/orders/{id}/fulfillments/{fulfillment_id}/cancel:
|
|
$ref: paths/admin_orders_{id}_fulfillments_{fulfillment_id}_cancel.yaml
|
|
/admin/orders/{id}/line-items/{line_item_id}/reserve:
|
|
$ref: paths/admin_orders_{id}_line-items_{line_item_id}_reserve.yaml
|
|
/admin/orders/{id}/refund:
|
|
$ref: paths/admin_orders_{id}_refund.yaml
|
|
/admin/orders/{id}/reservations:
|
|
$ref: paths/admin_orders_{id}_reservations.yaml
|
|
/admin/orders/{id}/return:
|
|
$ref: paths/admin_orders_{id}_return.yaml
|
|
/admin/orders/{id}/shipment:
|
|
$ref: paths/admin_orders_{id}_shipment.yaml
|
|
/admin/orders/{id}/shipping-methods:
|
|
$ref: paths/admin_orders_{id}_shipping-methods.yaml
|
|
/admin/orders/{id}/swaps:
|
|
$ref: paths/admin_orders_{id}_swaps.yaml
|
|
/admin/orders/{id}/swaps/{swap_id}/cancel:
|
|
$ref: paths/admin_orders_{id}_swaps_{swap_id}_cancel.yaml
|
|
/admin/orders/{id}/swaps/{swap_id}/fulfillments:
|
|
$ref: paths/admin_orders_{id}_swaps_{swap_id}_fulfillments.yaml
|
|
/admin/orders/{id}/swaps/{swap_id}/fulfillments/{fulfillment_id}/cancel:
|
|
$ref: >-
|
|
paths/admin_orders_{id}_swaps_{swap_id}_fulfillments_{fulfillment_id}_cancel.yaml
|
|
/admin/orders/{id}/swaps/{swap_id}/process-payment:
|
|
$ref: paths/admin_orders_{id}_swaps_{swap_id}_process-payment.yaml
|
|
/admin/orders/{id}/swaps/{swap_id}/shipments:
|
|
$ref: paths/admin_orders_{id}_swaps_{swap_id}_shipments.yaml
|
|
/admin/payment-collections/{id}:
|
|
$ref: paths/admin_payment-collections_{id}.yaml
|
|
/admin/payment-collections/{id}/authorize:
|
|
$ref: paths/admin_payment-collections_{id}_authorize.yaml
|
|
/admin/payments/{id}:
|
|
$ref: paths/admin_payments_{id}.yaml
|
|
/admin/payments/{id}/capture:
|
|
$ref: paths/admin_payments_{id}_capture.yaml
|
|
/admin/payments/{id}/refund:
|
|
$ref: paths/admin_payments_{id}_refund.yaml
|
|
/admin/price-lists:
|
|
$ref: paths/admin_price-lists.yaml
|
|
/admin/price-lists/{id}:
|
|
$ref: paths/admin_price-lists_{id}.yaml
|
|
/admin/price-lists/{id}/prices/batch:
|
|
$ref: paths/admin_price-lists_{id}_prices_batch.yaml
|
|
/admin/price-lists/{id}/products:
|
|
$ref: paths/admin_price-lists_{id}_products.yaml
|
|
/admin/price-lists/{id}/products/{product_id}/prices:
|
|
$ref: paths/admin_price-lists_{id}_products_{product_id}_prices.yaml
|
|
/admin/price-lists/{id}/variants/{variant_id}/prices:
|
|
$ref: paths/admin_price-lists_{id}_variants_{variant_id}_prices.yaml
|
|
/admin/product-categories:
|
|
$ref: paths/admin_product-categories.yaml
|
|
/admin/product-categories/{id}:
|
|
$ref: paths/admin_product-categories_{id}.yaml
|
|
/admin/product-categories/{id}/products/batch:
|
|
$ref: paths/admin_product-categories_{id}_products_batch.yaml
|
|
/admin/product-tags:
|
|
$ref: paths/admin_product-tags.yaml
|
|
/admin/product-types:
|
|
$ref: paths/admin_product-types.yaml
|
|
/admin/products:
|
|
$ref: paths/admin_products.yaml
|
|
/admin/products/tag-usage:
|
|
$ref: paths/admin_products_tag-usage.yaml
|
|
/admin/products/types:
|
|
$ref: paths/admin_products_types.yaml
|
|
/admin/products/{id}:
|
|
$ref: paths/admin_products_{id}.yaml
|
|
/admin/products/{id}/metadata:
|
|
$ref: paths/admin_products_{id}_metadata.yaml
|
|
/admin/products/{id}/options:
|
|
$ref: paths/admin_products_{id}_options.yaml
|
|
/admin/products/{id}/options/{option_id}:
|
|
$ref: paths/admin_products_{id}_options_{option_id}.yaml
|
|
/admin/products/{id}/variants:
|
|
$ref: paths/admin_products_{id}_variants.yaml
|
|
/admin/products/{id}/variants/{variant_id}:
|
|
$ref: paths/admin_products_{id}_variants_{variant_id}.yaml
|
|
/admin/publishable-api-key/{id}:
|
|
$ref: paths/admin_publishable-api-key_{id}.yaml
|
|
/admin/publishable-api-keys:
|
|
$ref: paths/admin_publishable-api-keys.yaml
|
|
/admin/publishable-api-keys/{id}:
|
|
$ref: paths/admin_publishable-api-keys_{id}.yaml
|
|
/admin/publishable-api-keys/{id}/revoke:
|
|
$ref: paths/admin_publishable-api-keys_{id}_revoke.yaml
|
|
/admin/publishable-api-keys/{id}/sales-channels:
|
|
$ref: paths/admin_publishable-api-keys_{id}_sales-channels.yaml
|
|
/admin/publishable-api-keys/{id}/sales-channels/batch:
|
|
$ref: paths/admin_publishable-api-keys_{id}_sales-channels_batch.yaml
|
|
/admin/regions:
|
|
$ref: paths/admin_regions.yaml
|
|
/admin/regions/{id}:
|
|
$ref: paths/admin_regions_{id}.yaml
|
|
/admin/regions/{id}/countries:
|
|
$ref: paths/admin_regions_{id}_countries.yaml
|
|
/admin/regions/{id}/countries/{country_code}:
|
|
$ref: paths/admin_regions_{id}_countries_{country_code}.yaml
|
|
/admin/regions/{id}/fulfillment-options:
|
|
$ref: paths/admin_regions_{id}_fulfillment-options.yaml
|
|
/admin/regions/{id}/fulfillment-providers:
|
|
$ref: paths/admin_regions_{id}_fulfillment-providers.yaml
|
|
/admin/regions/{id}/fulfillment-providers/{provider_id}:
|
|
$ref: paths/admin_regions_{id}_fulfillment-providers_{provider_id}.yaml
|
|
/admin/regions/{id}/payment-providers:
|
|
$ref: paths/admin_regions_{id}_payment-providers.yaml
|
|
/admin/regions/{id}/payment-providers/{provider_id}:
|
|
$ref: paths/admin_regions_{id}_payment-providers_{provider_id}.yaml
|
|
/admin/reservations:
|
|
$ref: paths/admin_reservations.yaml
|
|
/admin/reservations/{id}:
|
|
$ref: paths/admin_reservations_{id}.yaml
|
|
/admin/return-reasons:
|
|
$ref: paths/admin_return-reasons.yaml
|
|
/admin/return-reasons/{id}:
|
|
$ref: paths/admin_return-reasons_{id}.yaml
|
|
/admin/returns:
|
|
$ref: paths/admin_returns.yaml
|
|
/admin/returns/{id}/cancel:
|
|
$ref: paths/admin_returns_{id}_cancel.yaml
|
|
/admin/returns/{id}/receive:
|
|
$ref: paths/admin_returns_{id}_receive.yaml
|
|
/admin/sales-channels:
|
|
$ref: paths/admin_sales-channels.yaml
|
|
/admin/sales-channels/{id}:
|
|
$ref: paths/admin_sales-channels_{id}.yaml
|
|
/admin/sales-channels/{id}/products/batch:
|
|
$ref: paths/admin_sales-channels_{id}_products_batch.yaml
|
|
/admin/sales-channels/{id}/stock-locations:
|
|
$ref: paths/admin_sales-channels_{id}_stock-locations.yaml
|
|
/admin/shipping-options:
|
|
$ref: paths/admin_shipping-options.yaml
|
|
/admin/shipping-options/{id}:
|
|
$ref: paths/admin_shipping-options_{id}.yaml
|
|
/admin/shipping-profiles:
|
|
$ref: paths/admin_shipping-profiles.yaml
|
|
/admin/shipping-profiles/{id}:
|
|
$ref: paths/admin_shipping-profiles_{id}.yaml
|
|
/admin/stock-locations:
|
|
$ref: paths/admin_stock-locations.yaml
|
|
/admin/stock-locations/{id}:
|
|
$ref: paths/admin_stock-locations_{id}.yaml
|
|
/admin/store:
|
|
$ref: paths/admin_store.yaml
|
|
/admin/store/currencies/{code}:
|
|
$ref: paths/admin_store_currencies_{code}.yaml
|
|
/admin/store/payment-providers:
|
|
$ref: paths/admin_store_payment-providers.yaml
|
|
/admin/store/tax-providers:
|
|
$ref: paths/admin_store_tax-providers.yaml
|
|
/admin/swaps:
|
|
$ref: paths/admin_swaps.yaml
|
|
/admin/swaps/{id}:
|
|
$ref: paths/admin_swaps_{id}.yaml
|
|
/admin/tax-rates:
|
|
$ref: paths/admin_tax-rates.yaml
|
|
/admin/tax-rates/{id}:
|
|
$ref: paths/admin_tax-rates_{id}.yaml
|
|
/admin/tax-rates/{id}/product-types/batch:
|
|
$ref: paths/admin_tax-rates_{id}_product-types_batch.yaml
|
|
/admin/tax-rates/{id}/products/batch:
|
|
$ref: paths/admin_tax-rates_{id}_products_batch.yaml
|
|
/admin/tax-rates/{id}/shipping-options/batch:
|
|
$ref: paths/admin_tax-rates_{id}_shipping-options_batch.yaml
|
|
/admin/uploads:
|
|
$ref: paths/admin_uploads.yaml
|
|
/admin/uploads/download-url:
|
|
$ref: paths/admin_uploads_download-url.yaml
|
|
/admin/uploads/protected:
|
|
$ref: paths/admin_uploads_protected.yaml
|
|
/admin/users:
|
|
$ref: paths/admin_users.yaml
|
|
/admin/users/password-token:
|
|
$ref: paths/admin_users_password-token.yaml
|
|
/admin/users/reset-password:
|
|
$ref: paths/admin_users_reset-password.yaml
|
|
/admin/users/{id}:
|
|
$ref: paths/admin_users_{id}.yaml
|
|
/admin/variants:
|
|
$ref: paths/admin_variants.yaml
|
|
/admin/variants/{id}:
|
|
$ref: paths/admin_variants_{id}.yaml
|
|
/admin/variants/{id}/inventory:
|
|
$ref: paths/admin_variants_{id}_inventory.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 following along with the JS Client request samples, you must
|
|
provide the `apiKey` option when creating the Medusa client:
|
|
|
|
|
|
```ts
|
|
|
|
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3,
|
|
apiKey: '{api_token}' })
|
|
|
|
```
|
|
|
|
|
|
If you're using Medusa React, you can pass the `apiKey` prop to
|
|
`MedusaProvider`:
|
|
|
|
|
|
```tsx
|
|
|
|
<MedusaProvider
|
|
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.
|