medusa-store/docs/api/admin/openapi.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: Apps Oauth
    description: >
      Some plugins may require to authenticate with third-party services and
      store authentication details, such as the authentication token. To do
      that, they can create an Oauth provider within the plugin that handles the
      authentication.

      The Apps Oauth endpoints allows admins to manage and generate token for an
      app using its oauth provider.
  - name: Auth
    description: >
      Authentication endpoints allow admin users to manage their session, such
      as login or log out.

      When an admin user is logged in, the cookie header is set indicating the
      admin's login session.
    externalDocs:
      description: How to implement user profiles
      url: https://docs.medusajs.com/modules/users/admin/manage-profile
  - name: Batch Jobs
    description: >
      A batch job is a task that is performed by the Medusa backend
      asynchronusly. For example, the Import Product feature is implemented
      using batch jobs.

      Batch Job endpoints allows admins to manage the batch jobs and their
      state.
    externalDocs:
      description: How to import products
      url: https://docs.medusajs.com/modules/products/admin/import-products
  - name: Currencies
    description: >
      A store can use unlimited currencies, and each region must be associated
      with at least one currency.

      Currencies are defined within the Medusa backend. Currency endpoints allow
      admins to list and update currencies.
    externalDocs:
      description: How to manage currencies
      url: >-
        https://docs.medusajs.com/modules/regions-and-currencies/admin/manage-currencies
  - name: Customers
    description: >
      Customers can either be created when they register through the Store APIs,
      or created by the admin using the Admin APIs.
    externalDocs:
      description: How to manage customers
      url: https://docs.medusajs.com/modules/customers/admin/manage-customers
  - name: Customer Groups
    description: >
      Customer Groups can be used to organize customers that share similar data
      or attributes into dedicated groups.

      This can be useful for different purposes such as setting a different
      price for a specific customer group.
    externalDocs:
      description: How to manage customer groups
      url: https://docs.medusajs.com/modules/customers/admin/manage-customer-groups
  - name: Discounts
    description: >
      Admins can create discounts with conditions and rules, providing them with
      advanced settings for variety of cases.

      The Discount endpoints can be used to manage discounts, their conditions,
      resources, and more.
    externalDocs:
      description: How to manage discounts
      url: https://docs.medusajs.com/modules/discounts/admin/manage-discounts
  - name: Draft Orders
    description: >
      A draft order is an order created manually by the admin. It allows admins
      to create orders without direct involvement from the customer.
    externalDocs:
      description: How to manage draft orders
      url: https://docs.medusajs.com/modules/orders/admin/manage-draft-orders
  - name: Gift Cards
    description: >
      Admins can create gift cards and send them directly to customers,
      specifying options like their balance, region, and more.

      These gift cards are different than the saleable gift cards in a store,
      which are created and managed through Product endpoints.
    externalDocs:
      description: How to manage gift cards
      url: >-
        https://docs.medusajs.com/modules/gift-cards/admin/manage-gift-cards#manage-custom-gift-cards
  - name: Inventory Items
    description: >
      Inventory items, provided by the [Inventory
      Module](https://docs.medusajs.com/modules/multiwarehouse/inventory-module),
      can be used to manage the inventory of saleable items in your store.
    externalDocs:
      description: How to manage inventory items
      url: >-
        https://docs.medusajs.com/modules/multiwarehouse/admin/manage-inventory-items
  - name: Invites
    description: >
      An admin can invite new users to manage their team. This would allow new
      users to authenticate as admins and perform admin functionalities.
    externalDocs:
      description: How to manage invites
      url: https://docs.medusajs.com/modules/users/admin/manage-invites
  - name: Notes
    description: >
      Notes are created by admins and can be associated with any resource. For
      example, an admin can add a note to an order for additional details or
      remarks.
  - name: Notifications
    description: >
      Notifications are sent to customers to inform them of new updates. For
      example, a notification can be sent to the customer when their order is
      place or its state is updated.

      The notification's type, such as an email or SMS, is determined by the
      notification provider installed on the Medusa backend.
  - name: Orders
    description: >
      Orders are purchases made by customers, typically through a storefront
      using the Store API. Draft orders created by the admin are also
      transformed to an Order once the payment is captured.

      Managing orders include managing fulfillment, payment, claims,
      reservations, and more.
    externalDocs:
      description: How to manage orders
      url: https://docs.medusajs.com/modules/orders/admin/manage-orders
  - name: Order Edits
    description: >
      An admin can edit an order to remove, add, or update an item's quantity.
      When an admin edits an order, they're stored as an `OrderEdit`.
    externalDocs:
      description: How to edit an order
      url: https://docs.medusajs.com/modules/orders/admin/edit-order
  - name: Payment Collections
    description: >
      A payment collection is useful for managing additional payments, such as
      for Order Edits, or installment payments.
  - name: Price Lists
    description: >
      A price list are special prices applied to products based on a set of
      conditions, such as customer group.
    externalDocs:
      description: How to manage price lists
      url: https://docs.medusajs.com/modules/price-lists/admin/manage-price-lists
  - name: Products
    description: >
      Products are saleable items in a store. This also includes [saleable gift
      cards](https://docs.medusajs.com/modules/gift-cards/admin/manage-gift-cards#manage-gift-card-product)
      in a store.
    externalDocs:
      description: How to manage products
      url: https://docs.medusajs.com/modules/products/admin/manage-products
  - name: Product Categories
    description: >
      Products can be categoriezed into categories. A product can be added into
      more than one category.
    externalDocs:
      description: How to manage product categories
      url: https://docs.medusajs.com/modules/products/admin/manage-categories
  - name: Product Collections
    description: >
      A product collection is used to organize products for different purposes
      such as marketing or discount purposes. For example, you can create a
      Summer Collection.
  - name: Product Tags
    description: >
      Product tags are string values created when you create or update a product
      with a new tag.

      Products can have more than one tag, and products can share tags. This
      allows admins to associate products to similar tags that can be used to
      filter products.
  - name: Product Types
    description: >
      Product types are string values created when you create or update a
      product with a new type.

      Products can have one type, and products can share types. This allows
      admins to associate products with a type that can be used to filter
      products.
  - name: Product Variants
    description: >
      Product variants are the actual salable item in your store. Each variant
      is a combination of the different option values available on the product.

      Product variants can be managed through the Products endpoints.
    externalDocs:
      description: How to manage product variants
      url: >-
        https://docs.medusajs.com/modules/products/admin/manage-products#manage-product-variants
  - name: Publishable API Keys
    description: >
      Publishable API Keys can be used to scope Store API calls with an API key,
      determining what resources are retrieved when querying the API.

      For example, a publishable API key can be associated with one or more
      sales channels. When it is passed in the header of a request to the List
      Product store endpoint,

      the sales channels are inferred from the key and only products associated
      with those sales channels are retrieved.

      Admins can manage publishable API keys and their associated resources.
      Currently, only Sales Channels are supported as a resource.
    externalDocs:
      description: How to manage publishable API keys
      url: >-
        https://docs.medusajs.com/development/publishable-api-keys/admin/manage-publishable-api-keys
  - name: Reservations
    description: >
      Reservations, provided by the [Inventory
      Module](https://docs.medusajs.com/modules/multiwarehouse/inventory-module),
      are quantities of an item that are reserved, typically when an order is
      placed but not yet fulfilled.

      Reservations can be associated with any resources, but commonly with line
      items of an order.
    externalDocs:
      description: How to manage item allocations in orders
      url: >-
        https://docs.medusajs.com/modules/multiwarehouse/admin/manage-item-allocations-in-orders
  - name: Regions
    description: >
      Regions are different countries or geographical regions that the commerce
      store serves customers in.

      Admins can manage these regions, their providers, and more.
    externalDocs:
      description: How to manage regions
      url: >-
        https://docs.medusajs.com/modules/regions-and-currencies/admin/manage-regions
  - name: Return Reasons
    description: >
      Return reasons are key-value pairs that are used to specify why an order
      return is being created.

      Admins can manage available return reasons, and they can be used by both
      admins and customers when creating a return.
    externalDocs:
      description: How to manage return reasons
      url: >-
        https://docs.medusajs.com/modules/orders/admin/manage-returns#manage-return-reasons
  - name: Returns
    description: >
      A return can be created by a customer or an admin to return items in an
      order.

      Admins can manage these returns and change their state.
    externalDocs:
      description: How to manage returns
      url: https://docs.medusajs.com/modules/orders/admin/manage-returns
  - name: Sales Channels
    description: >
      A sales channel indicates a channel where products can be sold in. For
      example, a webshop or a mobile app.

      Admins can manage sales channels and the products available in them.
    externalDocs:
      description: How to manage sales channels
      url: https://docs.medusajs.com/modules/sales-channels/admin/manage
  - name: Shipping Options
    description: >
      A shipping option is used to define the available shipping methods during
      checkout or when creating a return.

      Admins can create an unlimited number of shipping options, each associated
      with a shipping profile and fulfillment provider, among other resources.
    externalDocs:
      description: Shipping Option architecture
      url: >-
        https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-option
  - name: Shipping Profiles
    description: >
      A shipping profile is used to group products that can be shipped in the
      same manner.

      They are created by the admin and they're not associated with a
      fulfillment provider.
    externalDocs:
      description: Shipping Option architecture
      url: >-
        https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-profile
  - name: Stock Locations
    description: >
      A stock location, provided by the [Stock Location
      module](https://docs.medusajs.com/modules/multiwarehouse/stock-location-module),
      indicates a physical address that stock-kept items, such as physical
      products, can be stored in.

      An admin can create and manage available stock locations.
    externalDocs:
      description: How to manage stock locations.
      url: >-
        https://docs.medusajs.com/modules/multiwarehouse/admin/manage-stock-locations
  - name: Store
    description: >
      A store indicates the general configurations and details about the
      commerce store. By default, there's only one store in the Medusa backend.

      Admins can manage the store and its details or configurations.
  - name: Swaps
    description: >
      A swap is created by a customer or an admin to exchange an item with a new
      one.

      Creating a swap implicitely includes creating a return for the item being
      exchanged.
    externalDocs:
      description: How to manage swaps
      url: https://docs.medusajs.com/modules/orders/admin/manage-swaps
  - name: Tax Rates
    description: >
      Each region has at least a default tax rate. Admins can create and manage
      additional tax rates that can be applied for certain conditions, such as
      for specific product types.
    externalDocs:
      description: How to manage tax rates
      url: https://docs.medusajs.com/modules/taxes/admin/manage-tax-rates
  - name: Uploads
    description: >
      The upload endpoints are used to upload any type of resources. For
      example, they can be used to upload CSV files that are used to import
      products into the store.
    externalDocs:
      description: How to upload CSV file when importing a product.
      url: >-
        https://docs.medusajs.com/modules/products/admin/import-products#1-upload-csv-file
  - name: Users
    description: >
      A store can have more than one user, each having the same privileges.
      Admins can manage users, their passwords, and more.
    externalDocs:
      description: How to manage users
      url: https://docs.medusajs.com/modules/users/admin/manage-users
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.