docs: Add request and error examples (#2109)

docs/api/admin-spec3-base.json

@@ -1,173 +0,0 @@
-{
-  "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`.",
-    "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 Types",
-      "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": {}
-}

docs/api/admin-spec3-base.yaml

@@ -0,0 +1,321 @@
+openapi: 3.0.0
+info:
+  version: 1.0.0
+  title: Medusa Admin API
+  description: |
+    API reference for Medusa's Admin endpoints. All endpoints are prefixed with `/admin`.
+    
+    ## Authentication
+
+    There are two ways to send authenticated requests to the Medusa server: Using a user's API token, or using a Cookie Session ID.
+
+    <!-- ReDoc-Inject: <SecurityDefinitions> -->
+  license:
+    name: MIT
+    url: https://github.com/medusajs/medusa/blob/master/LICENSE
+tags:
+- name: Auth
+  description: Auth endpoints that allow authorization of admin Users and manages
+    their sessions.
+- name: App
+  description: App endpoints that allow handling apps in Medusa.
+  x-resourceId: OAuth
+- name: Batch Job
+  description: Batch Job endpoints that allow handling batch jobs in Medusa.
+  x-resourceId: batch_job
+- name: Claim
+  description: Claim endpoints that allow handling claims in Medusa.
+  x-resourceId: claim_order
+- name: Collection
+  description: Collection endpoints that allow handling collections in Medusa.
+  x-resourceId: product_collection
+- name: Customer
+  description: Customer endpoints that allow handling customers in Medusa.
+  x-resourceId: customer
+- name: Customer Group
+  description: Customer Group endpoints that allow handling customer groups in Medusa.
+  x-resourceId: customer_group
+- name: Discount
+  description: Discount endpoints that allow handling discounts in Medusa.
+  x-resourceId: discount
+- name: Discount Condition
+  description: Discount Condition endpoints that allow handling discount conditions
+    in Medusa.
+  x-resourceId: discount_condition
+- name: Draft Order
+  description: Draft Order endpoints that allow handling draft orders in Medusa.
+  x-resourceId: draft-order
+- name: Gift Card
+  description: Gift Card endpoints that allow handling gift cards in Medusa.
+  x-resourceId: gift_card
+- name: Invite
+  description: Invite endpoints that allow handling invites in Medusa.
+  x-resourceId: invite
+- name: Note
+  description: Note endpoints that allow handling notes in Medusa.
+  x-resourceId: note
+- name: Notification
+  description: Notification endpoints that allow handling notifications in Medusa.
+  x-resourceId: notification
+- name: Order
+  description: Order endpoints that allow handling orders in Medusa.
+  x-resourceId: order
+- name: Price List
+  description: Price List endpoints that allow handling price lists in Medusa.
+  x-resourceId: price_list
+- name: Product
+  description: Product endpoints that allow handling products in Medusa.
+  x-resourceId: product
+- name: Product Tag
+  description: Product Tag endpoints that allow handling product tags in Medusa.
+  x-resourceId: product_tag
+- name: Product Type
+  description: Product Types endpoints that allow handling product types in Medusa.
+  x-resourceId: product_type
+- name: Product Variant
+  description: Product Variant endpoints that allow handling product variants in Medusa.
+  x-resourceId: product_variant
+- name: Region
+  description: Region endpoints that allow handling regions in Medusa.
+  x-resourceId: region
+- name: Return Reason
+  description: Return Reason endpoints that allow handling return reasons in Medusa.
+  x-resourceId: return_reason
+- name: Return
+  description: Return endpoints that allow handling returns in Medusa.
+  x-resourceId: return
+- name: Sales Channel
+  description: Sales Channel endpoints that allow handling sales channels in Medusa.
+  x-resourceId: sales_channel
+- name: Shipping Option
+  description: Shipping Option endpoints that allow handling shipping options in Medusa.
+  x-resourceId: shipping_option
+- name: Shipping Profile
+  description: Shipping Profile endpoints that allow handling shipping profiles in
+    Medusa.
+  x-resourceId: shipping_profile
+- name: Store
+  description: Store endpoints that allow handling stores in Medusa.
+  x-resourceId: store
+- name: Swap
+  description: Swap endpoints that allow handling swaps in Medusa.
+  x-resourceId: swap
+- name: Tax Rate
+  description: Tax Rate endpoints that allow handling tax rates in Medusa.
+  x-resourceId: tax_rate
+- name: Upload
+  description: Upload endpoints that allow handling uploads in Medusa.
+- name: User
+  description: User endpoints that allow handling users in Medusa.
+  x-resourceId: user
+servers:
+- url: https://api.medusa-commerce.com/admin
+paths: {}
+components:
+  responses: 
+    default_error:
+      description: Default Error
+      content:
+        application/json:
+          schema: 
+            $ref: "#/components/schemas/error"
+          example:
+            code: "unknown_error"
+            message: "An unknown error occurred."
+            type: "unknown_error"
+    invalid_state_error:
+      description: Invalid State Error
+      content:
+        application/json:
+          schema: 
+            $ref: "#/components/schemas/error"
+          example:
+            code: "unknown_error"
+            message: "The request conflicted with another request. You may retry the request with the provided Idempotency-Key."
+            type: "QueryRunnerAlreadyReleasedError"
+    invalid_request_error:
+      description: Invalid Request Error
+      content:
+        application/json:
+          schema: 
+            $ref: "#/components/schemas/error"
+          example:
+            code: "invalid_request_error"
+            message: "Discount with code TEST already exists."
+            type: "duplicate_error"
+    not_found_error:
+      description: Not Found Error
+      content:
+        application/json:
+          schema: 
+            $ref: "#/components/schemas/error"
+          example:
+            message: "Entity with id 1 was not found"
+            type: "not_found"
+    400_error:
+      description: Client Error or Multiple Errors
+      content:
+        application/json:
+          schema:
+            oneOf: 
+              - $ref: "#/components/schemas/error"
+              - $ref: "#/components/schemas/multiple_errors"
+          examples: 
+            not_allowed:
+              $ref: "#/components/examples/not_allowed_error"
+            invalid_data:
+              $ref: "#/components/examples/invalid_data_error"
+            multiple_errors:
+              $ref: "#/components/examples/multiple_errors"
+    500_error:
+      description: Server Error
+      content:
+        application/json:
+          schema: 
+            $ref: "#/components/schemas/error"
+          examples: 
+            database:
+              $ref: "#/components/examples/database_error"
+            unexpected_state:
+              $ref: "#/components/examples/unexpected_state_error"
+            invalid_argument:
+              $ref: "#/components/examples/invalid_argument_error"
+            default_error:
+              $ref: "#/components/examples/default_error"
+    unauthorized:
+      description: 'User is not authorized. Must log in first'
+      content: 
+        text/plain:
+          schema: 
+            type: string
+            default: Unauthorized
+            example: Unauthorized
+    incorrect_credentials:
+      description: 'User does not exist or incorrect credentials'
+      content: 
+        text/plain:
+          schema: 
+            type: string
+            default: Unauthorized
+            example: Unauthorized
+  examples:
+    not_allowed_error:
+      summary: Not Allowed Error
+      value:
+        message: "Discount must be set to dynamic"
+        type: "not_allowed"
+    invalid_data_error:
+      summary: Invalid Data Error
+      value:
+        message: "first_name must be a string"
+        type: "invalid_data"
+    multiple_errors:
+      summary: Multiple Errors
+      value:
+        message: "Provided request body contains errors. Please check the data and retry the request"
+        errors:
+          - message: "first_name must be a string"
+            type: "invalid_data"
+          - message: "Discount must be set to dynamic"
+            type: "not_allowed"
+    database_error:
+      summary: Database Error
+      value:
+        code: "api_error"
+        message: "An error occured while hashing password"
+        type: "database_error"
+    unexpected_state_error:
+      summary: Unexpected State Error
+      value:
+        message: "cart.total must be defined"
+        type: "unexpected_state"
+    invalid_argument_error:
+      summary: Invalid Argument Error
+      value:
+        message: "cart.total must be defined"
+        type: "unexpected_state"
+    default_error:
+      summary: Default Error
+      value:
+        code: "unknown_error"
+        message: "An unknown error occurred."
+        type: "unknown_error"
+  securitySchemes:
+    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.

docs/api/store-spec3-base.json

@@ -1,84 +0,0 @@
-{
-  "openapi": "3.0.0",
-  "info": {
-    "version": "1.0.0",
-    "title": "Medusa Storefront API",
-    "description": "API reference for Medusa's Storefront endpoints. All endpoints are prefixed with `/store`.",
-    "license": {
-      "name": "MIT",
-      "url": "https://github.com/medusajs/medusa/blob/master/LICENSE"
-    }
-  },
-  "tags": [
-    {
-      "name": "Auth",
-      "description": "Auth endpoints that allow authorization of customers and manages their sessions."
-    },
-    {
-      "name": "Cart",
-      "description": "Cart endpoints that allow handling carts in Medusa.",
-      "x-resourceId": "cart"
-    },
-    {
-      "name": "Collection",
-      "description": "Collection endpoints that allow handling collections in Medusa.",
-      "x-resourceId": "product_collection"
-    },
-    {
-      "name": "Customer",
-      "description": "Customer endpoints that allow handling customers in Medusa.",
-      "x-resourceId": "customer"
-    },
-    {
-      "name": "Gift Card",
-      "description": "Gift Card endpoints that allow handling gift cards in Medusa.",
-      "x-resourceId": "gift_card"
-    },
-    {
-      "name": "Order",
-      "description": "Order endpoints that allow handling orders in Medusa.",
-      "x-resourceId": "order"
-    },
-    {
-      "name": "Product",
-      "description": "Product endpoints that allow handling products in Medusa.",
-      "x-resourceId": "product"
-    },
-    {
-      "name": "Product Variant",
-      "description": "Product Variant endpoints that allow handling product variants in Medusa.",
-      "x-resourceId": "product_variant"
-    },
-    {
-      "name": "Region",
-      "description": "Region endpoints that allow handling regions in Medusa.",
-      "x-resourceId": "region"
-    },
-    {
-      "name": "Return Reason",
-      "description": "Return Reason endpoints that allow handling return reasons in Medusa.",
-      "x-resourceId": "return_reason"
-    },
-    {
-      "name": "Return",
-      "description": "Return endpoints that allow handling returns in Medusa.",
-      "x-resourceId": "return"
-    },
-    {
-      "name": "Shipping Option",
-      "description": "Shipping Option endpoints that allow handling shipping options in Medusa.",
-      "x-resourceId": "shipping_option"
-    },
-    {
-      "name": "Swap",
-      "description": "Swap endpoints that allow handling swaps in Medusa.",
-      "x-resourceId": "swap"
-    }
-  ],
-  "servers": [
-    {
-      "url": "https://api.medusa-commerce.com/store"
-    }
-  ],
-  "paths": {}
-}

docs/api/store-spec3-base.yaml

@@ -0,0 +1,227 @@
+openapi: 3.0.0
+info:
+  version: 1.0.0
+  title: Medusa Storefront API
+  description: |
+    API reference for Medusa's Storefront endpoints. All endpoints are prefixed with `/store`.
+    
+    ## Authentication
+
+    To send requests as an authenticated customer, you must use the Cookie Session ID.
+
+    <!-- ReDoc-Inject: <SecurityDefinitions> -->
+  license:
+    name: MIT
+    url: https://github.com/medusajs/medusa/blob/master/LICENSE
+tags:
+- name: Auth
+  description: Auth endpoints that allow authorization of customers and manages their
+    sessions.
+- name: Cart
+  description: Cart endpoints that allow handling carts in Medusa.
+  x-resourceId: cart
+- name: Collection
+  description: Collection endpoints that allow handling collections in Medusa.
+  x-resourceId: product_collection
+- name: Customer
+  description: Customer endpoints that allow handling customers in Medusa.
+  x-resourceId: customer
+- name: Gift Card
+  description: Gift Card endpoints that allow handling gift cards in Medusa.
+  x-resourceId: gift_card
+- name: Order
+  description: Order endpoints that allow handling orders in Medusa.
+  x-resourceId: order
+- name: Product
+  description: Product endpoints that allow handling products in Medusa.
+  x-resourceId: product
+- name: Product Variant
+  description: Product Variant endpoints that allow handling product variants in Medusa.
+  x-resourceId: product_variant
+- name: Region
+  description: Region endpoints that allow handling regions in Medusa.
+  x-resourceId: region
+- name: Return Reason
+  description: Return Reason endpoints that allow handling return reasons in Medusa.
+  x-resourceId: return_reason
+- name: Return
+  description: Return endpoints that allow handling returns in Medusa.
+  x-resourceId: return
+- name: Shipping Option
+  description: Shipping Option endpoints that allow handling shipping options in Medusa.
+  x-resourceId: shipping_option
+- name: Swap
+  description: Swap endpoints that allow handling swaps in Medusa.
+  x-resourceId: swap
+servers:
+- url: https://api.medusa-commerce.com/store
+paths: {}
+components:
+  responses: 
+    default_error:
+      description: Default Error
+      content:
+        application/json:
+          schema: 
+            $ref: "#/components/schemas/error"
+          example:
+            code: "unknown_error"
+            message: "An unknown error occurred."
+            type: "unknown_error"
+    invalid_state_error:
+      description: Invalid State Error
+      content:
+        application/json:
+          schema: 
+            $ref: "#/components/schemas/error"
+          example:
+            code: "unknown_error"
+            message: "The request conflicted with another request. You may retry the request with the provided Idempotency-Key."
+            type: "QueryRunnerAlreadyReleasedError"
+    invalid_request_error:
+      description: Invalid Request Error
+      content:
+        application/json:
+          schema: 
+            $ref: "#/components/schemas/error"
+          example:
+            code: "invalid_request_error"
+            message: "Discount with code TEST already exists."
+            type: "duplicate_error"
+    not_found_error:
+      description: Not Found Error
+      content:
+        application/json:
+          schema: 
+            $ref: "#/components/schemas/error"
+          example:
+            message: "Entity with id 1 was not found"
+            type: "not_found"
+    400_error:
+      description: Client Error or Multiple Errors
+      content:
+        application/json:
+          schema:
+            oneOf: 
+              - $ref: "#/components/schemas/error"
+              - $ref: "#/components/schemas/multiple_errors"
+          examples: 
+            not_allowed:
+              $ref: "#/components/examples/not_allowed_error"
+            invalid_data:
+              $ref: "#/components/examples/invalid_data_error"
+            multiple_errors:
+              $ref: "#/components/examples/multiple_errors"
+    500_error:
+      description: Server Error
+      content:
+        application/json:
+          schema: 
+            $ref: "#/components/schemas/error"
+          examples: 
+            database:
+              $ref: "#/components/examples/database_error"
+            unexpected_state:
+              $ref: "#/components/examples/unexpected_state_error"
+            invalid_argument:
+              $ref: "#/components/examples/invalid_argument_error"
+            default_error:
+              $ref: "#/components/examples/default_error"
+    unauthorized:
+      description: 'User is not authorized. Must log in first'
+      content: 
+        text/plain:
+          schema: 
+            type: string
+            default: Unauthorized
+            example: Unauthorized
+    incorrect_credentials:
+      description: 'User does not exist or incorrect credentials'
+      content: 
+        text/plain:
+          schema: 
+            type: string
+            default: Unauthorized
+            example: Unauthorized
+  examples:
+    not_allowed_error:
+      summary: Not Allowed Error
+      value:
+        message: "Discount must be set to dynamic"
+        type: "not_allowed"
+    invalid_data_error:
+      summary: Invalid Data Error
+      value:
+        message: "first_name must be a string"
+        type: "invalid_data"
+    multiple_errors:
+      summary: Multiple Errors
+      value:
+        message: "Provided request body contains errors. Please check the data and retry the request"
+        errors:
+          - message: "first_name must be a string"
+            type: "invalid_data"
+          - message: "Discount must be set to dynamic"
+            type: "not_allowed"
+    database_error:
+      summary: Database Error
+      value:
+        code: "api_error"
+        message: "An error occured while hashing password"
+        type: "database_error"
+    unexpected_state_error:
+      summary: Unexpected State Error
+      value:
+        message: "cart.total must be defined"
+        type: "unexpected_state"
+    invalid_argument_error:
+      summary: Invalid Argument Error
+      value:
+        message: "cart.total must be defined"
+        type: "unexpected_state"
+    default_error:
+      summary: Default Error
+      value:
+        code: "unknown_error"
+        message: "An unknown error occurred."
+        type: "unknown_error"
+  securitySchemes:
+    cookie_auth:
+      type: apiKey
+      x-displayName: Cookie Session ID
+      in: cookie
+      name: connect.sid
+      description: |
+        Use a cookie session to send authenticated requests.
+
+        ### How to Obtain the Cookie Session
+
+        If you're sending requests through a browser, using JS Client, or using tools like Postman, the cookie session should be automatically set when the customer is logged in.
+
+        If you're sending requests using cURL, you must set the Session ID in the cookie manually.
+
+        To do that, send a request to [authenticate the customer](#tag/Auth/operation/PostAuth) and pass the cURL option `-v`:
+
+        ```bash
+        curl -v --location --request POST 'https://medusa-url.com/store/auth' \
+        --header 'Content-Type: application/json' \
+        --data-raw '{
+          "email": "user@example.com",
+          "password": "supersecret"
+        }'
+        ```
+
+        The headers will be logged in the terminal as well as the response. You should find in the headers a Cookie header similar to this:
+
+        ```bash
+        Set-Cookie: connect.sid=s%3A2Bu8BkaP9JUfHu9rG59G16Ma0QZf6Gj1.WT549XqX37PN8n0OecqnMCq798eLjZC5IT7yiDCBHPM;
+        ```
+
+        Copy the value after `connect.sid` (without the `;` at the end) and pass it as a cookie in subsequent requests as the following:
+
+        ```bash
+        curl --location --request GET 'https://medusa-url.com/store/customers/me/orders' \
+        --header 'Cookie: connect.sid={sid}'
+        ```
+        
+        Where `{sid}` is the value of `connect.sid` that you copied.

packages/medusa/src/api/middlewares/await-middleware.ts

@@ -15,3 +15,18 @@ export default (fn: handler): RequestHandler => {
     return fn(req, res).catch(next)
   }
 }
+
+/**
+ * @schema multiple_errors
+ * title: "Multiple Errors"
+ * x-resourceId: multiple_errors
+ * properties:
+ *  errors:
+ *    type: array
+ *    description: Array of errors
+ *    items:
+ *      $ref: "#/components/schemas/error"
+ *  message:
+ *    type: string
+ *    default: "Provided request body contains errors. Please check the data and retry the request"
+ */

packages/medusa/src/api/middlewares/error-handler.ts

@@ -67,3 +67,19 @@ export default () => {
     res.status(statusCode).json(errObj)
   }
 }
+
+/**
+ * @schema error
+ * title: "Response Error"
+ * x-resourceId: error
+ * properties:
+ *  code:
+ *    type: string
+ *    description: A slug code to indicate the type of the error.
+ *  message:
+ *    type: string
+ *    description: Description of the error that occurred.
+ *  type:
+ *    type: string
+ *    description: A slug indicating the type of the error.
+ */

packages/medusa/src/api/routes/admin/apps/authorize-app.ts

@@ -27,6 +27,21 @@ import { validator } from "../../../../utils/validator"
  *           code:
  *             type: string
  *             description: The code for the generated token.
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/apps/authorizations' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "application_name": "example",
+ *           "state": "ready",
+ *           "code": "token"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - App
  * responses:
@@ -38,6 +53,18 @@ import { validator } from "../../../../utils/validator"
  *          properties:
  *            apps:
  *              $ref: "#/components/schemas/OAuth"
+ *  "400":
+ *    $ref: "#/components/responses/400_error"
+ *  "401":
+ *    $ref: "#/components/responses/unauthorized"
+ *  "404":
+ *    $ref: "#/components/responses/not_found_error"
+ *  "409":
+ *    $ref: "#/components/responses/invalid_state_error"
+ *  "422":
+ *    $ref: "#/components/responses/invalid_request_error"
+ *  "500":
+ *    $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const validated = await validator(AdminPostAppsReq, req.body)

packages/medusa/src/api/routes/admin/apps/list.ts

@@ -6,6 +6,15 @@ import { OauthService } from "../../../../services"
  * summary: "List applications"
  * description: "Retrieve a list of applications."
  * x-authenticated: true
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/apps' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - App
  * responses:
@@ -19,6 +28,18 @@ import { OauthService } from "../../../../services"
  *               type: array
  *               items:
  *                 $ref: "#/components/schemas/OAuth"
+ *  "400":
+ *    $ref: "#/components/responses/400_error"
+ *  "401":
+ *    $ref: "#/components/responses/unauthorized"
+ *  "404":
+ *    $ref: "#/components/responses/not_found_error"
+ *  "409":
+ *    $ref: "#/components/responses/invalid_state_error"
+ *  "422":
+ *    $ref: "#/components/responses/invalid_request_error"
+ *  "500":
+ *    $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const oauthService: OauthService = req.scope.resolve("oauthService")

packages/medusa/src/api/routes/admin/auth/create-session.ts

@@ -32,6 +32,27 @@ import { validator } from "../../../../utils/validator"
  *             type: string
  *             description: The User's password.
  *             format: password
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       medusa.admin.auth.createSession({
+ *         email: 'user@example.com',
+ *         password: 'supersecret'
+ *       }).then((({ user }) => {
+ *         console.log(user.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/auth' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *         "email": "user@example.com",
+ *         "password": "supersecret"
+ *       }'
  * tags:
  *   - Auth
  * responses:
@@ -43,8 +64,18 @@ import { validator } from "../../../../utils/validator"
  *          properties:
  *            user:
  *              $ref: "#/components/schemas/user"
+ *  "400":
+ *    $ref: "#/components/responses/400_error"
  *  "401":
- *    description: The user doesn't exist or the credentials are incorrect.
+ *    $ref: "#/components/responses/incorrect_credentials"
+ *  "404":
+ *    $ref: "#/components/responses/not_found_error"
+ *  "409":
+ *    $ref: "#/components/responses/invalid_state_error"
+ *  "422":
+ *    $ref: "#/components/responses/invalid_request_error"
+ *  "500":
+ *    $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { projectConfig: { jwt_secret } } = req.scope.resolve('configModule')

packages/medusa/src/api/routes/admin/auth/delete-session.ts

@@ -4,11 +4,39 @@
  * summary: "Delete Session"
  * x-authenticated: true
  * description: "Deletes the current session for the logged in user."
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.auth.deleteSession()
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request DELETE 'https://medusa-url.com/admin/auth' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Auth
  * responses:
  *  "200":
  *    description: OK
+ *  "400":
+ *    $ref: "#/components/responses/400_error"
+ *  "401":
+ *    $ref: "#/components/responses/unauthorized"
+ *  "404":
+ *    $ref: "#/components/responses/not_found_error"
+ *  "409":
+ *    $ref: "#/components/responses/invalid_state_error"
+ *  "422":
+ *    $ref: "#/components/responses/invalid_request_error"
+ *  "500":
+ *    $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   req.session.destroy()

packages/medusa/src/api/routes/admin/auth/get-session.ts

@@ -7,6 +7,25 @@ import _ from "lodash"
  * summary: "Get Session"
  * x-authenticated: true
  * description: "Gets the currently logged in User."
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.auth.getSession()
+ *       .then(({ user }) => {
+ *         console.log(user.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/auth' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Auth
  * responses:
@@ -19,7 +38,17 @@ import _ from "lodash"
  *            user:
  *              $ref: "#/components/schemas/user"
  *  "400":
- *    description: An error occurred.
+ *    $ref: "#/components/responses/400_error"
+ *  "401":
+ *    $ref: "#/components/responses/unauthorized"
+ *  "404":
+ *    $ref: "#/components/responses/not_found_error"
+ *  "409":
+ *    $ref: "#/components/responses/invalid_state_error"
+ *  "422":
+ *    $ref: "#/components/responses/invalid_request_error"
+ *  "500":
+ *    $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   try {

packages/medusa/src/api/routes/admin/batch/cancel-batch-job.ts

@@ -9,6 +9,25 @@ import { EntityManager } from "typeorm"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the batch job.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.batchJobs.cancel(batch_job_id)
+ *       .then(({ batch_job }) => {
+ *         console.log(batch_job.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/batch-jobs/{id}/cancel' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Batch Job
  * responses:
@@ -20,6 +39,18 @@ import { EntityManager } from "typeorm"
  *          properties:
  *            batch_job:
  *              $ref: "#/components/schemas/batch_job"
+ *  "400":
+ *    $ref: "#/components/responses/400_error"
+ *  "401":
+ *    $ref: "#/components/responses/unauthorized"
+ *  "404":
+ *    $ref: "#/components/responses/not_found_error"
+ *  "409":
+ *    $ref: "#/components/responses/invalid_state_error"
+ *  "422":
+ *    $ref: "#/components/responses/invalid_request_error"
+ *  "500":
+ *    $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   let batch_job = req.batch_job

packages/medusa/src/api/routes/admin/batch/confirm-batch-job.ts

@@ -9,6 +9,25 @@ import { EntityManager } from "typeorm"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the batch job.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.batchJobs.confirm(batch_job_id)
+ *       .then(({ batch_job }) => {
+ *         console.log(batch_job.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/batch-jobs/{id}/confirm' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Batch Job
  * responses:
@@ -20,6 +39,18 @@ import { EntityManager } from "typeorm"
  *          properties:
  *            batch_job:
  *              $ref: "#/components/schemas/batch_job"
+ *  "400":
+ *    $ref: "#/components/responses/400_error"
+ *  "401":
+ *    $ref: "#/components/responses/unauthorized"
+ *  "404":
+ *    $ref: "#/components/responses/not_found_error"
+ *  "409":
+ *    $ref: "#/components/responses/invalid_state_error"
+ *  "422":
+ *    $ref: "#/components/responses/invalid_request_error"
+ *  "500":
+ *    $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   let batch_job = req.batch_job

packages/medusa/src/api/routes/admin/batch/create-batch-job.ts

@@ -46,6 +46,33 @@ import { validator } from "../../../../utils/validator"
  *            type: boolean
  *            description: Set a batch job in dry_run mode to get some information on what will be done without applying any modifications.
  *            default: false
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.batchJobs.create({
+ *         type: 'product-export',
+ *         context: {},
+ *         dry_run: false
+ *       }).then((({ batch_job }) => {
+ *         console.log(batch_job.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/batch-jobs' \
+ *       --header 'Content-Type: application/json' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --data-raw '{
+ *           "type": "product-export",
+ *           "context": { }
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Batch Job
  * responses:
@@ -57,6 +84,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *            batch_job:
  *              $ref: "#/components/schemas/batch_job"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const validated = await validator(AdminPostBatchesReq, req.body)

packages/medusa/src/api/routes/admin/batch/get-batch-job.ts

@@ -6,6 +6,25 @@
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Batch Job
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.batchJobs.retrieve(batch_job_id)
+ *       .then(({ batch_job }) => {
+ *         console.log(batch_job.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/batch-jobs/{id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Batch Job
  * responses:
@@ -17,6 +36,18 @@
  *          properties:
  *            batch_job:
  *              $ref: "#/components/schemas/batch_job"
+ *  "400":
+ *    $ref: "#/components/responses/400_error"
+ *  "401":
+ *    $ref: "#/components/responses/unauthorized"
+ *  "404":
+ *    $ref: "#/components/responses/not_found_error"
+ *  "409":
+ *    $ref: "#/components/responses/invalid_state_error"
+ *  "422":
+ *    $ref: "#/components/responses/invalid_request_error"
+ *  "500":
+ *    $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const batch_job = req.batch_job

packages/medusa/src/api/routes/admin/batch/list-batch-jobs.ts

@@ -210,6 +210,25 @@ import { isDefined } from "../../../../utils"
  *            type: string
  *            description: filter by dates greater than or equal to this date
  *            format: date
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.batchJobs.list()
+ *       .then(({ batch_jobs, limit, offset, count }) => {
+ *         console.log(batch_jobs.length);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/batch-jobs' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Batch Job
  * responses:
@@ -232,6 +251,18 @@ import { isDefined } from "../../../../utils"
  *            limit:
  *               type: integer
  *               description: The number of items per page
+ *  "400":
+ *    $ref: "#/components/responses/400_error"
+ *  "401":
+ *    $ref: "#/components/responses/unauthorized"
+ *  "404":
+ *    $ref: "#/components/responses/not_found_error"
+ *  "409":
+ *    $ref: "#/components/responses/invalid_state_error"
+ *  "422":
+ *    $ref: "#/components/responses/invalid_request_error"
+ *  "500":
+ *    $ref: "#/components/responses/500_error"
  */
 export default async (req: Request, res) => {
   const batchService: BatchJobService = req.scope.resolve("batchJobService")

packages/medusa/src/api/routes/admin/collections/add-products.ts

@@ -25,6 +25,21 @@ import ProductCollectionService from "../../../../services/product-collection"
  *             items:
  *               description: "The ID of a Product to add to the Product Collection."
  *               type: string
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/collections/{id}/products/batch' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "product_ids": [
+ *               "prod_01G1G5V2MBA328390B5AXJ610F"
+ *           ]
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Collection
  * responses:
@@ -36,6 +51,18 @@ import ProductCollectionService from "../../../../services/product-collection"
  *          properties:
  *            collection:
  *              $ref: "#/components/schemas/product_collection"
+ *  "400":
+ *    $ref: "#/components/responses/400_error"
+ *  "401":
+ *    $ref: "#/components/responses/unauthorized"
+ *  "404":
+ *    $ref: "#/components/responses/not_found_error"
+ *  "409":
+ *    $ref: "#/components/responses/invalid_state_error"
+ *  "422":
+ *    $ref: "#/components/responses/invalid_request_error"
+ *  "500":
+ *    $ref: "#/components/responses/500_error"
  */
 export default async (req: Request, res: Response) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/collections/create-collection.ts

@@ -25,6 +25,31 @@ import { EntityManager } from "typeorm"
  *           metadata:
  *             description: An optional set of key-value pairs to hold additional information.
  *             type: object
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.collections.create({
+ *         title: 'New Collection'
+ *       })
+ *       .then(({ collection }) => {
+ *         console.log(collection.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/collections' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "title": "New Collection"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Collection
  * responses:
@@ -36,6 +61,18 @@ import { EntityManager } from "typeorm"
  *          properties:
  *            collection:
  *              $ref: "#/components/schemas/product_collection"
+ *  "400":
+ *    $ref: "#/components/responses/400_error"
+ *  "401":
+ *    $ref: "#/components/responses/unauthorized"
+ *  "404":
+ *    $ref: "#/components/responses/not_found_error"
+ *  "409":
+ *    $ref: "#/components/responses/invalid_state_error"
+ *  "422":
+ *    $ref: "#/components/responses/invalid_request_error"
+ *  "500":
+ *    $ref: "#/components/responses/500_error"
  */
 export default async (req: Request, res: Response) => {
   const { validatedBody } = req as { validatedBody: AdminPostCollectionsReq }

packages/medusa/src/api/routes/admin/collections/delete-collection.ts

@@ -11,6 +11,25 @@ import ProductCollectionService from "../../../../services/product-collection"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Collection.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.collections.delete(collection_id)
+ *       .then(({ id, object, deleted }) => {
+ *         console.log(id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request DELETE 'https://medusa-url.com/admin/collections/{id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Collection
  * responses:
@@ -31,6 +50,18 @@ import ProductCollectionService from "../../../../services/product-collection"
  *              type: boolean
  *              description: Whether the collection was deleted successfully or not.
  *              default: true
+ *  "400":
+ *    $ref: "#/components/responses/400_error"
+ *  "401":
+ *    $ref: "#/components/responses/unauthorized"
+ *  "404":
+ *    $ref: "#/components/responses/not_found_error"
+ *  "409":
+ *    $ref: "#/components/responses/invalid_state_error"
+ *  "422":
+ *    $ref: "#/components/responses/invalid_request_error"
+ *  "500":
+ *    $ref: "#/components/responses/500_error"
  */
 export default async (req: Request, res: Response) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/collections/get-collection.ts

@@ -10,6 +10,25 @@ import { defaultAdminCollectionsRelations } from "."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Product Collection
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.collections.retrieve(collection_id)
+ *       .then(({ collection }) => {
+ *         console.log(collection.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/collections/{id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Collection
  * responses:
@@ -21,6 +40,18 @@ import { defaultAdminCollectionsRelations } from "."
  *          properties:
  *            collection:
  *              $ref: "#/components/schemas/product_collection"
+ *  "400":
+ *    $ref: "#/components/responses/400_error"
+ *  "401":
+ *    $ref: "#/components/responses/unauthorized"
+ *  "404":
+ *    $ref: "#/components/responses/not_found_error"
+ *  "409":
+ *    $ref: "#/components/responses/invalid_state_error"
+ *  "422":
+ *    $ref: "#/components/responses/invalid_request_error"
+ *  "500":
+ *    $ref: "#/components/responses/500_error"
  */
 export default async (req: Request, res: Response) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/collections/list-collections.ts

@@ -84,6 +84,25 @@ import { Type } from "class-transformer"
  *            type: string
  *            description: filter by dates greater than or equal to this date
  *            format: date
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.collections.list()
+ *       .then(({ collections, limit, offset, count }) => {
+ *         console.log(collections.length);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/collections' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Collection
  * responses:
@@ -106,6 +125,18 @@ import { Type } from "class-transformer"
  *            limit:
  *               type: integer
  *               description: The number of items per page
+ *  "400":
+ *    $ref: "#/components/responses/400_error"
+ *  "401":
+ *    $ref: "#/components/responses/unauthorized"
+ *  "404":
+ *    $ref: "#/components/responses/not_found_error"
+ *  "409":
+ *    $ref: "#/components/responses/invalid_state_error"
+ *  "422":
+ *    $ref: "#/components/responses/invalid_request_error"
+ *  "500":
+ *    $ref: "#/components/responses/500_error"
  */
 export default async (req: Request, res: Response) => {
   const productCollectionService: ProductCollectionService = req.scope.resolve(

packages/medusa/src/api/routes/admin/collections/remove-products.ts

@@ -25,6 +25,21 @@ import ProductCollectionService from "../../../../services/product-collection"
  *             items:
  *               description: "The ID of a Product to add to the Product Collection."
  *               type: string
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request DELETE 'https://medusa-url.com/admin/collections/{id}/products/batch' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "product_ids": [
+ *               "prod_01G1G5V2MBA328390B5AXJ610F"
+ *           ]
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Collection
  * responses:
@@ -47,6 +62,18 @@ import ProductCollectionService from "../../../../services/product-collection"
  *              items:
  *                description: "The ID of a Product to add to the Product Collection."
  *                type: string
+ *  "400":
+ *    $ref: "#/components/responses/400_error"
+ *  "401":
+ *    $ref: "#/components/responses/unauthorized"
+ *  "404":
+ *    $ref: "#/components/responses/not_found_error"
+ *  "409":
+ *    $ref: "#/components/responses/invalid_state_error"
+ *  "422":
+ *    $ref: "#/components/responses/invalid_request_error"
+ *  "500":
+ *    $ref: "#/components/responses/500_error"
  */
 export default async (req: Request, res: Response) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/collections/update-collection.ts

@@ -25,6 +25,31 @@ import ProductCollectionService from "../../../../services/product-collection"
  *           metadata:
  *             description: An optional set of key-value pairs to hold additional information.
  *             type: object
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.collections.update(collection_id, {
+ *         title: 'New Collection'
+ *       })
+ *       .then(({ collection }) => {
+ *         console.log(collection.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/collections/{id}' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "title": "New Collection"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Collection
  * responses:
@@ -36,6 +61,18 @@ import ProductCollectionService from "../../../../services/product-collection"
  *          properties:
  *            collection:
  *              $ref: "#/components/schemas/product_collection"
+ *  "400":
+ *    $ref: "#/components/responses/400_error"
+ *  "401":
+ *    $ref: "#/components/responses/unauthorized"
+ *  "404":
+ *    $ref: "#/components/responses/not_found_error"
+ *  "409":
+ *    $ref: "#/components/responses/invalid_state_error"
+ *  "422":
+ *    $ref: "#/components/responses/invalid_request_error"
+ *  "500":
+ *    $ref: "#/components/responses/500_error"
  */
 export default async (req: Request, res: Response) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/customer-groups/add-customers-batch.ts

@@ -32,6 +32,39 @@ import { validator } from "../../../../utils/validator"
  *                 id:
  *                   description: ID of the customer
  *                   type: string
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.customerGroups.addCustomers(customer_group_id, {
+ *         customer_ids: [
+ *           {
+ *             id: customer_id
+ *           }
+ *         ]
+ *       })
+ *       .then(({ customer_group }) => {
+ *         console.log(customer_group.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/customer-groups/{id}/customers/batch' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "customer_ids": [
+ *               {
+ *                   "id": "cus_01G2Q4BS9GAHDBMDEN4ZQZCJB2"
+ *               }
+ *           ]
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Customer Group
  * responses:
@@ -43,6 +76,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             customer_group:
  *               $ref: "#/components/schemas/customer_group"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 
 export default async (req: Request, res: Response) => {

packages/medusa/src/api/routes/admin/customer-groups/create-customer-group.ts

@@ -14,6 +14,31 @@ import { validator } from "../../../../utils/validator"
  * parameters:
  *   - (body) name=* {string} Name of the customer group
  *   - (body) metadata {object} Metadata for the customer.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.customerGroups.create({
+ *         name: 'VIP'
+ *       })
+ *       .then(({ customer_group }) => {
+ *         console.log(customer_group.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/customer-groups' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "name": "VIP"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Customer Group
  * responses:
@@ -25,6 +50,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             customer_group:
  *               $ref: "#/components/schemas/customer_group"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 
 export default async (req: Request, res: Response) => {

packages/medusa/src/api/routes/admin/customer-groups/delete-customer-group.ts

@@ -11,6 +11,25 @@ import { EntityManager } from "typeorm"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Customer Group
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.customerGroups.delete(customer_group_id)
+ *       .then(({ id, object, deleted }) => {
+ *         console.log(id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request DELETE 'https://medusa-url.com/admin/customer-groups/{id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Customer Group
  * responses:
@@ -31,6 +50,18 @@ import { EntityManager } from "typeorm"
  *               type: boolean
  *               description: Whether the customer group was deleted successfully or not.
  *               default: true
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 
 export default async (req: Request, res: Response) => {

packages/medusa/src/api/routes/admin/customer-groups/delete-customers-batch.ts

@@ -32,6 +32,39 @@ import { validator } from "../../../../utils/validator"
  *                 id:
  *                   description: ID of the customer
  *                   type: string
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.customerGroups.removeCustomers(customer_group_id, {
+ *         customer_ids: [
+ *           {
+ *             id: customer_id
+ *           }
+ *         ]
+ *       })
+ *       .then(({ customer_group }) => {
+ *         console.log(customer_group.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request DELETE 'https://medusa-url.com/admin/customer-groups/{id}/customers/batch' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "customer_ids": [
+ *               {
+ *                   "id": "cus_01G2Q4BS9GAHDBMDEN4ZQZCJB2"
+ *               }
+ *           ]
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Customer Group
  * responses:
@@ -43,6 +76,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             customer_group:
  *               $ref: "#/components/schemas/customer_group"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 
 export default async (req: Request, res: Response) => {

packages/medusa/src/api/routes/admin/customer-groups/get-customer-group-customers.ts

@@ -10,6 +10,25 @@ import CustomerController from "../../../../controllers/customers"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the customer group.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.customerGroups.listCustomers(customer_group_id)
+ *       .then(({ customers }) => {
+ *         console.log(customers.length);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/customer-groups/{id}/customers' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Customer Group
  * responses:
@@ -32,6 +51,18 @@ import CustomerController from "../../../../controllers/customers"
  *             limit:
  *               type: integer
  *               description: The number of items per page
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req: Request, res: Response) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/customer-groups/get-customer-group.ts

@@ -13,6 +13,25 @@ import { FindParams } from "../../../../types/common"
  *   - (path) id=* {string} The ID of the Customer Group.
  *   - (query) expand {string} (Comma separated) Which fields should be expanded in the customer group.
  *   - (query) fields {string} (Comma separated) Which fields should be included in the customer group.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.customerGroups.retrieve(customer_group_id)
+ *       .then(({ customer_group }) => {
+ *         console.log(customer_group.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/customer-groups/{id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Customer Group
  * responses:
@@ -24,6 +43,18 @@ import { FindParams } from "../../../../types/common"
  *           properties:
  *             customer_group:
  *               $ref: "#/components/schemas/customer_group"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req: Request, res: Response) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/customer-groups/list-customer-groups.ts

@@ -99,7 +99,25 @@ import { Type } from "class-transformer"
  *            format: date
  *   - (query) limit=10 {integer} Limit the number of customer groups returned.
  *   - (query) expand {string} (Comma separated) Which fields should be expanded in each customer groups of the result.
-
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.customerGroups.list()
+ *       .then(({ customer_groups, limit, offset, count }) => {
+ *         console.log(customer_groups.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/customer-groups' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Customer Group
  * responses:
@@ -122,6 +140,18 @@ import { Type } from "class-transformer"
  *             limit:
  *               type: integer
  *               description: The number of items per page
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req: Request, res: Response) => {
   const customerGroupService: CustomerGroupService = req.scope.resolve(

packages/medusa/src/api/routes/admin/customer-groups/update-customer-group.ts

@@ -26,6 +26,31 @@ import { validator } from "../../../../utils/validator"
  *           metadata:
  *             description: "Metadata for the customer."
  *             type: object
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.customerGroups.update(customer_group_id, {
+ *         name: 'VIP'
+ *       })
+ *       .then(({ customer_group }) => {
+ *         console.log(customer_group.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/customer-groups/{id}' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "name": "VIP"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Customer Group
  * responses:
@@ -37,6 +62,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             customer_group:
  *               $ref: "#/components/schemas/customer_group"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 
 export default async (req: Request, res: Response) => {

packages/medusa/src/api/routes/admin/customers/create-customer.ts

@@ -42,6 +42,37 @@ import { EntityManager } from "typeorm"
  *             type: object
  * tags:
  *   - Customer
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.customers.create({
+ *         email: 'user@example.com',
+ *         first_name: 'Caterina',
+ *         last_name: 'Yost',
+ *         password: 'supersecret'
+ *       })
+ *       .then(({ customer }) => {
+ *         console.log(customer.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/customers' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "email": "user@example.com",
+ *           "first_name": "Caterina",
+ *           "last_name": "Yost",
+ *           "password": "supersecret"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * responses:
  *   201:
  *     description: OK
@@ -51,6 +82,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             customer:
  *               $ref: "#/components/schemas/customer"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const validated = await validator(AdminPostCustomersReq, req.body)

packages/medusa/src/api/routes/admin/customers/get-customer.ts

@@ -13,6 +13,25 @@ import { validator } from "../../../../utils/validator"
  *   - (path) id=* {string} The ID of the Customer.
  *   - (query) expand {string} (Comma separated) Which fields should be expanded in the customer.
  *   - (query) fields {string} (Comma separated) Which fields should be included in the customer.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.customers.retrieve(customer_id)
+ *       .then(({ customer }) => {
+ *         console.log(customer.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/customers/{id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Customer
  * responses:
@@ -24,6 +43,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             customer:
  *               $ref: "#/components/schemas/customer"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/customers/list-customers.ts

@@ -16,6 +16,25 @@ import customerController from "../../../../controllers/customers"
  *   - (query) expand {string} (Comma separated) Which fields should be expanded in each customer.
  *   - (query) q {string} a search term to search email, first_name, and last_name.
  *   - (query) groups[] {string} group IDs to search customers by.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.customers.list()
+ *       .then(({ customers, limit, offset, count }) => {
+ *         console.log(customers.length);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/customers' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Customer
  * responses:
@@ -38,6 +57,18 @@ import customerController from "../../../../controllers/customers"
  *             limit:
  *               type: integer
  *               description: The number of items per page
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const result = await customerController.listAndCount(

packages/medusa/src/api/routes/admin/customers/update-customer.ts

@@ -60,6 +60,31 @@ import { validator } from "../../../../utils/validator"
  *           metadata:
  *             description: An optional set of key-value pairs to hold additional information.
  *             type: object
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.customers.update(customer_id, {
+ *         first_name: 'Dolly'
+ *       })
+ *       .then(({ customer }) => {
+ *         console.log(customer.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/customers/{id}' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "first_name": "Dolly"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Customer
  * responses:
@@ -71,6 +96,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             customer:
  *               $ref: "#/components/schemas/customer"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/discounts/add-region.ts

@@ -13,6 +13,25 @@ import { EntityManager } from "typeorm"
  * parameters:
  *   - (path) id=* {string} The ID of the Discount.
  *   - (path) region_id=* {string} The ID of the Region.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.discounts.addRegion(discount_id, region_id)
+ *       .then(({ discount }) => {
+ *         console.log(discount.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/regions/{region_id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Discount
  * responses:
@@ -24,6 +43,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             discount:
  *               $ref: "#/components/schemas/discount"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { discount_id, region_id } = req.params

packages/medusa/src/api/routes/admin/discounts/create-condition.ts

@@ -55,7 +55,32 @@ import { validator } from "../../../../utils/validator"
  *              description: list of customer group IDs if the condition is applied on customer groups.
  *              items:
  *                type: string
-
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       import { DiscountConditionOperator } from "@medusajs/medusa"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.discounts.createCondition(discount_id, {
+ *         operator: DiscountConditionOperator.IN
+ *       })
+ *       .then(({ discount }) => {
+ *         console.log(discount.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/conditions' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "operator": "in"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Discount Condition
  * responses:
@@ -67,6 +92,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             discount:
  *               $ref: "#/components/schemas/discount"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { discount_id } = req.params

packages/medusa/src/api/routes/admin/discounts/create-discount.ts

@@ -139,6 +139,44 @@ import { validator } from "../../../../utils/validator"
  *           metadata:
  *             description: An optional set of key-value pairs to hold additional information.
  *             type: object
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       import { AllocationType, DiscountRuleType } from "@medusajs/medusa"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.discounts.create({
+ *         code: 'TEST',
+ *         rule: {
+ *           type: DiscountRuleType.FIXED,
+ *           value: 10,
+ *           allocation: AllocationType.ITEM
+ *         },
+ *         is_dynamic: false,
+ *         is_disabled: false
+ *       })
+ *       .then(({ discount }) => {
+ *         console.log(discount.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/discounts' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "code": "TEST",
+ *           "rule": {
+ *              "type": "fixed",
+ *              "value": 10,
+ *              "allocation": "item"
+ *           }
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Discount
  * responses:
@@ -150,6 +188,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             discount:
  *               $ref: "#/components/schemas/discount"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 
 export default async (req, res) => {

packages/medusa/src/api/routes/admin/discounts/create-dynamic-code.ts

@@ -22,6 +22,32 @@ import { validator } from "../../../../utils/validator"
  *   - (body) code=* {string} The unique code that will be used to redeem the Discount.
  *   - (body) usage_limit=1 {number} amount of times the discount can be applied.
  *   - (body) metadata {object} An optional set of key-value paris to hold additional information.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.discounts.createDynamicCode(discount_id, {
+ *         code: 'TEST',
+ *         usage_limit: 1
+ *       })
+ *       .then(({ discount }) => {
+ *         console.log(discount.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/dynamic-codes' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "code": "TEST"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Discount
  * responses:
@@ -33,6 +59,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             discount:
  *               $ref: "#/components/schemas/discount"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { discount_id } = req.params

packages/medusa/src/api/routes/admin/discounts/delete-condition.ts

@@ -20,6 +20,25 @@ import { validator } from "../../../../utils/validator"
  *   - (path) condition_id=* {string} The ID of the DiscountCondition
  *   - (query) expand {string} Comma separated list of relations to include in the results.
  *   - (query) fields {string} Comma separated list of fields to include in the results.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.discounts.deleteCondition(discount_id, condition_id)
+ *       .then(({ id, object, deleted }) => {
+ *         console.log(id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Discount Condition
  * responses:
@@ -43,6 +62,18 @@ import { validator } from "../../../../utils/validator"
  *             discount:
  *               description: The Discount to which the condition used to belong
  *               $ref: "#/components/schemas/discount"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { discount_id, condition_id } = req.params

packages/medusa/src/api/routes/admin/discounts/delete-discount.ts

@@ -9,6 +9,25 @@ import { EntityManager } from "typeorm"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Discount
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.discounts.delete(discount_id)
+ *       .then(({ id, object, deleted }) => {
+ *         console.log(id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Discount
  * responses:
@@ -29,6 +48,18 @@ import { EntityManager } from "typeorm"
  *               type: boolean
  *               description: Whether the discount was deleted successfully or not.
  *               default: true
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { discount_id } = req.params

packages/medusa/src/api/routes/admin/discounts/delete-dynamic-code.ts

@@ -12,6 +12,25 @@ import { EntityManager } from "typeorm"
  * parameters:
  *   - (path) id=* {string} The ID of the Discount
  *   - (path) code=* {string} The ID of the Discount
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.discounts.deleteDynamicCode(discount_id, code)
+ *       .then(({ discount }) => {
+ *         console.log(discount.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/dynamic-codes/{code}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Discount
  * responses:
@@ -23,6 +42,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             discount:
  *               $ref: "#/components/schemas/discount"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { discount_id, code } = req.params

packages/medusa/src/api/routes/admin/discounts/get-condition.ts

@@ -15,14 +15,32 @@ import { validator } from "../../../../utils/validator"
  * @oas [get] /discounts/{discount_id}/conditions/{condition_id}
  * operationId: "GetDiscountsDiscountConditionsCondition"
  * summary: "Gets a DiscountCondition"
+ * description: "Gets a DiscountCondition"
  * x-authenticated: true
  * parameters:
  *   - (path) discount_id=* {string} The ID of the Discount.
  *   - (path) condition_id=* {string} The ID of the DiscountCondition.
  *   - (query) expand {string} Comma separated list of relations to include in the results.
  *   - (query) fields {string} Comma separated list of fields to include in the results.
- * description: "Gets a DiscountCondition"
+ * x-codeSamples:
- 
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.discounts.getCondition(discount_id, condition_id)
+ *       .then(({ discount_condition }) => {
+ *         console.log(discount_condition.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition_id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Discount Condition
  * responses:
@@ -34,6 +52,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             discount_condition:
  *               $ref: "#/components/schemas/discount_condition"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 
 export default async (req, res) => {

packages/medusa/src/api/routes/admin/discounts/get-discount-by-code.ts

@@ -15,6 +15,25 @@ import { validator } from "../../../../utils/validator"
  *   - (path) code=* {string} The code of the Discount
  *   - (query) expand {string} Comma separated list of relations to include in the results.
  *   - (query) fields {string} Comma separated list of fields to include in the results.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.discounts.retrieveByCode(code)
+ *       .then(({ discount }) => {
+ *         console.log(discount.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/discounts/code/{code}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Discount
  * responses:
@@ -26,6 +45,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             discount:
  *               $ref: "#/components/schemas/discount"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { code } = req.params

packages/medusa/src/api/routes/admin/discounts/get-discount.ts

@@ -15,6 +15,25 @@ import { validator } from "../../../../utils/validator"
  *   - (path) id=* {string} The ID of the Discount
  *   - (query) expand {string} Comma separated list of relations to include in the results.
  *   - (query) fields {string} Comma separated list of fields to include in the results.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.discounts.retrieve(discount_id)
+ *       .then(({ discount }) => {
+ *         console.log(discount.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/discounts/{id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Discount
  * responses:
@@ -26,6 +45,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             discount:
  *               $ref: "#/components/schemas/discount"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { discount_id } = req.params

packages/medusa/src/api/routes/admin/discounts/list-discounts.ts

@@ -43,6 +43,25 @@ import { isDefined } from "../../../../utils"
  *   - (query) limit=20 {number} The number of items in the response
  *   - (query) offset=0 {number} The offset of items in response
  *   - (query) expand {string} Comma separated list of relations to include in the results.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.discounts.list()
+ *       .then(({ discounts, limit, offset, count }) => {
+ *         console.log(discounts.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/discounts' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Discount
  * responses:
@@ -65,6 +84,18 @@ import { isDefined } from "../../../../utils"
  *             limit:
  *               type: integer
  *               description: The number of items per page
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const validated = await validator(AdminGetDiscountsParams, req.query)

packages/medusa/src/api/routes/admin/discounts/remove-region.ts

@@ -12,6 +12,25 @@ import { EntityManager } from "typeorm"
  * parameters:
  *   - (path) id=* {string} The ID of the Discount.
  *   - (path) region_id=* {string} The ID of the Region.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.discounts.removeRegion(discount_id, region_id)
+ *       .then(({ discount }) => {
+ *         console.log(discount.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request DELETE 'https://medusa-url.com/admin/discounts/{id}/regions/{region_id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Discount
  * responses:
@@ -23,6 +42,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             discount:
  *               $ref: "#/components/schemas/discount"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { discount_id, region_id } = req.params

packages/medusa/src/api/routes/admin/discounts/update-condition.ts

@@ -50,6 +50,35 @@ import { validator } from "../../../../utils/validator"
  *              description: list of customer group IDs if the condition is applied on customer groups.
  *              items:
  *                type: string
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.discounts.updateCondition(discount_id, condition_id, {
+ *         products: [
+ *           product_id
+ *         ]
+ *       })
+ *       .then(({ discount }) => {
+ *         console.log(discount.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}/conditions/{condition}' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "products": [
+ *              "prod_01G1G5V2MBA328390B5AXJ610F"
+ *           ]
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Discount
  * responses:
@@ -61,6 +90,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             discount:
  *               $ref: "#/components/schemas/discount"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 
 export default async (req, res) => {

packages/medusa/src/api/routes/admin/discounts/update-discount.ts

@@ -127,6 +127,31 @@ import { validator } from "../../../../utils/validator"
  *           metadata:
  *              description: An object containing metadata of the discount
  *              type: object
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.discounts.update(discount_id, {
+ *         code: 'TEST'
+ *       })
+ *       .then(({ discount }) => {
+ *         console.log(discount.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "code": "TEST"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Discount
  * responses:
@@ -138,6 +163,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             discount:
  *               $ref: "#/components/schemas/discount"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { discount_id } = req.params

packages/medusa/src/api/routes/admin/draft-orders/create-draft-order.ts

@@ -116,6 +116,53 @@ import { validator } from "../../../../utils/validator"
  *           metadata:
  *             description: The optional key-value map with additional details about the Draft Order.
  *             type: object
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.draftOrders.create({
+ *         email: 'user@example.com',
+ *         region_id,
+ *         items: [
+ *           {
+ *             quantity: 1
+ *           }
+ *         ],
+ *         shipping_methods: [
+ *           {
+ *             option_id
+ *           }
+ *         ],
+ *       })
+ *       .then(({ draft_order }) => {
+ *         console.log(draft_order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/draft-orders' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "email": "user@example.com",
+ *           "region_id": "{region_id}"
+ *           "items": [
+ *              {
+ *                "quantity": 1
+ *              }
+ *           ],
+ *           "shipping_methods": [
+ *              {
+ *                "option_id": "{option_id}"
+ *              }
+ *           ]
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Draft Order
  * responses:
@@ -127,6 +174,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             draft_order:
  *               $ref: "#/components/schemas/draft-order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 
 export default async (req, res) => {

packages/medusa/src/api/routes/admin/draft-orders/create-line-item.ts

@@ -52,6 +52,31 @@ import { validator } from "../../../../utils/validator"
  *           metadata:
  *             description: The optional key-value map with additional details about the Line Item.
  *             type: object
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.draftOrders.addLineItem(draft_order_id, {
+ *         quantity: 1
+ *       })
+ *       .then(({ draft_order }) => {
+ *         console.log(draft_order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}/line-items' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "quantity": 1
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Draft Order
  * responses:
@@ -63,6 +88,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             draft_order:
  *               $ref: "#/components/schemas/draft-order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 
 export default async (req, res) => {

packages/medusa/src/api/routes/admin/draft-orders/delete-draft-order.ts

@@ -8,6 +8,25 @@ import { EntityManager } from "typeorm"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Draft Order.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.draftOrders.delete(draft_order_id)
+ *       .then(({ id, object, deleted }) => {
+ *         console.log(id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request DELETE 'https://medusa-url.com/admin/draft-orders/{id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Draft Order
  * responses:
@@ -28,6 +47,18 @@ import { EntityManager } from "typeorm"
  *               type: boolean
  *               description: Whether the draft order was deleted successfully or not.
  *               default: true
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/draft-orders/delete-line-item.ts

@@ -18,6 +18,25 @@ import { MedusaError } from "medusa-core-utils"
  * parameters:
  *   - (path) id=* {string} The ID of the Draft Order.
  *   - (path) line_id=* {string} The ID of the Draft Order.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.draftOrders.removeLineItem(draft_order_id, item_id)
+ *       .then(({ draft_order }) => {
+ *         console.log(draft_order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request DELETE 'https://medusa-url.com/admin/draft-orders/{id}/line-items/{line_id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Draft Order
  * responses:
@@ -29,6 +48,18 @@ import { MedusaError } from "medusa-core-utils"
  *           properties:
  *             draft_order:
  *               $ref: "#/components/schemas/draft-order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 
 export default async (req, res) => {

packages/medusa/src/api/routes/admin/draft-orders/get-draft-order.ts

@@ -16,6 +16,25 @@ import { DraftOrder } from "../../../.."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Draft Order.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.draftOrders.retrieve(draft_order_id)
+ *       .then(({ draft_order }) => {
+ *         console.log(draft_order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/draft-orders/{id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Draft Order
  * responses:
@@ -27,6 +46,18 @@ import { DraftOrder } from "../../../.."
  *           properties:
  *             draft_order:
  *               $ref: "#/components/schemas/draft-order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 
 export default async (req, res) => {

packages/medusa/src/api/routes/admin/draft-orders/list-draft-orders.ts

@@ -21,6 +21,25 @@ import { validator } from "../../../../utils/validator"
  *   - (query) offset=0 {number} The number of items to skip before the results.
  *   - (query) limit=50 {number} Limit the number of items returned.
  *   - (query) q {string} a search term to search emails in carts associated with draft orders and display IDs of draft orders
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.draftOrders.list()
+ *       .then(({ draft_orders, limit, offset, count }) => {
+ *         console.log(draft_orders.length);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/draft-orders' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Draft Order
  * responses:
@@ -43,6 +62,18 @@ import { validator } from "../../../../utils/validator"
  *             limit:
  *               type: integer
  *               description: The number of items per page
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 
 export default async (req, res) => {

packages/medusa/src/api/routes/admin/draft-orders/register-payment.ts

@@ -19,6 +19,25 @@ import { EntityManager } from "typeorm"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {String} The Draft Order id.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.draftOrders.markPaid(draft_order_id)
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}/pay' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Draft Order
  * responses:
@@ -30,6 +49,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/draft-order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 
 export default async (req, res) => {

packages/medusa/src/api/routes/admin/draft-orders/update-draft-order.ts

@@ -68,6 +68,31 @@ import { validator } from "../../../../utils/validator"
  *           customer_id:
  *             description: "The ID of the Customer to associate the Draft Order with."
  *             type: string
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.draftOrders.update(draft_order_id, {
+ *         email: "user@example.com"
+ *       })
+ *       .then(({ draft_order }) => {
+ *         console.log(draft_order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "email": "user@example.com"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Draft Order
  * responses:
@@ -79,6 +104,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             draft_order:
  *               $ref: "#/components/schemas/draft-order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 
 export default async (req, res) => {

packages/medusa/src/api/routes/admin/draft-orders/update-line-item.ts

@@ -38,6 +38,31 @@ import { validator } from "../../../../utils/validator"
  *           metadata:
  *             description: The optional key-value map with additional details about the Line Item.
  *             type: object
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.draftOrders.updateLineItem(draft_order_id, line_id, {
+ *         quantity: 1
+ *       })
+ *       .then(({ draft_order }) => {
+ *         console.log(draft_order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/draft-orders/{id}/line-items/{line_id}' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "quantity": 1
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Draft Order
  * responses:
@@ -49,6 +74,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             draft_order:
  *               $ref: "#/components/schemas/draft-order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 
 export default async (req, res) => {

packages/medusa/src/api/routes/admin/gift-cards/create-gift-card.ts

@@ -35,6 +35,31 @@ import { EntityManager } from "typeorm"
  *           metadata:
  *             description: An optional set of key-value pairs to hold additional information.
  *             type: object
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.giftCards.create({
+ *         region_id
+ *       })
+ *       .then(({ gift_card }) => {
+ *         console.log(gift_card.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/gift-cards' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "region_id": "{region_id}"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Gift Card
  * responses:
@@ -46,6 +71,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             gift_card:
  *               $ref: "#/components/schemas/gift_card"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const validated = await validator(AdminPostGiftCardsReq, req.body)

packages/medusa/src/api/routes/admin/gift-cards/delete-gift-card.ts

@@ -8,6 +8,25 @@ import { EntityManager } from "typeorm"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Gift Card to delete.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.giftCards.delete(gift_card_id)
+ *       .then(({ id, object, deleted }) => {
+ *         console.log(id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request DELETE 'https://medusa-url.com/admin/gift-cards/{id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Gift Card
  * responses:
@@ -28,6 +47,18 @@ import { EntityManager } from "typeorm"
  *               type: boolean
  *               description: Whether the gift card was deleted successfully or not.
  *               default: true
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/gift-cards/get-gift-card.ts

@@ -8,6 +8,25 @@ import { defaultAdminGiftCardFields, defaultAdminGiftCardRelations } from "./"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Gift Card.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.giftCards.retrieve(gift_card_id)
+ *       .then(({ gift_card }) => {
+ *         console.log(gift_card.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/gift-cards/{id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Gift Card
  * responses:
@@ -19,6 +38,18 @@ import { defaultAdminGiftCardFields, defaultAdminGiftCardRelations } from "./"
  *           properties:
  *             gift_card:
  *               $ref: "#/components/schemas/gift_card"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/gift-cards/list-gift-cards.ts

@@ -16,6 +16,25 @@ import { isDefined } from "../../../../utils"
  *   - (query) offset=0 {number} The number of items to skip before the results.
  *   - (query) limit=50 {number} Limit the number of items returned.
  *   - (query) q {string} a search term to search by code or display ID
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.giftCards.list()
+ *       .then(({ gift_cards, limit, offset, count }) => {
+ *         console.log(gift_cards.length);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/gift-cards' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Gift Card
  * responses:
@@ -38,6 +57,18 @@ import { isDefined } from "../../../../utils"
  *             limit:
  *               type: integer
  *               description: The number of items per page
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const validated = await validator(AdminGetGiftCardsParams, req.query)

packages/medusa/src/api/routes/admin/gift-cards/update-gift-card.ts

@@ -35,6 +35,31 @@ import { EntityManager } from "typeorm"
  *           metadata:
  *             description: An optional set of key-value pairs to hold additional information.
  *             type: object
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.giftCards.update(gift_card_id, {
+ *         region_id
+ *       })
+ *       .then(({ gift_card }) => {
+ *         console.log(gift_card.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/gift-cards/{id}' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "region_id": "{region_id}"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Gift Card
  * responses:
@@ -46,6 +71,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             gift_card:
  *               $ref: "#/components/schemas/gift_card"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/invites/accept-invite.ts

@@ -39,11 +39,61 @@ import { EntityManager } from "typeorm"
  *                 description: The desired password for the User
  *                 type: string
  *                 format: password
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.invites.accept({
+ *         token,
+ *         user: {
+ *           first_name: 'Brigitte',
+ *           last_name: 'Collier',
+ *           password: 'supersecret'
+ *         }
+ *       })
+ *       .then(() => {
+ *         // successful
+ *       })
+ *       .catch(() => {
+ *         // an error occurred
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/invites/accept' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "token": "{token}",
+ *           "user": {
+ *             "first_name": "Brigitte",
+ *             "last_name": "Collier",
+ *             "password": "supersecret"
+ *           }
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Invite
  * responses:
  *   200:
  *     description: OK
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const validated = await validator(AdminPostInvitesInviteAcceptReq, req.body)

packages/medusa/src/api/routes/admin/invites/create-invite.ts

@@ -27,11 +27,53 @@ import { EntityManager } from "typeorm"
  *             description: "The role of the user to be created."
  *             type: string
  *             enum: [admin, member, developer]
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.invites.create({
+ *         user: "user@example.com",
+ *         role: "admin"
+ *       })
+ *       .then(() => {
+ *         // successful
+ *       })
+ *       .catch(() => {
+ *         // an error occurred
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/invites' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "user": "user@example.com",
+ *           "role": "admin"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Invite
  * responses:
  *   200:
  *     description: OK
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const validated = await validator(AdminPostInvitesReq, req.body)

packages/medusa/src/api/routes/admin/invites/delete-invite.ts

@@ -9,6 +9,25 @@ import InviteService from "../../../../services/invite"
  * x-authenticated: true
  * parameters:
  *   - (path) invite_id=* {string} The ID of the Invite
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.invites.delete(invite_id)
+ *       .then(({ id, object, deleted }) => {
+ *         console.log(id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request DELETE 'https://medusa-url.com/admin/invites/{invite_id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Invite
  * responses:
@@ -29,6 +48,18 @@ import InviteService from "../../../../services/invite"
  *               type: boolean
  *               description: Whether or not the Invite was deleted.
  *               default: true
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { invite_id } = req.params

packages/medusa/src/api/routes/admin/invites/list-invites.ts

@@ -6,6 +6,25 @@ import InviteService from "../../../../services/invite"
  * summary: "Lists all Invites"
  * description: "Lists all Invites"
  * x-authenticated: true
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.invites.list()
+ *       .then(({ invites }) => {
+ *         console.log(invites.length);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/invites' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Invite
  * responses:
@@ -19,6 +38,18 @@ import InviteService from "../../../../services/invite"
  *               type: array
  *               items:
  *                 $ref: "#/components/schemas/invite"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const inviteService: InviteService = req.scope.resolve("inviteService")

packages/medusa/src/api/routes/admin/invites/resend-invite.ts

@@ -9,11 +9,45 @@ import { EntityManager } from "typeorm"
  * x-authenticated: true
  * parameters:
  *   - (path) invite_id=* {string} The ID of the Invite
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.invites.resend(invite_id)
+ *       .then(() => {
+ *         // successful
+ *       })
+ *       .catch(() => {
+ *         // an error occurred
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/invites/{invite_id}/resend' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Invite
  * responses:
  *   200:
  *     description: OK
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { invite_id } = req.params

packages/medusa/src/api/routes/admin/notes/create-note.ts

@@ -28,6 +28,35 @@ import { EntityManager } from "typeorm"
  *          value:
  *            type: string
  *            description: The content of the Note to create.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.notes.create({
+ *         resource_id,
+ *         resource_type: 'order',
+ *         value: 'We delivered this order'
+ *       })
+ *       .then(({ note }) => {
+ *         console.log(note.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/notes' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "resource_id": "{resource_id}",
+ *           "resource_type": "order",
+ *           "value": "We delivered this order"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Note
  * responses:
@@ -39,6 +68,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             note:
  *               $ref: "#/components/schemas/note"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  *
  */
 export default async (req, res) => {

packages/medusa/src/api/routes/admin/notes/delete-note.ts

@@ -9,6 +9,25 @@ import NoteService from "../../../../services/note"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Note to delete.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.notes.delete(note_id)
+ *       .then(({ id, object, deleted }) => {
+ *         console.log(id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request DELETE 'https://medusa-url.com/admin/notes/{id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Note
  * responses:
@@ -29,6 +48,18 @@ import NoteService from "../../../../services/note"
  *               type: boolean
  *               description: Whether or not the Note was deleted.
  *               default: true
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/notes/get-note.ts

@@ -8,6 +8,25 @@ import NoteService from "../../../../services/note"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the note to retrieve.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.notes.retrieve(note_id)
+ *       .then(({ note }) => {
+ *         console.log(note.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/notes/{id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Note
  * responses:
@@ -19,6 +38,18 @@ import NoteService from "../../../../services/note"
  *           properties:
  *             note:
  *               $ref: "#/components/schemas/note"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/notes/list-notes.ts

@@ -15,6 +15,25 @@ import { validator } from "../../../../utils/validator"
  *   - (query) limit=50 {number} The number of notes to get
  *   - (query) offset=0 {number} The offset at which to get notes
  *   - (query) resource_id {string} The ID which the notes belongs to
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.notes.list()
+ *       .then(({ notes, limit, offset, count }) => {
+ *         console.log(notes.length);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/notes' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Note
  * responses:
@@ -37,6 +56,18 @@ import { validator } from "../../../../utils/validator"
  *             limit:
  *               type: integer
  *               description: The number of items per page
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const validated = await validator(AdminGetNotesParams, req.query)

packages/medusa/src/api/routes/admin/notes/update-note.ts

@@ -21,6 +21,31 @@ import { EntityManager } from "typeorm"
  *          value:
  *            type: string
  *            description: The updated description of the Note.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.notes.update(note_id, {
+ *        value: 'We delivered this order'
+ *       })
+ *       .then(({ note }) => {
+ *         console.log(note.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/notes/{id}' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "value": "We delivered this order"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Note
  * responses:
@@ -32,7 +57,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             note:
  *               $ref: "#/components/schemas/note"
- *
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/notifications/list-notifications.ts

@@ -27,6 +27,25 @@ import { validator } from "../../../../utils/validator"
  *   - (query) resource_id {string} The ID of the resource that the Notification refers to.
  *   - (query) to {string} The address that the Notification was sent to. This will usually be an email address, but represent other addresses such as a chat bot user id
  *   - (query) include_resends {string} A boolean indicating whether the result set should include resent notifications or not
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.notifications.list()
+ *       .then(({ notifications }) => {
+ *         console.log(notifications.length);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/notifications' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Notification
  * responses:
@@ -40,6 +59,18 @@ import { validator } from "../../../../utils/validator"
  *               type: array
  *               items:
  *                 $ref: "#/components/schemas/notification"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const notificationService: NotificationService = req.scope.resolve(

packages/medusa/src/api/routes/admin/notifications/resend-notification.ts

@@ -26,6 +26,25 @@ import { validator } from "../../../../utils/validator"
  *           to:
  *             description: "A new address or user identifier that the Notification should be sent to"
  *             type: string
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.notifications.resend(notification_id)
+ *       .then(({ notification }) => {
+ *         console.log(notification.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/notifications/{id}/resend' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Notification
  * responses:
@@ -37,6 +56,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             notification:
  *               $ref: "#/components/schemas/notification"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/orders/add-shipping-method.ts

@@ -22,6 +22,33 @@ import { EntityManager } from "typeorm"
  *   - (body) price=* {integer} The price (excluding VAT) that should be charged for the Shipping Method
  *   - (body) option_id=* {string} The ID of the Shipping Option to create the Shipping Method from.
  *   - (body) data {object} The data required for the Shipping Option to create a Shipping Method. This will depend on the Fulfillment Provider.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.addShippingMethod(order_id, {
+ *         price: 1000,
+ *         option_id
+ *       })
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/shipping-methods' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "price": 1000,
+ *           "option_id": "{option_id}"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Order
  * responses:
@@ -33,6 +60,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/orders/archive-order.ts

@@ -9,6 +9,25 @@ import { EntityManager } from "typeorm"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Order.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.archive(order_id)
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/archive' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Order
  * responses:
@@ -20,6 +39,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/orders/cancel-claim.ts

@@ -13,6 +13,25 @@ import { MedusaError } from "medusa-core-utils"
  * parameters:
  *   - (path) id=* {string} The ID of the Order.
  *   - (path) claim_id=* {string} The ID of the Claim.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.cancelClaim(order_id, claim_id)
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/cancel' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Claim
  * responses:
@@ -24,6 +43,18 @@ import { MedusaError } from "medusa-core-utils"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id, claim_id } = req.params

packages/medusa/src/api/routes/admin/orders/cancel-fulfillment-claim.ts

@@ -18,6 +18,25 @@ import { MedusaError } from "medusa-core-utils"
  *   - (path) id=* {string} The ID of the Order which the Claim relates to.
  *   - (path) claim_id=* {string} The ID of the Claim which the Fulfillment relates to.
  *   - (path) fulfillment_id=* {string} The ID of the Fulfillment.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.cancelClaimFulfillment(order_id, claim_id, fulfillment_id)
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/fulfillments/{fulfillment_id}/cancel' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Fulfillment
  * responses:
@@ -29,6 +48,18 @@ import { MedusaError } from "medusa-core-utils"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id, claim_id, fulfillment_id } = req.params

packages/medusa/src/api/routes/admin/orders/cancel-fulfillment-swap.ts

@@ -18,6 +18,25 @@ import { MedusaError } from "medusa-core-utils"
  *   - (path) id=* {string} The ID of the Order which the Swap relates to.
  *   - (path) swap_id=* {string} The ID of the Swap which the Fulfillment relates to.
  *   - (path) fulfillment_id=* {string} The ID of the Fulfillment.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.cancelSwapFulfillment(order_id, swap_id, fulfillment_id)
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/fulfillments/{fulfillment_id}/cancel' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Fulfillment
  * responses:
@@ -29,6 +48,18 @@ import { MedusaError } from "medusa-core-utils"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id, swap_id, fulfillment_id } = req.params

packages/medusa/src/api/routes/admin/orders/cancel-fulfillment.ts

@@ -13,6 +13,25 @@ import { MedusaError } from "medusa-core-utils"
  * parameters:
  *   - (path) id=* {string} The ID of the Order which the Fulfillment relates to.
  *   - (path) fulfillment_id=* {string} The ID of the Fulfillment
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.cancelFulfillment(order_id, fulfillment_id)
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/fulfillments/{fulfillment_id}/cancel' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Fulfillment
  * responses:
@@ -24,6 +43,18 @@ import { MedusaError } from "medusa-core-utils"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id, fulfillment_id } = req.params

packages/medusa/src/api/routes/admin/orders/cancel-order.ts

@@ -11,6 +11,25 @@ import { EntityManager } from "typeorm"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Order.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.cancel(order_id)
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/cancel' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Order
  * responses:
@@ -22,6 +41,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/orders/cancel-swap.ts

@@ -13,6 +13,25 @@ import { MedusaError } from "medusa-core-utils"
  * parameters:
  *   - (path) id=* {string} The ID of the Order.
  *   - (path) swap_id=* {string} The ID of the Swap.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.cancelSwap(order_id, swap_id)
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{order_id}/swaps/{swap_id}/cancel' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Swap
  * responses:
@@ -24,6 +43,18 @@ import { MedusaError } from "medusa-core-utils"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id, swap_id } = req.params

packages/medusa/src/api/routes/admin/orders/capture-payment.ts

@@ -11,6 +11,25 @@ import { EntityManager } from "typeorm"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Order.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.capturePayment(order_id)
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/capture' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Order
  * responses:
@@ -22,6 +41,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/orders/complete-order.ts

@@ -9,6 +9,25 @@ import { EntityManager } from "typeorm"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Order.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.complete(order_id)
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/complete' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Order
  * responses:
@@ -20,6 +39,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/orders/create-claim-shipment.ts

@@ -29,6 +29,31 @@ import { EntityManager } from "typeorm"
  *             type: array
  *             items:
  *               type: string
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.createClaimShipment(order_id, claim_id, {
+ *         fulfillment_id
+ *       })
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/shipments' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "fulfillment_id": "{fulfillment_id}"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Claim
  * responses:
@@ -40,6 +65,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id, claim_id } = req.params

packages/medusa/src/api/routes/admin/orders/create-claim.ts

@@ -126,6 +126,43 @@ import { validator } from "../../../../utils/validator"
  *           metadata:
  *              description: An optional set of key-value pairs to hold additional information.
  *              type: object
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.createClaim(order_id, {
+ *         type: 'refund',
+ *         claim_items: [
+ *           {
+ *             item_id,
+ *             quantity: 1
+ *           }
+ *         ]
+ *       })
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "type": "refund",
+ *           "claim_items": [
+ *             {
+ *               "item_id": "asdsd",
+ *               "quantity": 1
+ *             }
+ *           ]
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Claim
  * responses:
@@ -137,6 +174,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 
 export default async (req, res) => {

packages/medusa/src/api/routes/admin/orders/create-fulfillment.ts

@@ -50,6 +50,41 @@ import { validator } from "../../../../utils/validator"
  *           metadata:
  *             description: An optional set of key-value pairs to hold additional information.
  *             type: object
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.createFulfillment(order_id, {
+ *         items: [
+ *           {
+ *             item_id,
+ *             quantity: 1
+ *           }
+ *         ]
+ *       })
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/fulfillment' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "items": [
+ *             {
+ *               "item_id": "{item_id}",
+ *               "quantity": 1
+ *             }
+ *           ]
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Fulfillment
  * responses:
@@ -61,6 +96,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/orders/create-shipment.ts

@@ -38,6 +38,31 @@ import { validator } from "../../../../utils/validator"
  *           no_notification:
  *             description: If set to true no notification will be send related to this Shipment.
  *             type: boolean
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.createShipment(order_id, {
+ *         fulfillment_id
+ *       })
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/shipment' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "fulfillment_id": "{fulfillment_id}"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Order
  * responses:
@@ -49,6 +74,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/orders/create-swap-shipment.ts

@@ -38,6 +38,31 @@ import { validator } from "../../../../utils/validator"
  *           no_notification:
  *             description: If set to true no notification will be send related to this Claim.
  *             type: boolean
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.createSwapShipment(order_id, swap_id, {
+ *         fulfillment_id
+ *       })
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/shipments' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "fulfillment_id": "{fulfillment_id}"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Swap
  * responses:
@@ -49,6 +74,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id, swap_id } = req.params

packages/medusa/src/api/routes/admin/orders/create-swap.ts

@@ -105,6 +105,41 @@ import { validator } from "../../../../utils/validator"
  *             description: If true, swaps can be completed with items out of stock
  *             type: boolean
  *             default: true
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.createSwap(order_id, {
+ *         return_items: [
+ *           {
+ *             item_id,
+ *             quantity: 1
+ *           }
+ *         ]
+ *       })
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "return_items": [
+ *             {
+ *               "item_id": "asfasf",
+ *               "quantity": 1
+ *             }
+ *           ]
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Swap
  * responses:
@@ -116,6 +151,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/orders/fulfill-claim.ts

@@ -25,6 +25,25 @@ import { validator } from "../../../../utils/validator"
  *           no_notification:
  *             description: If set to true no notification will be send related to this Claim.
  *             type: boolean
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.fulfillClaim(order_id, claim_id)
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}/fulfillments' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Fulfillment
  * responses:
@@ -36,6 +55,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id, claim_id } = req.params

packages/medusa/src/api/routes/admin/orders/fulfill-swap.ts

@@ -25,6 +25,25 @@ import { validator } from "../../../../utils/validator"
  *           no_notification:
  *             description: If set to true no notification will be send related to this Claim.
  *             type: boolean
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.fulfillSwap(order_id, swap_id)
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/fulfillments' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Fulfillment
  * responses:
@@ -36,6 +55,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id, swap_id } = req.params

packages/medusa/src/api/routes/admin/orders/get-order.ts

@@ -8,6 +8,25 @@ import { OrderService } from "../../../../services"
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Order.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.retrieve(order_id)
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/orders/{id}' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Order
  * responses:
@@ -19,6 +38,18 @@ import { OrderService } from "../../../../services"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/orders/list-orders.ts

@@ -153,6 +153,25 @@ import { pick } from "lodash"
  *   - (query) limit=50 {integer} Limit the number of orders returned.
  *   - (query) expand {string} (Comma separated) Which fields should be expanded in each order of the result.
  *   - (query) fields {string} (Comma separated) Which fields should be included in each order of the result.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.list()
+ *       .then(({ orders, limit, offset, count }) => {
+ *         console.log(orders.length);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request GET 'https://medusa-url.com/admin/orders' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Order
  * responses:
@@ -175,6 +194,18 @@ import { pick } from "lodash"
  *             limit:
  *               type: integer
  *               description: The number of items per page
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const orderService: OrderService = req.scope.resolve("orderService")

packages/medusa/src/api/routes/admin/orders/process-swap-payment.ts

@@ -12,6 +12,25 @@ import { EntityManager } from "typeorm"
  * parameters:
  *   - (path) id=* {string} The ID of the Order.
  *   - (path) swap_id=* {string} The ID of the Swap.
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.processSwapPayment(order_id, swap_id)
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/swaps/{swap_id}/process-payment' \
+ *       --header 'Authorization: Bearer {api_token}'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Swap
  * responses:
@@ -23,6 +42,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id, swap_id } = req.params

packages/medusa/src/api/routes/admin/orders/refund-payment.ts

@@ -39,6 +39,33 @@ import { EntityManager } from "typeorm"
  *           no_notification:
  *             description: If set to true no notification will be send related to this Refund.
  *             type: boolean
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.refundPayment(order_id, {
+ *         amount: 1000,
+ *         reason: 'Do not like it'
+ *       })
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/adasda/refund' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "amount": 1000,
+ *           "reason": "Do not like it"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Order
  * responses:
@@ -50,6 +77,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/orders/request-return.ts

@@ -79,6 +79,41 @@ import { validator } from "../../../../utils/validator"
  *           refund:
  *             description: The amount to refund.
  *             type: integer
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.requestReturn(order_id, {
+ *         items: [
+ *           {
+ *             item_id,
+ *             quantity: 1
+ *           }
+ *         ]
+ *       })
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/return' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "items": [
+ *             {
+ *               "item_id": "{item_id}",
+ *               "quantity": 1
+ *             }
+ *           ]
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Return
  *   - Order
@@ -91,6 +126,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id } = req.params

packages/medusa/src/api/routes/admin/orders/update-claim.ts

@@ -105,6 +105,31 @@ import { EntityManager } from "typeorm"
  *           metadata:
  *             description: An optional set of key-value pairs to hold additional information.
  *             type: object
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.updateClaim(order_id, claim_id, {
+ *         no_notification: true
+ *       })
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "no_notification": true
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Claim
  * responses:
@@ -116,6 +141,18 @@ import { EntityManager } from "typeorm"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
   const { id, claim_id } = req.params

packages/medusa/src/api/routes/admin/orders/update-order.ts

@@ -90,6 +90,31 @@ import { validator } from "../../../../utils/validator"
  *           no_notification:
  *             description: A flag to indicate if no notifications should be emitted related to the updated order.
  *             type: boolean
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.update(order_id, {
+ *         email: 'user@example.com'
+ *       })
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/adasda' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "email": "user@example.com"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
  * tags:
  *   - Order
  * responses:
@@ -101,6 +126,18 @@ import { validator } from "../../../../utils/validator"
  *           properties:
  *             order:
  *               $ref: "#/components/schemas/order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
  */
 
 export default async (req, res) => {