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.


    For example, when you list customers you can also retrieve their groups by
    passing to the `expand` query parameter the value `groups`.


    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
    orders and the groups of a customer, pass to the `expand` query parameter
    the value `groups,orders`.


    Please note that the parameters you pass to `expand` replace any relations
    that are expanded by default.


    ## 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.


    You can pass more than one field by seperating the field names in the
    `fields` query parameter with a comma.


    Only the fields you pass to `field` will be retrieved and returned in the
    response. Any fields that are returned by default will not be returned in
    this case. This does not affect relations.


    For example, to only select the `title` and `description` fields of a
    product, pass to the `fields` query parameter the value `title,description`.


    ## 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.


    ### Response Fields


    In listing fields, aside from the entities retrieved, there are three
    pagination-related fields returned: `count`, `limit`, and `offset`.


    Similarly 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`.
  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/{condition_id}/batch:
    $ref: paths/discounts_{discount_id}_conditions_{condition_id}_batch.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
  /order-edits/{id}/items:
    $ref: paths/order-edits_{id}_items.yaml
  /order-edits/{id}/cancel:
    $ref: paths/order-edits_{id}_cancel.yaml
  /order-edits/{id}/confirm:
    $ref: paths/order-edits_{id}_confirm.yaml
  /order-edits:
    $ref: paths/order-edits.yaml
  /order-edits/{id}/items/{item_id}:
    $ref: paths/order-edits_{id}_items_{item_id}.yaml
  /order-edits/{id}/changes/{change_id}:
    $ref: paths/order-edits_{id}_changes_{change_id}.yaml
  /order-edits/{id}:
    $ref: paths/order-edits_{id}.yaml
  /order-edits/{id}/request:
    $ref: paths/order-edits_{id}_request.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/protected:
    $ref: paths/uploads_protected.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.