chore(docs): Updated API Reference (v2) (#9666)

Automated changes by [create-pull-request](https://github.com/peter-evans/create-pull-request) GitHub action Co-authored-by: Oli Juhl <[email protected]> Co-authored-by: Shahed Nasser <[email protected]>
medusajs · Oct 18, 2024 · 8209d93 · 8209d93
1 parent 2ea766d
commit 8209d93
Show file tree

Hide file tree

Showing 595 changed files with 33,956 additions and 13,815 deletions.
diff --git a/www/apps/api-reference/specs/admin/code_samples/Shell/admin_orders_{id}_line-items/get.sh b/www/apps/api-reference/specs/admin/code_samples/Shell/admin_orders_{id}_line-items/get.sh
@@ -0,0 +1,2 @@
+curl '{backend_url}/admin/orders/{id}/line-items' \
+-H 'Authorization: Bearer {access_token}'
diff --git a/www/apps/api-reference/specs/admin/code_samples/Shell/admin_products/post.sh b/www/apps/api-reference/specs/admin/code_samples/Shell/admin_products/post.sh
@@ -2,5 +2,11 @@ curl -X POST '{backend_url}/admin/products' \
 -H 'Authorization: Bearer {access_token}' \
 -H 'Content-Type: application/json' \
 --data-raw '{
-  "title": "{value}"
+  "title": "{value}",
+  "options": [
+    {
+      "title": "Default option",
+      "values": ["Default option value"]
+    }
+  ]
 }'
diff --git a/www/apps/api-reference/specs/admin/code_samples/Shell/admin_tax-regions_{id}/post.sh b/www/apps/api-reference/specs/admin/code_samples/Shell/admin_tax-regions_{id}/post.sh
@@ -0,0 +1,2 @@
+curl -X POST '{backend_url}/admin/tax-regions/{id}' \
+-H 'Authorization: Bearer {access_token}'
diff --git a/www/apps/api-reference/specs/admin/components/schemas/AdminCreateFulfillment.yaml b/www/apps/api-reference/specs/admin/components/schemas/AdminCreateFulfillment.yaml
@@ -3,9 +3,9 @@ description: The filfillment's details.
 x-schemaName: AdminCreateFulfillment
 required:
   - data
-  - order_id
-  - metadata
   - items
+  - metadata
+  - order_id
   - location_id
   - provider_id
   - delivery_address

diff --git a/www/apps/api-reference/specs/admin/components/schemas/AdminCreateProduct.yaml b/www/apps/api-reference/specs/admin/components/schemas/AdminCreateProduct.yaml
@@ -3,6 +3,7 @@ description: The product's details.
 x-schemaName: AdminCreateProduct
 required:
   - title
+  - options
 properties:
   title:
     type: string

diff --git a/www/apps/api-reference/specs/admin/components/schemas/AdminCreateShippingOption.yaml b/www/apps/api-reference/specs/admin/components/schemas/AdminCreateShippingOption.yaml
@@ -2,19 +2,87 @@ type: object
 description: The shipping option's details.
 x-schemaName: AdminCreateShippingOption
 required:
-  - label
-  - description
-  - code
+  - name
+  - service_zone_id
+  - shipping_profile_id
+  - price_type
+  - provider_id
+  - type
+  - prices
 properties:
-  label:
+  name:
     type: string
-    title: label
-    description: The type's label.
-  description:
+    title: name
+    description: The shipping option's name.
+  service_zone_id:
     type: string
-    title: description
-    description: The type's description.
-  code:
+    title: service_zone_id
+    description: The ID of the associated service zone.
+  shipping_profile_id:
     type: string
-    title: code
-    description: The type's code.
+    title: shipping_profile_id
+    description: The ID of the associated shipping profile.
+  data:
+    type: object
+    description: >-
+      The shipping option's data, useful for the fulfillment provider handling
+      its processing.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/shipping-option#data-property
+  price_type:
+    type: string
+    description: >-
+      The shipping option's price type. If `flat`, the shipping option has a
+      fixed price set in `prices`. Otherwise, the shipping option's price is
+      calculated by the fulfillment provider.
+    enum:
+      - flat
+      - calculated
+  provider_id:
+    type: string
+    title: provider_id
+    description: The ID of the fulfillment provider handling this shipping option.
+  type:
+    $ref: ./AdminCreateShippingOptionType.yaml
+  prices:
+    type: array
+    description: The shipping option's prices.
+    items:
+      oneOf:
+        - type: object
+          description: The price's details.
+          x-schemaName: AdminCreateShippingOptionPriceWithCurrency
+          required:
+            - currency_code
+            - amount
+          properties:
+            currency_code:
+              type: string
+              title: currency_code
+              description: The price's currency code.
+              example: usd
+            amount:
+              type: number
+              title: amount
+              description: The price's amount.
+        - type: object
+          description: The price's details.
+          x-schemaName: AdminCreateShippingOptionPriceWithRegion
+          required:
+            - region_id
+            - amount
+          properties:
+            region_id:
+              type: string
+              title: region_id
+              description: The ID of the region this price is used in.
+            amount:
+              type: number
+              title: amount
+              description: The price's amount.
+  rules:
+    type: array
+    description: The shipping option's rules.
+    items:
+      $ref: ./AdminCreateShippingOptionRule.yaml
diff --git a/www/apps/api-reference/specs/admin/components/schemas/AdminCreateShippingOptionType.yaml b/www/apps/api-reference/specs/admin/components/schemas/AdminCreateShippingOptionType.yaml
@@ -0,0 +1,20 @@
+type: object
+description: The shipping option type's details.
+x-schemaName: AdminCreateShippingOptionType
+required:
+  - label
+  - description
+  - code
+properties:
+  label:
+    type: string
+    title: label
+    description: The type's label.
+  description:
+    type: string
+    title: description
+    description: The type's description.
+  code:
+    type: string
+    title: code
+    description: The type's code.
diff --git a/www/apps/api-reference/specs/admin/components/schemas/AdminExchange.yaml b/www/apps/api-reference/specs/admin/components/schemas/AdminExchange.yaml
@@ -95,7 +95,7 @@ properties:
     title: deleted_at
     description: The date the exchange was deleted.
   order:
-    $ref: ./AdminOrder.yaml
+    $ref: ./BaseOrder.yaml
   allow_backorder:
     type: boolean
     title: allow_backorder

diff --git a/www/apps/api-reference/specs/admin/components/schemas/AdminExchangeOrderResponse.yaml b/www/apps/api-reference/specs/admin/components/schemas/AdminExchangeOrderResponse.yaml
@@ -6,7 +6,6 @@ required:
   - exchange
 properties:
   order:
-    description: The details of the associated order.
     $ref: ./Order.yaml
   exchange:
     $ref: ./AdminExchange.yaml
diff --git a/www/apps/api-reference/specs/admin/components/schemas/AdminOrder.yaml b/www/apps/api-reference/specs/admin/components/schemas/AdminOrder.yaml
@@ -7,16 +7,16 @@ required:
   - shipping_methods
   - currency_code
   - id
-  - created_at
-  - updated_at
-  - email
   - version
   - region_id
   - customer_id
   - sales_channel_id
+  - email
   - payment_status
   - fulfillment_status
   - summary
+  - created_at
+  - updated_at
   - original_item_total
   - original_item_subtotal
   - original_item_tax_total

diff --git a/www/apps/api-reference/specs/admin/components/schemas/AdminOrderChange.yaml b/www/apps/api-reference/specs/admin/components/schemas/AdminOrderChange.yaml
@@ -8,12 +8,12 @@ required:
   - exchange
   - actions
   - status
-  - order_id
-  - metadata
   - id
+  - version
+  - metadata
   - created_at
   - updated_at
-  - version
+  - order_id
   - canceled_at
   - return_id
   - exchange_id
@@ -62,11 +62,7 @@ properties:
     title: claim_id
     description: The ID of the associated claim.
   order:
-    type: string
-    title: order
-    description: The order change's order.
-    externalDocs:
-      url: '#pagination'
+    $ref: ./AdminOrder.yaml
   return_order:
     $ref: ./AdminReturn.yaml
   exchange:

diff --git a/www/apps/api-reference/specs/admin/components/schemas/AdminOrderChangeAction.yaml b/www/apps/api-reference/specs/admin/components/schemas/AdminOrderChangeAction.yaml
@@ -4,11 +4,11 @@ x-schemaName: AdminOrderChangeAction
 required:
   - order_change
   - order
-  - order_id
-  - internal_note
   - id
   - created_at
   - updated_at
+  - order_id
+  - internal_note
   - return_id
   - exchange_id
   - claim_id
@@ -45,11 +45,7 @@ properties:
     title: exchange_id
     description: The ID of the associated exchange.
   order:
-    type: string
-    title: order
-    description: The order change's order.
-    externalDocs:
-      url: '#pagination'
+    $ref: ./AdminOrder.yaml
   reference:
     type: string
     title: reference

diff --git a/www/apps/api-reference/specs/admin/components/schemas/AdminOrderItem.yaml b/www/apps/api-reference/specs/admin/components/schemas/AdminOrderItem.yaml
@@ -0,0 +1,45 @@
+type: object
+description: The order item's details.
+x-schemaName: AdminOrderItem
+required:
+  - order_id
+  - item_id
+  - version
+  - history
+  - item
+properties:
+  order_id:
+    type: string
+    title: order_id
+    description: The ID of the order this item belongs to.
+  item_id:
+    type: string
+    title: item_id
+    description: The ID of the associated line item.
+  version:
+    type: number
+    title: version
+    description: The order item's version.
+  history:
+    type: object
+    description: The order item's history.
+    required:
+      - version
+    properties:
+      version:
+        type: object
+        description: The version changes of the item.
+        required:
+          - from
+          - to
+        properties:
+          from:
+            type: number
+            title: from
+            description: The original version.
+          to:
+            type: number
+            title: to
+            description: The new version.
+  item:
+    $ref: ./AdminOrderLineItem.yaml
diff --git a/www/apps/api-reference/specs/admin/components/schemas/AdminOrderLineItem.yaml b/www/apps/api-reference/specs/admin/components/schemas/AdminOrderLineItem.yaml
@@ -3,10 +3,8 @@ description: The item's details.
 x-schemaName: AdminOrderLineItem
 required:
   - title
-  - metadata
   - id
-  - subtitle
-  - thumbnail
+  - metadata
   - created_at
   - updated_at
   - item_total
@@ -20,6 +18,8 @@ required:
   - tax_total
   - discount_total
   - discount_tax_total
+  - subtitle
+  - thumbnail
   - variant_id
   - product_id
   - product_title

diff --git a/www/apps/api-reference/specs/admin/components/schemas/AdminOrderPreview.yaml b/www/apps/api-reference/specs/admin/components/schemas/AdminOrderPreview.yaml
@@ -8,17 +8,17 @@ required:
   - order_change
   - currency_code
   - id
-  - created_at
-  - updated_at
-  - email
   - version
   - region_id
   - customer_id
   - sales_channel_id
+  - email
   - payment_collections
   - payment_status
   - fulfillment_status
   - summary
+  - created_at
+  - updated_at
   - original_item_total
   - original_item_subtotal
   - original_item_tax_total

diff --git a/...ps/api-reference/specs/admin/components/schemas/AdminPostOrderEditsAddItemsReqSchema.yaml b/...ps/api-reference/specs/admin/components/schemas/AdminPostOrderEditsAddItemsReqSchema.yaml
@@ -37,3 +37,7 @@ properties:
         metadata:
           type: object
           description: The item's metadata, can hold custom key-value pairs.
+        compare_at_unit_price:
+          type: number
+          title: compare_at_unit_price
+          description: The original price of the item before a promotion or sale.
diff --git a/...api-reference/specs/admin/components/schemas/AdminPostOrderEditsItemsActionReqSchema.yaml b/...api-reference/specs/admin/components/schemas/AdminPostOrderEditsItemsActionReqSchema.yaml
@@ -14,3 +14,7 @@ properties:
     type: number
     title: unit_price
     description: The item's unit price.
+  compare_at_unit_price:
+    type: number
+    title: compare_at_unit_price
+    description: The original price of the item before a promotion or sale.
diff --git a/...erence/specs/admin/components/schemas/AdminPostOrderEditsUpdateItemQuantityReqSchema.yaml b/...erence/specs/admin/components/schemas/AdminPostOrderEditsUpdateItemQuantityReqSchema.yaml
@@ -16,3 +16,7 @@ properties:
     type: number
     title: unit_price
     description: The item's unit price.
+  compare_at_unit_price:
+    type: number
+    title: compare_at_unit_price
+    description: The original price of the item before a promotion or sale.
diff --git a/www/apps/api-reference/specs/admin/components/schemas/AdminProduct.yaml b/www/apps/api-reference/specs/admin/components/schemas/AdminProduct.yaml
@@ -11,10 +11,12 @@ required:
   - status
   - description
   - id
-  - handle
+  - created_at
+  - updated_at
   - subtitle
-  - is_giftcard
   - thumbnail
+  - handle
+  - is_giftcard
   - width
   - weight
   - height
@@ -26,8 +28,6 @@ required:
   - type_id
   - discountable
   - external_id
-  - created_at
-  - updated_at
   - deleted_at
 properties:
   collection:
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		curl '{backend_url}/admin/orders/{id}/line-items' \
		-H 'Authorization: Bearer {access_token}'
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		curl -X POST '{backend_url}/admin/tax-regions/{id}' \
		-H 'Authorization: Bearer {access_token}'