chore(docs): Generated API Reference (#2572)

Co-authored-by: shahednasser <shahednasser@users.noreply.github.com>

docs/api/admin/paths/admin_draft-orders_{id}.yaml

@@ -31,10 +31,14 @@ post:
               format: email
             billing_address:
               description: The Address to be used for billing purposes.
-              $ref: ../components/schemas/address_fields.yaml
+              anyOf:
+                - $ref: ../components/schemas/address_fields.yaml
+                - type: string
             shipping_address:
               description: The Address to be used for shipping.
-              $ref: ../components/schemas/address_fields.yaml
+              anyOf:
+                - $ref: ../components/schemas/address_fields.yaml
+                - type: string
             discounts:
               description: An array of Discount codes to add to the Draft Order.
               type: array

docs/api/admin/paths/collections.yaml

@@ -91,6 +91,11 @@ get:
       description: a search term to search titles and handles.
       schema:
         type: string
+    - in: query
+      name: discount_condition_id
+      description: The discount condition id on which to filter the product collections.
+      schema:
+        type: string
     - in: query
       name: created_at
       description: Date comparison for when resulting collections were created.

docs/api/admin/paths/currencies.yaml

@@ -16,19 +16,30 @@ get:
         type: boolean
     - in: query
       name: order
-      description: to retrieve products in.
+      description: order to retrieve products in.
       schema:
         type: string
     - in: query
       name: offset
       description: How many products to skip in the result.
       schema:
-        type: string
+        type: number
+        default: '0'
     - in: query
       name: limit
       description: Limit the number of products returned.
       schema:
-        type: string
+        type: number
+        default: '20'
+  x-codeSamples:
+    - lang: JavaScript
+      label: JS Client
+      source:
+        $ref: ../code_samples/JavaScript/currencies/getundefined
+    - lang: Shell
+      label: cURL
+      source:
+        $ref: ../code_samples/Shell/currencies/getundefined
   tags:
     - Currency
   responses:
@@ -38,16 +49,16 @@ get:
         application/json:
           schema:
             properties:
-              count:
-                description: The number of Currency.
-                type: integer
-              offset:
-                description: The offset of the Currency query.
-                type: integer
-              limit:
-                description: The limit of the currency query.
-                type: integer
               currencies:
                 type: array
                 items:
                   $ref: ../components/schemas/currency.yaml
+              count:
+                type: integer
+                description: The total number of items available
+              offset:
+                type: integer
+                description: The number of items skipped before these items
+              limit:
+                type: integer
+                description: The number of items per page

docs/api/admin/paths/currencies_{code}.yaml

@@ -18,6 +18,15 @@ post:
             includes_tax:
               type: boolean
               description: '[EXPERIMENTAL] Tax included in prices of currency.'
+  x-codeSamples:
+    - lang: JavaScript
+      label: JS Client
+      source:
+        $ref: ../code_samples/JavaScript/currencies_{code}/postundefined
+    - lang: Shell
+      label: cURL
+      source:
+        $ref: ../code_samples/Shell/currencies_{code}/postundefined
   tags:
     - Currency
   responses:

docs/api/admin/paths/customer-groups.yaml

@@ -75,6 +75,11 @@ get:
       description: the field used to order the customer groups.
       schema:
         type: string
+    - in: query
+      name: discount_condition_id
+      description: The discount condition id on which to filter the customer groups.
+      schema:
+        type: string
     - in: query
       name: id
       style: form

docs/api/admin/paths/discounts_{discount_id}_conditions_{condition_id}_batch.yaml

@@ -0,0 +1,172 @@
+post:
+  operationId: PostDiscountsDiscountConditionsConditionBatch
+  summary: Add a batch of resources to a discount condition
+  description: Add a batch of resources to a discount condition.
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: discount_id
+      required: true
+      description: The ID of the Product.
+      schema:
+        type: string
+    - in: path
+      name: condition_id
+      required: true
+      description: The ID of the condition on which to add the item.
+      schema:
+        type: string
+    - in: query
+      name: expand
+      description: >-
+        (Comma separated) Which relations should be expanded in each discount of
+        the result.
+      schema:
+        type: string
+    - in: query
+      name: fields
+      description: >-
+        (Comma separated) Which fields should be included in each discount of
+        the result.
+      schema:
+        type: string
+  requestBody:
+    content:
+      application/json:
+        schema:
+          required:
+            - resources
+          properties:
+            resources:
+              description: The resources to be added to the discount condition
+              type: array
+              items:
+                required:
+                  - id
+                properties:
+                  id:
+                    description: The id of the item
+                    type: string
+  x-codeSamples:
+    - lang: JavaScript
+      label: JS Client
+      source:
+        $ref: >-
+          ../code_samples/JavaScript/discounts_{discount_id}_conditions_{condition_id}_batch/postundefined
+    - lang: Shell
+      label: cURL
+      source:
+        $ref: >-
+          ../code_samples/Shell/discounts_{discount_id}_conditions_{condition_id}_batch/postundefined
+  security:
+    - api_token: []
+    - cookie_auth: []
+  tags:
+    - Discount Condition
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              discount:
+                $ref: ../components/schemas/discount.yaml
+    '400':
+      $ref: ../components/responses/400_error.yaml
+    '401':
+      $ref: ../components/responses/unauthorized.yaml
+    '404':
+      $ref: ../components/responses/not_found_error.yaml
+    '409':
+      $ref: ../components/responses/invalid_state_error.yaml
+    '422':
+      $ref: ../components/responses/invalid_request_error.yaml
+    '500':
+      $ref: ../components/responses/500_error.yaml
+delete:
+  operationId: DeleteDiscountsDiscountConditionsConditionBatch
+  summary: Delete a batch of resources from a discount condition
+  description: Delete a batch of resources from a discount condition.
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: discount_id
+      required: true
+      description: The ID of the Product.
+      schema:
+        type: string
+    - in: path
+      name: condition_id
+      required: true
+      description: The ID of the condition on which to add the item.
+      schema:
+        type: string
+    - in: query
+      name: expand
+      description: >-
+        (Comma separated) Which relations should be expanded in each discount of
+        the result.
+      schema:
+        type: string
+    - in: query
+      name: fields
+      description: >-
+        (Comma separated) Which fields should be included in each discount of
+        the result.
+      schema:
+        type: string
+  requestBody:
+    content:
+      application/json:
+        schema:
+          required:
+            - resources
+          properties:
+            resources:
+              description: The resources to be deleted from the discount condition
+              type: array
+              items:
+                required:
+                  - id
+                properties:
+                  id:
+                    description: The id of the item
+                    type: string
+  x-codeSamples:
+    - lang: JavaScript
+      label: JS Client
+      source:
+        $ref: >-
+          ../code_samples/JavaScript/discounts_{discount_id}_conditions_{condition_id}_batch/deleteundefined
+    - lang: Shell
+      label: cURL
+      source:
+        $ref: >-
+          ../code_samples/Shell/discounts_{discount_id}_conditions_{condition_id}_batch/deleteundefined
+  security:
+    - api_token: []
+    - cookie_auth: []
+  tags:
+    - Discount Condition
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              discount:
+                $ref: ../components/schemas/discount.yaml
+    '400':
+      $ref: ../components/responses/400_error.yaml
+    '401':
+      $ref: ../components/responses/unauthorized.yaml
+    '404':
+      $ref: ../components/responses/not_found_error.yaml
+    '409':
+      $ref: ../components/responses/invalid_state_error.yaml
+    '422':
+      $ref: ../components/responses/invalid_request_error.yaml
+    '500':
+      $ref: ../components/responses/500_error.yaml

docs/api/admin/paths/draft-orders.yaml

@@ -25,10 +25,14 @@ post:
               format: email
             billing_address:
               description: The Address to be used for billing purposes.
-              $ref: ../components/schemas/address_fields.yaml
+              anyOf:
+                - $ref: ../components/schemas/address_fields.yaml
+                - type: string
             shipping_address:
               description: The Address to be used for shipping.
-              $ref: ../components/schemas/address_fields.yaml
+              anyOf:
+                - $ref: ../components/schemas/address_fields.yaml
+                - type: string
             items:
               description: The Line Items that have been received.
               type: array

docs/api/admin/paths/order-edits.yaml

@@ -2,6 +2,19 @@ post:
   operationId: PostOrderEdits
   summary: Create an OrderEdit
   description: Creates an OrderEdit.
+  requestBody:
+    content:
+      application/json:
+        schema:
+          required:
+            - order_id
+          properties:
+            order_id:
+              description: The ID of the order to create the edit for.
+              type: string
+            internal_note:
+              description: An optional note to create for the order edit.
+              type: string
   x-authenticated: true
   x-codeSamples:
     - lang: JavaScript
@@ -38,3 +51,86 @@ post:
       $ref: ../components/responses/invalid_request_error.yaml
     '500':
       $ref: ../components/responses/500_error.yaml
+get:
+  operationId: GetOrderEdits
+  summary: List an OrderEdit
+  description: List a OrderEdit.
+  x-authenticated: true
+  parameters:
+    - in: query
+      name: q
+      description: Query used for searching order edit internal note.
+      schema:
+        type: string
+    - in: query
+      name: order_id
+      description: List order edits by order id.
+      schema:
+        type: string
+    - in: query
+      name: limit
+      description: The number of items in the response
+      schema:
+        type: number
+        default: '20'
+    - in: query
+      name: offset
+      description: The offset of items in response
+      schema:
+        type: number
+        default: '0'
+    - in: query
+      name: expand
+      description: Comma separated list of relations to include in the results.
+      schema:
+        type: string
+    - in: query
+      name: fields
+      description: Comma separated list of fields to include in the results.
+      schema:
+        type: string
+  x-codeSamples:
+    - lang: JavaScript
+      label: JS Client
+      source:
+        $ref: ../code_samples/JavaScript/order-edits/getundefined
+    - lang: Shell
+      label: cURL
+      source:
+        $ref: ../code_samples/Shell/order-edits/getundefined
+  security:
+    - api_token: []
+    - cookie_auth: []
+  tags:
+    - OrderEdit
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              order_edits:
+                type: array
+                $ref: ../components/schemas/order_edit.yaml
+              count:
+                type: integer
+                description: The total number of items available
+              offset:
+                type: integer
+                description: The number of items skipped before these items
+              limit:
+                type: integer
+                description: The number of items per page
+    '400':
+      $ref: ../components/responses/400_error.yaml
+    '401':
+      $ref: ../components/responses/unauthorized.yaml
+    '404':
+      $ref: ../components/responses/not_found_error.yaml
+    '409':
+      $ref: ../components/responses/invalid_state_error.yaml
+    '422':
+      $ref: ../components/responses/invalid_request_error.yaml
+    '500':
+      $ref: ../components/responses/500_error.yaml

docs/api/admin/paths/order-edits_{id}.yaml

@@ -56,6 +56,16 @@ get:
       description: The ID of the OrderEdit.
       schema:
         type: string
+    - in: query
+      name: expand
+      description: Comma separated list of relations to include in the results.
+      schema:
+        type: string
+    - in: query
+      name: fields
+      description: Comma separated list of fields to include in the results.
+      schema:
+        type: string
   x-codeSamples:
     - lang: JavaScript
       label: JS Client
@@ -103,6 +113,14 @@ post:
       description: The ID of the OrderEdit.
       schema:
         type: string
+  requestBody:
+    content:
+      application/json:
+        schema:
+          properties:
+            internal_note:
+              description: An optional note to create or update for the order edit.
+              type: string
   x-codeSamples:
     - lang: JavaScript
       label: JS Client

docs/api/admin/paths/order-edits_{id}_items.yaml

@@ -9,6 +9,25 @@ post:
       description: The ID of the Order Edit.
       schema:
         type: string
+  requestBody:
+    content:
+      application/json:
+        schema:
+          required:
+            - variant_id
+            - quantity
+          properties:
+            variant_id:
+              description: The ID of the variant ID to add
+              type: string
+            quantity:
+              description: The quantity to add
+              type: number
+            metadata:
+              description: >-
+                An optional set of key-value pairs to hold additional
+                information.
+              type: object
   x-authenticated: true
   x-codeSamples:
     - lang: JavaScript

docs/api/admin/paths/order-edits_{id}_items_{item_id}.yaml

@@ -70,6 +70,16 @@ post:
       description: The ID of the order edit item to update.
       schema:
         type: string
+  requestBody:
+    content:
+      application/json:
+        schema:
+          required:
+            - quantity
+          properties:
+            quantity:
+              description: The quantity to update
+              type: number
   x-codeSamples:
     - lang: JavaScript
       label: JS Client

docs/api/admin/paths/product-tags.yaml

@@ -21,6 +21,11 @@ get:
       description: The field to sort items by.
       schema:
         type: string
+    - in: query
+      name: discount_condition_id
+      description: The discount condition id on which to filter the tags.
+      schema:
+        type: string
     - in: query
       name: value
       style: form

docs/api/admin/paths/product-types.yaml

@@ -21,6 +21,11 @@ get:
       description: The field to sort items by.
       schema:
         type: string
+    - in: query
+      name: discount_condition_id
+      description: The discount condition id on which to filter the product types.
+      schema:
+        type: string
     - in: query
       name: value
       style: form

docs/api/admin/paths/products.yaml

@@ -289,6 +289,11 @@ get:
         and sku, and collection title.
       schema:
         type: string
+    - in: query
+      name: discount_condition_id
+      description: The discount condition id on which to filter the product.
+      schema:
+        type: string
     - in: query
       name: id
       style: form
@@ -352,6 +357,15 @@ get:
         type: array
         items:
           type: string
+    - in: query
+      name: type_id
+      style: form
+      explode: false
+      description: Type IDs to filter products by
+      schema:
+        type: array
+        items:
+          type: string
     - in: query
       name: title
       description: title to search for.
@@ -372,11 +386,6 @@ get:
       description: Search for giftcards using is_giftcard=true.
       schema:
         type: boolean
-    - in: query
-      name: type
-      description: type ID to search for.
-      schema:
-        type: string
     - in: query
       name: created_at
       description: Date comparison for when resulting products were created.

docs/api/admin/paths/uploads_protected.yaml

@@ -0,0 +1,58 @@
+post:
+  operationId: PostUploadsProtected
+  summary: Upload files with acl or in a non-public bucket
+  description: >-
+    Uploads at least one file to the specific fileservice that is installed in
+    Medusa.
+  x-authenticated: true
+  requestBody:
+    content:
+      multipart/form-data:
+        schema:
+          type: object
+          properties:
+            files:
+              type: string
+              format: binary
+  x-codeSamples:
+    - lang: JavaScript
+      label: JS Client
+      source:
+        $ref: ../code_samples/JavaScript/uploads_protected/postundefined
+    - lang: Shell
+      label: cURL
+      source:
+        $ref: ../code_samples/Shell/uploads_protected/postundefined
+  security:
+    - api_token: []
+    - cookie_auth: []
+  tags:
+    - Upload
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              uploads:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    url:
+                      type: string
+                      description: The URL of the uploaded file.
+                      format: uri
+    '400':
+      $ref: ../components/responses/400_error.yaml
+    '401':
+      $ref: ../components/responses/unauthorized.yaml
+    '404':
+      $ref: ../components/responses/not_found_error.yaml
+    '409':
+      $ref: ../components/responses/invalid_state_error.yaml
+    '422':
+      $ref: ../components/responses/invalid_request_error.yaml
+    '500':
+      $ref: ../components/responses/500_error.yaml

docs/api/admin/paths/variants.yaml

@@ -5,22 +5,94 @@ get:
   x-authenticated: true
   parameters:
     - in: query
-      name: q
-      description: Query used for searching variants.
+      name: id
+      description: A Product Variant id to filter by.
+      schema:
+        type: string
+    - in: query
+      name: ids
+      description: A comma separated list of Product Variant ids to filter by.
+      schema:
+        type: string
+    - in: query
+      name: expand
+      description: A comma separated list of Product Variant relations to load.
+      schema:
+        type: string
+    - in: query
+      name: fields
+      description: A comma separated list of Product Variant fields to include.
       schema:
         type: string
     - in: query
       name: offset
-      description: How many variants to skip in the result.
+      description: How many product variants to skip in the result.
       schema:
-        type: integer
-        default: 0
+        type: number
+        default: '0'
     - in: query
       name: limit
-      description: Limit the number of variants returned.
+      description: Maximum number of Product Variants to return.
       schema:
-        type: integer
-        default: 20
+        type: number
+        default: '100'
+    - in: query
+      name: cart_id
+      description: The id of the cart to use for price selection.
+      schema:
+        type: string
+    - in: query
+      name: region_id
+      description: The id of the region to use for price selection.
+      schema:
+        type: string
+    - in: query
+      name: currency_code
+      description: The currency code to use for price selection.
+      schema:
+        type: string
+    - in: query
+      name: customer_id
+      description: The id of the customer to use for price selection.
+      schema:
+        type: string
+    - in: query
+      name: title
+      style: form
+      explode: false
+      description: product variant title to search for.
+      schema:
+        oneOf:
+          - type: string
+            description: a single title to search by
+          - type: array
+            description: multiple titles to search by
+            items:
+              type: string
+    - in: query
+      name: inventory_quantity
+      description: Filter by available inventory quantity
+      schema:
+        oneOf:
+          - type: number
+            description: a specific number to search by.
+          - type: object
+            description: search using less and greater than comparisons.
+            properties:
+              lt:
+                type: number
+                description: filter by inventory quantity less than this number
+              gt:
+                type: number
+                description: filter by inventory quantity greater than this number
+              lte:
+                type: number
+                description: filter by inventory quantity less than or equal to this number
+              gte:
+                type: number
+                description: >-
+                  filter by inventory quantity greater than or equal to this
+                  number
   x-codeSamples:
     - lang: JavaScript
       label: JS Client