chore(docs): Refactor API Reference (#1883)

.github/workflows/generate-api-reference.yml

@@ -0,0 +1,51 @@
+name: Generate API Reference
+on: 
+  pull_request:
+    types:
+      - closed
+    branches:
+      - "master"
+    paths:
+      - packages/medusa/src/api/routes/**
+      - '!packages/medusa/src/api/routes/**/index.ts'
+      - '!packages/medusa/src/api/routes/**/index.js'
+jobs:
+  api:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.9.1
+        with:
+          access_token: ${{ github.token }}
+
+      - name: Checkout
+        uses: actions/checkout@v2.3.5
+        with:
+          token: ${{ secrets.REFERENCE_PAT }}
+          fetch-depth: 0
+
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v2.4.1
+        with:
+          node-version: "14"
+          cache: "yarn"
+
+      - name: Install dependencies
+        uses: ./.github/actions/cache-deps
+        with:
+          extension: reference
+
+      - name: Build Packages
+        run: yarn build
+
+      - name: Generate API Reference
+        run: yarn openapi:generate
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v4
+        with:
+          commit-message: 'chore(docs): Generated API Reference'
+          base: 'master'
+          title: 'chore(docs): Updated API Reference'
+          labels: 'type: chore'
+          add-paths: docs/api/*

.github/workflows/generate-js-reference.yml

@@ -46,8 +46,8 @@ jobs:
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@v4
         with:
-          commit-message: 'docs: Generated JS Client Reference (automated)'
+          commit-message: 'chore(docs): Generated JS Client Reference (automated)'
           base: 'master'
-          title: 'docs: Generated JS Client Reference (automated)'
-          labels: 'type: docs'
+          title: 'chore(docs): Updated API Reference'
+          labels: 'type: chore'
           add-paths: docs/content/references/js-client/**

.github/workflows/generate-reference.yml

@@ -46,8 +46,8 @@ jobs:
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@v4
         with:
-          commit-message: 'docs: Generated Services Reference (automated)'
+          commit-message: 'chore(docs): Generated Services Reference (automated)'
           base: 'master'
-          title: 'docs: Generated Services Reference (automated)'
-          labels: 'type: docs'
+          title: 'chore(docs): Generated Services Reference (automated)'
+          labels: 'type: chore'
           add-paths: docs/content/references/services/**

.github/workflows/oas-test.yml

@@ -0,0 +1,34 @@
+name: OAS Comments Format Validation
+on: 
+  pull_request:
+    paths:
+      - packages/medusa/src/api/routes/**
+
+jobs:
+  docs-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.9.1
+        with:
+          access_token: ${{ github.token }}
+
+      - name: Checkout
+        uses: actions/checkout@v2.3.5
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v2.4.1
+        with:
+          node-version: "14"
+          cache: "yarn"
+
+      - name: Install dependencies
+        uses: ./.github/actions/cache-deps
+        with:
+          extension: oas
+
+      - name: Build OAS
+        run: |
+          yarn openapi:generate

.gitignore

@@ -20,4 +20,4 @@ lerna-debug.log
 
 .idea
 .turbo
-build/**
+build/**

docs/api/admin-spec3-base.json

@@ -3,70 +3,165 @@
   "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"
+      "name": "MIT",
+      "url": "https://github.com/medusajs/medusa/blob/master/LICENSE"
     }
   },
   "tags": [
     {
       "name": "Auth",
-      "description": "Auth endpoints allows authorization of admin Users and manages their sessions."
+      "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": "Product Variant",
-      "x-resourceId": "product_variant"
+      "name": "Tax Rate",
+      "description": "Tax Rate endpoints that allow handling tax rates in Medusa.",
+      "x-resourceId": "tax_rate"
     },
     {
-      "name": "OAuth",
-      "x-resourceId": "OAuth"
+      "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": [

docs/api/admin/components/schemas/OAuth.yaml

@@ -0,0 +1,32 @@
+title: OAuth
+description: Represent an OAuth app
+x-resourceId: OAuth
+required:
+  - id
+  - display_name
+  - application_name
+properties:
+  id:
+    type: string
+    description: The app's ID
+    example: example_app
+  display_name:
+    type: string
+    description: The app's display name
+    example: Example app
+  application_name:
+    type: string
+    description: The app's name
+    example: example
+  install_url:
+    type: string
+    description: The URL to install the app
+    format: uri
+  uninstall_url:
+    type: string
+    description: The URL to uninstall the app
+    format: uri
+  data:
+    type: object
+    description: Any data necessary to the app.
+    example: {}

docs/api/admin/components/schemas/address.yaml

@@ -0,0 +1,82 @@
+title: Address
+description: An address.
+x-resourceId: address
+properties:
+  id:
+    type: string
+    description: ID of the address
+    example: addr_01G8ZC9VS1XVE149MGH2J7QSSH
+  customer_id:
+    type: string
+    description: ID of the customer this address belongs to
+    example: cus_01G2SG30J8C85S4A5CHM2S1NS2
+  customer:
+    description: Available if the relation `customer` is expanded.
+    type: array
+    items:
+      type: object
+      description: A customer object.
+  company:
+    type: string
+    description: Company name
+    example: Acme
+  first_name:
+    type: string
+    description: First name
+    example: Arno
+  last_name:
+    type: string
+    description: Last name
+    example: Willms
+  address_1:
+    type: string
+    description: Address line 1
+    example: 14433 Kemmer Court
+  address_2:
+    type: string
+    description: Address line 2
+    example: Suite 369
+  city:
+    type: string
+    description: City
+    example: South Geoffreyview
+  country_code:
+    type: string
+    description: The 2 character ISO code of the country in lower case
+    externalDocs:
+      url: >-
+        https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
+      description: See a list of codes.
+    example: st
+  country:
+    description: A country object. Available if the relation `country` is expanded.
+    type: object
+  province:
+    type: string
+    description: Province
+    example: Kentucky
+  postal_code:
+    type: string
+    description: Postal Code
+    example: 72093
+  phone:
+    type: string
+    description: Phone Number
+    example: 16128234334802
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/batch_job.yaml

@@ -0,0 +1,139 @@
+title: Batch Job
+description: A Batch Job.
+x-resourceId: batch_job
+required:
+  - type
+properties:
+  id:
+    type: string
+    description: The unique identifier for the batch job.
+    example: batch_01G8T782965PYFG0751G0Z38B4
+  type:
+    type: string
+    description: The type of batch job.
+    enum:
+      - product-import
+      - product-export
+  status:
+    type: string
+    description: The status of the batch job.
+    enum:
+      - created
+      - pre_processed
+      - confirmed
+      - processing
+      - completed
+      - canceled
+      - failed
+    default: created
+  created_by:
+    type: string
+    description: The unique identifier of the user that created the batch job.
+    example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V
+  created_by_user:
+    description: A user object. Available if the relation `created_by_user` is expanded.
+    type: object
+  context:
+    type: object
+    description: >-
+      The context of the batch job, the type of the batch job determines what
+      the context should contain.
+    example:
+      shape:
+        prices:
+          - region: null
+            currency_code: eur
+        dynamicImageColumnCount: 4
+        dynamicOptionColumnCount: 2
+      list_config:
+        skip: 0
+        take: 50
+        order:
+          created_at: DESC
+        relations:
+          - variants
+          - variant.prices
+          - images
+  dry_run:
+    type: boolean
+    description: Specify if the job must apply the modifications or not.
+    default: false
+  result:
+    type: object
+    description: The result of the batch job.
+    properties:
+      count:
+        type: number
+      advancement_count:
+        type: number
+      progress:
+        type: number
+      errors:
+        type: object
+        properties:
+          message:
+            type: string
+          code:
+            oneOf:
+              - type: string
+              - type: number
+          err:
+            type: array
+      stat_descriptors:
+        type: object
+        properties:
+          key:
+            type: string
+          name:
+            type: string
+          message:
+            type: string
+      file_key:
+        type: string
+      file_size:
+        type: number
+    example:
+      errors:
+        - err: []
+          code: unknown
+          message: Method not implemented.
+      stat_descriptors:
+        - key: product-export-count
+          name: Product count to export
+          message: There will be 8 products exported by this action
+  pre_processed_at:
+    type: string
+    description: The date from which the job has been pre processed.
+    format: date-time
+  processing_at:
+    type: string
+    description: The date the job is processing at.
+    format: date-time
+  confirmed_at:
+    type: string
+    description: The date when the confirmation has been done.
+    format: date-time
+  completed_at:
+    type: string
+    description: The date of the completion.
+    format: date-time
+  canceled_at:
+    type: string
+    description: The date of the concellation.
+    format: date-time
+  failed_at:
+    type: string
+    description: The date when the job failed.
+    format: date-time
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was last updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time

docs/api/admin/components/schemas/cart.yaml

@@ -0,0 +1,174 @@
+title: Cart
+description: Represents a user cart
+x-resourceId: cart
+properties:
+  id:
+    type: string
+    description: The cart's ID
+    example: cart_01G8ZH853Y6TFXWPG5EYE81X63
+  email:
+    type: string
+    description: The email associated with the cart
+    format: email
+  billing_address_id:
+    type: string
+    description: The billing address's ID
+    example: addr_01G8ZH853YPY9B94857DY91YGW
+  billing_address:
+    description: Available if the relation `billing_address` is expanded.
+    $ref: ./address.yaml
+  shipping_address_id:
+    type: string
+    description: The shipping address's ID
+    example: addr_01G8ZH853YPY9B94857DY91YGW
+  shipping_address:
+    description: Available if the relation `shipping_address` is expanded.
+    $ref: ./address.yaml
+  items:
+    description: Available if the relation `items` is expanded.
+    type: array
+    items:
+      $ref: ./line_item.yaml
+  region_id:
+    type: string
+    description: The region's ID
+    example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
+  region:
+    description: A region object. Available if the relation `region` is expanded.
+    type: object
+  discounts:
+    type: array
+    description: Available if the relation `discounts` is expanded.
+    items:
+      type: object
+      description: A discount object.
+  gift_cards:
+    type: array
+    description: Available if the relation `gift_cards` is expanded.
+    items:
+      type: object
+      description: A gift card object.
+  customer_id:
+    type: string
+    description: The customer's ID
+    example: cus_01G2SG30J8C85S4A5CHM2S1NS2
+  customer:
+    description: A customer object. Available if the relation `customer` is expanded.
+    type: object
+  payment_session:
+    description: The selected payment session in the cart.
+    $ref: ./payment_session.yaml
+  payment_sessions:
+    type: array
+    description: The payment sessions created on the cart.
+    items:
+      $ref: ./payment_session.yaml
+  payment_id:
+    type: string
+    description: The payment's ID if available
+    example: pay_01G8ZCC5W42ZNY842124G7P5R9
+  payment:
+    description: Available if the relation `payment` is expanded.
+    $ref: ./payment.yaml
+  shipping_methods:
+    type: array
+    description: The shipping methods added to the cart.
+    items:
+      $ref: ./shipping_method.yaml
+  type:
+    type: string
+    description: The cart's type.
+    enum:
+      - default
+      - swap
+      - draft_order
+      - payment_link
+      - claim
+    default: default
+  completed_at:
+    type: string
+    description: The date with timezone at which the cart was completed.
+    format: date-time
+  payment_authorized_at:
+    type: string
+    description: The date with timezone at which the payment was authorized.
+    format: date-time
+  idempotency_key:
+    type: string
+    description: >-
+      Randomly generated key used to continue the completion of a cart in case
+      of failure.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key
+      description: Learn more how to use the idempotency key.
+  context:
+    type: object
+    description: The context of the cart which can include info like IP or user agent.
+    example:
+      ip: '::1'
+      user_agent: PostmanRuntime/7.29.2
+  sales_channel_id:
+    type: string
+    description: The sales channel ID the cart is associated with.
+    example: null
+  sales_channel:
+    description: >-
+      A sales channel object. Available if the relation `sales_channel` is
+      expanded.
+    type: object
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white
+  shipping_total:
+    type: integer
+    description: The total of shipping
+    example: 1000
+  discount_total:
+    type: integer
+    description: The total of discount
+    example: 800
+  tax_total:
+    type: integer
+    description: The total of tax
+    example: 0
+  refunded_total:
+    type: integer
+    description: >-
+      The total amount refunded if the order associated with this cart is
+      returned.
+    example: 0
+  total:
+    type: integer
+    description: The total amount of the cart
+    example: 8200
+  subtotal:
+    type: integer
+    description: The subtotal of the cart
+    example: 8000
+  refundable_amount:
+    type: integer
+    description: The amount that can be refunded
+    example: 8200
+  gift_card_total:
+    type: integer
+    description: The total of gift cards
+    example: 0
+  gift_card_tax_total:
+    type: integer
+    description: The total of gift cards with taxes
+    example: 0

docs/api/admin/components/schemas/claim_image.yaml

@@ -0,0 +1,38 @@
+title: Claim Image
+description: Represents photo documentation of a claim.
+x-resourceId: claim_image
+required:
+  - claim_item_id
+  - url
+properties:
+  id:
+    type: string
+    description: The claim image's ID
+    example: cimg_01G8ZH853Y6TFXWPG5EYE81X63
+  claim_item_id:
+    type: string
+    description: The ID of the claim item associated with the image
+  claim_item:
+    description: A claim item object. Available if the relation `claim_item` is expanded.
+    type: object
+  url:
+    type: string
+    description: The URL of the image
+    format: uri
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/claim_item.yaml

@@ -0,0 +1,83 @@
+title: Claim Item
+description: >-
+  Represents a claimed item along with information about the reasons for the
+  claim.
+x-resourceId: claim_item
+required:
+  - claim_order_id
+  - item_id
+  - variant_id
+  - reason
+  - quantity
+properties:
+  id:
+    type: string
+    description: The claim item's ID
+    example: citm_01G8ZH853Y6TFXWPG5EYE81X63
+  images:
+    type: array
+    description: Available if the relation `images` is expanded.
+    items:
+      $ref: ./claim_image.yaml
+  claim_order_id:
+    description: The ID of the claim this item is associated with.
+    type: string
+  claim_order:
+    description: A claim order object. Available if the relation `claim_order` is expanded.
+    type: object
+  item_id:
+    description: The ID of the line item that the claim item refers to.
+    type: string
+    example: item_01G8ZM25TN49YV9EQBE2NC27KC
+  item:
+    description: Available if the relation `item` is expanded.
+    $ref: ./line_item.yaml
+  variant_id:
+    description: The ID of the product variant that is claimed.
+    type: string
+    example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6
+  variant:
+    description: A variant object. Available if the relation `variant` is expanded.
+    type: object
+  reason:
+    description: The reason for the claim
+    type: string
+    enum:
+      - missing_item
+      - wrong_item
+      - production_failure
+      - other
+  note:
+    description: An optional note about the claim, for additional information
+    type: string
+    example: I don't like it.
+  quantity:
+    description: >-
+      The quantity of the item that is being claimed; must be less than or equal
+      to the amount purchased in the original order.
+    type: integer
+    example: 1
+  tags:
+    description: >-
+      User defined tags for easy filtering and grouping. Available if the
+      relation 'tags' is expanded.
+    type: array
+    items:
+      $ref: ./claim_tag.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/claim_order.yaml

@@ -0,0 +1,121 @@
+title: Claim Order
+description: >-
+  Claim Orders represent a group of faulty or missing items. Each claim order
+  consists of a subset of items associated with an original order, and can
+  contain additional information about fulfillments and returns.
+x-resourceId: claim_order
+required:
+  - type
+  - order_id
+properties:
+  id:
+    type: string
+    description: The claim's ID
+    example: claim_01G8ZH853Y6TFXWPG5EYE81X63
+  type:
+    type: string
+    enum:
+      - refund
+      - replace
+  payment_status:
+    type: string
+    description: The status of the claim's payment
+    enum:
+      - na
+      - not_refunded
+      - refunded
+    default: na
+  fulfillment_status:
+    type: string
+    enum:
+      - not_fulfilled
+      - partially_fulfilled
+      - fulfilled
+      - partially_shipped
+      - shipped
+      - partially_returned
+      - returned
+      - canceled
+      - requires_action
+    default: not_fulfilled
+  claim_items:
+    description: The items that have been claimed
+    type: array
+    items:
+      $ref: ./claim_item.yaml
+  additional_items:
+    description: >-
+      Refers to the new items to be shipped when the claim order has the type
+      `replace`
+    type: array
+    items:
+      $ref: ./line_item.yaml
+  order_id:
+    description: The ID of the order that the claim comes from.
+    type: string
+    example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
+  order:
+    description: An order object. Available if the relation `order` is expanded.
+    type: object
+  return_order:
+    description: >-
+      A return object. Holds information about the return if the claim is to be
+      returned. Available if the relation 'return_order' is expanded
+    type: object
+  shipping_address_id:
+    description: The ID of the address that the new items should be shipped to
+    type: string
+    example: addr_01G8ZH853YPY9B94857DY91YGW
+  shipping_address:
+    description: Available if the relation `shipping_address` is expanded.
+    $ref: ./address.yaml
+  shipping_methods:
+    description: The shipping methods that the claim order will be shipped with.
+    type: array
+    items:
+      $ref: ./shipping_method.yaml
+  fulfillments:
+    description: The fulfillments of the new items to be shipped
+    type: array
+    items:
+      $ref: ./fulfillment.yaml
+  refund_amount:
+    description: The amount that will be refunded in conjunction with the claim
+    type: integer
+    example: 1000
+  canceled_at:
+    description: The date with timezone at which the claim was canceled.
+    type: string
+    format: date-time
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white
+  no_notification:
+    description: >-
+      Flag for describing whether or not notifications related to this should be
+      send.
+    type: boolean
+    example: false
+  idempotency_key:
+    type: string
+    description: >-
+      Randomly generated key used to continue the completion of the cart
+      associated with the claim in case of failure.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key
+      description: Learn more how to use the idempotency key.

docs/api/admin/components/schemas/claim_tag.yaml

@@ -0,0 +1,33 @@
+title: Claim Tag
+description: >-
+  Claim Tags are user defined tags that can be assigned to claim items for easy
+  filtering and grouping.
+x-resourceId: claim_tag
+required:
+  - value
+properties:
+  id:
+    type: string
+    description: The claim tag's ID
+    example: ctag_01G8ZCC5Y63B95V6B5SHBZ91S4
+  value:
+    description: The value that the claim tag holds
+    type: string
+    example: Damaged
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/country.yaml

@@ -0,0 +1,53 @@
+title: Country
+description: Country details
+x-resourceId: country
+required:
+  - iso_2
+  - iso_3
+  - num_code
+  - name
+  - display_name
+properties:
+  id:
+    type: string
+    description: The country's ID
+    example: 109
+  iso_2:
+    type: string
+    description: The 2 character ISO code of the country in lower case
+    example: it
+    externalDocs:
+      url: >-
+        https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
+      description: See a list of codes.
+  iso_3:
+    type: string
+    description: The 2 character ISO code of the country in lower case
+    example: ita
+    externalDocs:
+      url: >-
+        https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements
+      description: See a list of codes.
+  num_code:
+    description: The numerical ISO code for the country.
+    type: string
+    example: 380
+    externalDocs:
+      url: >-
+        https://en.wikipedia.org/wiki/ISO_3166-1_numeric#Officially_assigned_code_elements
+      description: See a list of codes.
+  name:
+    description: The normalized country name in upper case.
+    type: string
+    example: ITALY
+  display_name:
+    description: The country name appropriate for display.
+    type: string
+    example: Italy
+  region_id:
+    type: string
+    description: The region ID this country is associated with.
+    example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
+  region:
+    description: A region object. Available if the relation `region` is expanded.
+    type: object

docs/api/admin/components/schemas/currency.yaml

@@ -0,0 +1,28 @@
+title: Currency
+description: Currency
+x-resourceId: currency
+required:
+  - code
+  - symbol
+  - symbol_native
+  - name
+properties:
+  code:
+    description: The 3 character ISO code for the currency.
+    type: string
+    example: usd
+    externalDocs:
+      url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+      description: See a list of codes.
+  symbol:
+    description: The symbol used to indicate the currency.
+    type: string
+    example: $
+  symbol_native:
+    description: The native symbol used to indicate the currency.
+    type: string
+    example: $
+  name:
+    description: The written name of the currency
+    type: string
+    example: US Dollar

docs/api/admin/components/schemas/custom_shipping_option.yaml

@@ -0,0 +1,53 @@
+title: Custom Shipping Option
+description: >-
+  Custom Shipping Options are 'overriden' Shipping Options. Store managers can
+  attach a Custom Shipping Option to a cart in order to set a custom price for a
+  particular Shipping Option
+x-resourceId: custom_shipping_option
+required:
+  - price
+  - shipping_option_id
+properties:
+  id:
+    type: string
+    description: The custom shipping option's ID
+    example: cso_01G8X99XNB77DMFBJFWX6DN9V9
+  price:
+    description: >-
+      The custom price set that will override the shipping option's original
+      price
+    type: integer
+    example: 1000
+  shipping_option_id:
+    description: The ID of the Shipping Option that the custom shipping option overrides
+    type: string
+    example: so_01G1G5V27GYX4QXNARRQCW1N8T
+  shipping_option:
+    description: >-
+      A shipping option object. Available if the relation `shipping_option` is
+      expanded.
+    type: object
+  cart_id:
+    description: The ID of the Cart that the custom shipping option is attached to
+    type: string
+    example: cart_01G8ZH853Y6TFXWPG5EYE81X63
+  cart:
+    description: A cart object. Available if the relation `cart` is expanded.
+    type: object
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/customer.yaml

@@ -0,0 +1,72 @@
+title: Customer
+description: Represents a customer
+x-resourceId: customer
+required:
+  - email
+properties:
+  id:
+    type: string
+    description: The customer's ID
+    example: cus_01G2SG30J8C85S4A5CHM2S1NS2
+  email:
+    type: string
+    description: The customer's email
+    format: email
+  first_name:
+    type: string
+    description: The customer's first name
+    example: Arno
+  last_name:
+    type: string
+    description: The customer's first name
+    example: Willms
+  billing_address_id:
+    type: string
+    description: The customer's billing address ID
+    example: addr_01G8ZH853YPY9B94857DY91YGW
+  billing_address:
+    description: Available if the relation `billing_address` is expanded.
+    $ref: ./address.yaml
+  shipping_addresses:
+    description: Available if the relation `shipping_addresses` is expanded.
+    type: array
+    items:
+      $ref: ./address.yaml
+  phone:
+    type: string
+    description: The customer's phone number
+    example: 16128234334802
+  has_account:
+    type: boolean
+    description: Whether the customer has an account or not
+    default: false
+  orders:
+    description: Available if the relation `orders` is expanded.
+    type: array
+    items:
+      type: object
+      description: An order object.
+  groups:
+    description: >-
+      The customer groups the customer belongs to. Available if the relation
+      `groups` is expanded.
+    type: array
+    items:
+      $ref: ./customer_group.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/customer_group.yaml

@@ -0,0 +1,46 @@
+title: Customer Group
+description: Represents a customer group
+x-resourceId: customer_group
+required:
+  - name
+properties:
+  id:
+    type: string
+    description: The customer group's ID
+    example: cgrp_01G8ZH853Y6TFXWPG5EYE81X63
+  name:
+    type: string
+    description: The name of the customer group
+    example: VIP
+  customers:
+    type: array
+    description: >-
+      The customers that belong to the customer group. Available if the relation
+      `customers` is expanded.
+    items:
+      type: object
+      description: A customer object.
+  price_lists:
+    type: array
+    description: >-
+      The price lists that are associated with the customer group. Available if
+      the relation `price_lists` is expanded.
+    items:
+      $ref: ./price_list.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/discount.yaml

@@ -0,0 +1,91 @@
+title: Discount
+description: Represents a discount that can be applied to a cart for promotional purposes.
+x-resourceId: discount
+required:
+  - code
+  - is_dynamic
+properties:
+  id:
+    type: string
+    description: The discount's ID
+    example: disc_01F0YESMW10MGHWJKZSDDMN0VN
+  code:
+    description: >-
+      A unique code for the discount - this will be used by the customer to
+      apply the discount
+    type: string
+    example: 10DISC
+  is_dynamic:
+    description: >-
+      A flag to indicate if multiple instances of the discount can be generated.
+      I.e. for newsletter discounts
+    type: boolean
+    example: false
+  rule_id:
+    type: string
+    description: The Discount Rule that governs the behaviour of the Discount
+    example: dru_01F0YESMVK96HVX7N419E3CJ7C
+  rule:
+    description: Available if the relation `rule` is expanded.
+    $ref: ./discount_rule.yaml
+  is_disabled:
+    description: >-
+      Whether the Discount has been disabled. Disabled discounts cannot be
+      applied to carts
+    type: boolean
+    example: false
+  parent_discount_id:
+    type: string
+    description: >-
+      The Discount that the discount was created from. This will always be a
+      dynamic discount
+    example: disc_01G8ZH853YPY9B94857DY91YGW
+  parent_discount:
+    description: Available if the relation `parent_discount` is expanded.
+    $ref: ./discount.yaml
+  starts_at:
+    description: The time at which the discount can be used.
+    type: string
+    format: date-time
+  ends_at:
+    description: The time at which the discount can no longer be used.
+    type: string
+    format: date-time
+  valid_duration:
+    type: string
+    description: Duration the discount runs between
+    example: P3Y6M4DT12H30M5S
+  regions:
+    description: >-
+      The Regions in which the Discount can be used. Available if the relation
+      `regions` is expanded.
+    type: array
+    items:
+      type: object
+      description: A region object.
+  usage_limit:
+    description: The maximum number of times that a discount can be used.
+    type: integer
+    example: 100
+  usage_count:
+    description: The number of times a discount has been used.
+    type: integer
+    example: 50
+    default: 0
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/discount_condition.yaml

@@ -0,0 +1,92 @@
+title: Discount Condition
+description: Holds rule conditions for when a discount is applicable
+x-resourceId: discount_condition
+required:
+  - type
+  - operator
+  - discount_rule_id
+properties:
+  id:
+    type: string
+    description: The discount condition's ID
+    example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
+  type:
+    description: The type of the Condition
+    type: string
+    enum:
+      - products
+      - product_types
+      - product_collections
+      - product_tags
+      - customer_groups
+  operator:
+    description: The operator of the Condition
+    type: string
+    enum:
+      - in
+      - not_in
+  discount_rule_id:
+    type: string
+    description: The ID of the discount rule associated with the condition
+    example: dru_01F0YESMVK96HVX7N419E3CJ7C
+  discount_rule:
+    description: Available if the relation `discount_rule` is expanded.
+    $ref: ./discount_rule.yaml
+  products:
+    description: >-
+      products associated with this condition if type = products. Available if
+      the relation `products` is expanded.
+    type: array
+    items:
+      type: object
+      description: A product object.
+  product_types:
+    description: >-
+      product types associated with this condition if type = product_types.
+      Available if the relation `product_types` is expanded.
+    type: array
+    items:
+      type: object
+      description: A product type object.
+  product_tags:
+    description: >-
+      product tags associated with this condition if type = product_tags.
+      Available if the relation `product_tags` is expanded.
+    type: array
+    items:
+      type: object
+      description: A product tag object.
+  product_collections:
+    description: >-
+      product collections associated with this condition if type =
+      product_collections. Available if the relation `product_collections` is
+      expanded.
+    type: array
+    items:
+      type: object
+      description: A product collection object.
+  customer_groups:
+    description: >-
+      customer groups associated with this condition if type = customer_groups.
+      Available if the relation `customer_groups` is expanded.
+    type: array
+    items:
+      type: object
+      description: A customer group object.
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/discount_condition_customer_group.yaml

@@ -0,0 +1,34 @@
+title: Product Tag Discount Condition
+description: Associates a discount condition with a customer group
+x-resourceId: discount_condition_customer_group
+required:
+  - customer_group_id
+  - condition_id
+properties:
+  customer_group_id:
+    description: The ID of the Product Tag
+    type: string
+    example: cgrp_01G8ZH853Y6TFXWPG5EYE81X63
+  condition_id:
+    description: The ID of the Discount Condition
+    type: string
+    example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
+  customer_group:
+    description: Available if the relation `customer_group` is expanded.
+    $ref: ./customer_group.yaml
+  discount_condition:
+    description: Available if the relation `discount_condition` is expanded.
+    $ref: ./discount_condition.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/discount_condition_product.yaml

@@ -0,0 +1,34 @@
+title: Product Discount Condition
+description: Associates a discount condition with a product
+x-resourceId: discount_condition_product
+required:
+  - product_id
+  - condition_id
+properties:
+  product_id:
+    description: The ID of the Product Tag
+    type: string
+    example: prod_01G1G5V2MBA328390B5AXJ610F
+  condition_id:
+    description: The ID of the Discount Condition
+    type: string
+    example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
+  product:
+    description: Available if the relation `product` is expanded.
+    $ref: ./product.yaml
+  discount_condition:
+    description: Available if the relation `discount_condition` is expanded.
+    $ref: ./discount_condition.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/discount_condition_product_collection.yaml

@@ -0,0 +1,34 @@
+title: Product Collection Discount Condition
+description: Associates a discount condition with a product collection
+x-resourceId: discount_condition_product_collection
+required:
+  - product_collection_id
+  - condition_id
+properties:
+  product_collection_id:
+    description: The ID of the Product Collection
+    type: string
+    example: pcol_01F0YESBFAZ0DV6V831JXWH0BG
+  condition_id:
+    description: The ID of the Discount Condition
+    type: string
+    example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
+  product_collection:
+    description: Available if the relation `product_collection` is expanded.
+    $ref: ./product_collection.yaml
+  discount_condition:
+    description: Available if the relation `discount_condition` is expanded.
+    $ref: ./discount_condition.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/discount_condition_product_tag.yaml

@@ -0,0 +1,34 @@
+title: Product Tag Discount Condition
+description: Associates a discount condition with a product tag
+x-resourceId: discount_condition_product_tag
+required:
+  - product_tag_id
+  - condition_id
+properties:
+  product_tag_id:
+    description: The ID of the Product Tag
+    type: string
+    example: ptag_01F0YESHPZYY3H4SJ3A5918SBN
+  condition_id:
+    description: The ID of the Discount Condition
+    type: string
+    example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
+  product_tag:
+    description: Available if the relation `product_tag` is expanded.
+    $ref: ./product_tag.yaml
+  discount_condition:
+    description: Available if the relation `discount_condition` is expanded.
+    $ref: ./discount_condition.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/discount_condition_product_type.yaml

@@ -0,0 +1,34 @@
+title: Product Type Discount Condition
+description: Associates a discount condition with a product type
+x-resourceId: discount_condition_product
+required:
+  - product_type_id
+  - condition_id
+properties:
+  product_type_id:
+    description: The ID of the Product Tag
+    type: string
+    example: ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A
+  condition_id:
+    description: The ID of the Discount Condition
+    type: string
+    example: discon_01G8X9A7ESKAJXG2H0E6F1MW7A
+  product_type:
+    description: Available if the relation `product_type` is expanded.
+    $ref: ./product_type.yaml
+  discount_condition:
+    description: Available if the relation `discount_condition` is expanded.
+    $ref: ./discount_condition.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/discount_rule.yaml

@@ -0,0 +1,66 @@
+title: Discount Rule
+description: >-
+  Holds the rules that governs how a Discount is calculated when applied to a
+  Cart.
+x-resourceId: discount_rule
+required:
+  - type
+  - value
+properties:
+  id:
+    type: string
+    description: The discount rule's ID
+    example: dru_01F0YESMVK96HVX7N419E3CJ7C
+  type:
+    description: >-
+      The type of the Discount, can be `fixed` for discounts that reduce the
+      price by a fixed amount, `percentage` for percentage reductions or
+      `free_shipping` for shipping vouchers.
+    type: string
+    enum:
+      - fixed
+      - percentage
+      - free_shipping
+    example: percentage
+  description:
+    description: A short description of the discount
+    type: string
+    example: 10 Percent
+  value:
+    description: >-
+      The value that the discount represents; this will depend on the type of
+      the discount
+    type: integer
+    example: 10
+  allocation:
+    description: The scope that the discount should apply to.
+    type: string
+    enum:
+      - total
+      - item
+    example: total
+  conditions:
+    description: >-
+      A set of conditions that can be used to limit when  the discount can be
+      used. Available if the relation `conditions` is expanded.
+    type: array
+    items:
+      type: object
+      description: A discount condition object.
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/draft-order.yaml

@@ -0,0 +1,71 @@
+title: DraftOrder
+description: Represents a draft order
+x-resourceId: draft-order
+properties:
+  id:
+    type: string
+    description: The draft order's ID
+    example: dorder_01G8TJFKBG38YYFQ035MSVG03C
+  status:
+    type: string
+    description: The status of the draft order
+    enum:
+      - open
+      - completed
+    default: open
+  display_id:
+    type: string
+    description: The draft order's display ID
+    example: 2
+  cart_id:
+    type: string
+    description: The ID of the cart associated with the draft order.
+    example: cart_01G8ZH853Y6TFXWPG5EYE81X63
+  cart:
+    description: A cart object. Available if the relation `cart` is expanded.
+    type: object
+  order_id:
+    type: string
+    description: The ID of the order associated with the draft order.
+    example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
+  order:
+    description: An order object. Available if the relation `order` is expanded.
+    type: object
+  canceled_at:
+    type: string
+    description: The date the draft order was canceled at.
+    format: date-time
+  completed_at:
+    type: string
+    description: The date the draft order was completed at.
+    format: date-time
+  no_notification_order:
+    type: boolean
+    description: Whether to send the customer notifications regarding order updates.
+    example: false
+  idempotency_key:
+    type: string
+    description: >-
+      Randomly generated key used to continue the completion of the cart
+      associated with the draft order in case of failure.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key
+      description: Learn more how to use the idempotency key.
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/fulfillment.yaml

@@ -0,0 +1,117 @@
+title: Fulfillment
+description: >-
+  Fulfillments are created once store operators can prepare the purchased goods.
+  Fulfillments will eventually be shipped and hold information about how to
+  track shipments. Fulfillments are created through a provider, which is
+  typically an external shipping aggregator, shipping partner og 3PL, most
+  plugins will have asynchronous communications with these providers through
+  webhooks in order to automatically update and synchronize the state of
+  Fulfillments.
+x-resourceId: fulfillment
+required:
+  - provider_id
+properties:
+  id:
+    type: string
+    description: The cart's ID
+    example: ful_01G8ZRTMQCA76TXNAT81KPJZRF
+  claim_order_id:
+    description: The id of the Claim that the Fulfillment belongs to.
+    type: string
+    example: null
+  claim_order:
+    description: A claim order object. Available if the relation `claim_order` is expanded.
+    type: object
+  swap_id:
+    description: The id of the Swap that the Fulfillment belongs to.
+    type: string
+    example: null
+  swap:
+    description: A swap object. Available if the relation `swap` is expanded.
+    type: object
+  order_id:
+    description: The id of the Order that the Fulfillment belongs to.
+    type: string
+    example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
+  order:
+    description: An order object. Available if the relation `order` is expanded.
+    type: object
+  provider_id:
+    description: >-
+      The id of the Fulfillment Provider responsible for handling the
+      fulfillment
+    type: string
+    example: manual
+  provider:
+    description: Available if the relation `provider` is expanded.
+    $ref: ./fulfillment_provider.yaml
+  items:
+    description: >-
+      The Fulfillment Items in the Fulfillment - these hold information about
+      how many of each Line Item has been fulfilled. Available if the relation
+      `items` is expanded.
+    type: array
+    items:
+      $ref: ./fulfillment_item.yaml
+  tracking_links:
+    description: >-
+      The Tracking Links that can be used to track the status of the
+      Fulfillment, these will usually be provided by the Fulfillment Provider.
+      Available if the relation `tracking_links` is expanded.
+    type: array
+    items:
+      $ref: ./tracking_link.yaml
+  tracking_numbers:
+    deprecated: true
+    description: >-
+      The tracking numbers that can be used to track the status of the
+      fulfillment.
+    type: array
+    items:
+      type: string
+  data:
+    description: >-
+      This contains all the data necessary for the Fulfillment provider to
+      handle the fulfillment.
+    type: object
+    example: {}
+  shipped_at:
+    description: The date with timezone at which the Fulfillment was shipped.
+    type: string
+    format: date-time
+  no_notification:
+    description: >-
+      Flag for describing whether or not notifications related to this should be
+      send.
+    type: boolean
+    example: false
+  canceled_at:
+    description: The date with timezone at which the Fulfillment was canceled.
+    type: string
+    format: date-time
+  idempotency_key:
+    type: string
+    description: >-
+      Randomly generated key used to continue the completion of the fulfillment
+      in case of failure.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key
+      description: Learn more how to use the idempotency key.
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/fulfillment_item.yaml

@@ -0,0 +1,28 @@
+title: Fulfillment Item
+description: >-
+  Correlates a Line Item with a Fulfillment, keeping track of the quantity of
+  the Line Item.
+x-resourceId: fulfillment_item
+required:
+  - fulfillment_id
+  - item_id
+  - quantity
+properties:
+  fulfillment_id:
+    description: The id of the Fulfillment that the Fulfillment Item belongs to.
+    type: string
+    example: ful_01G8ZRTMQCA76TXNAT81KPJZRF
+  item_id:
+    description: The id of the Line Item that the Fulfillment Item references.
+    type: string
+    example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
+  fulfillment:
+    description: A fulfillment object. Available if the relation `fulfillment` is expanded.
+    type: object
+  item:
+    description: Available if the relation `item` is expanded.
+    $ref: ./line_item.yaml
+  quantity:
+    description: The quantity of the Line Item that is included in the Fulfillment.
+    type: integer
+    example: 1

docs/api/admin/components/schemas/fulfillment_provider.yaml

@@ -0,0 +1,15 @@
+title: Fulfillment Provider
+description: Represents a fulfillment provider plugin and holds its installation status.
+x-resourceId: fulfillment_provider
+properties:
+  id:
+    description: The id of the fulfillment provider as given by the plugin.
+    type: string
+    example: manual
+  is_installed:
+    description: >-
+      Whether the plugin is installed in the current version. Plugins that are
+      no longer installed are not deleted by will have this field set to
+      `false`.
+    type: boolean
+    example: true

docs/api/admin/components/schemas/gift_card.yaml

@@ -0,0 +1,70 @@
+title: Gift Card
+description: >-
+  Gift Cards are redeemable and represent a value that can be used towards the
+  payment of an Order.
+x-resourceId: gift_card
+required:
+  - code
+  - value
+  - balance
+  - region_id
+properties:
+  id:
+    type: string
+    description: The cart's ID
+    example: gift_01G8XKBPBQY2R7RBET4J7E0XQZ
+  code:
+    description: >-
+      The unique code that identifies the Gift Card. This is used by the
+      Customer to redeem the value of the Gift Card.
+    type: string
+    example: 3RFT-MH2C-Y4YZ-XMN4
+  value:
+    description: The value that the Gift Card represents.
+    type: integer
+    example: 10
+  balance:
+    description: The remaining value on the Gift Card.
+    type: integer
+    example: 10
+  region_id:
+    type: string
+    description: The id of the Region in which the Gift Card is available.
+    example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
+  region:
+    description: A region object. Available if the relation `region` is expanded.
+    type: object
+  order_id:
+    type: string
+    description: The id of the Order that the Gift Card was purchased in.
+    example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
+  order:
+    description: An order object. Available if the relation `order` is expanded.
+    type: object
+  is_disabled:
+    description: >-
+      Whether the Gift Card has been disabled. Disabled Gift Cards cannot be
+      applied to carts.
+    type: boolean
+    example: false
+  ends_at:
+    description: The time at which the Gift Card can no longer be used.
+    type: string
+    format: date-time
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/gift_card_transaction.yaml

@@ -0,0 +1,43 @@
+title: Gift Card Transaction
+description: >-
+  Gift Card Transactions are created once a Customer uses a Gift Card to pay for
+  their Order
+x-resourceId: gift_card_transaction
+required:
+  - gift_card_id
+  - amount
+properties:
+  id:
+    type: string
+    description: The gift card transaction's ID
+    example: gct_01G8X9A7ESKAJXG2H0E6F1MW7A
+  gift_card_id:
+    description: The ID of the Gift Card that was used in the transaction.
+    type: string
+    example: gift_01G8XKBPBQY2R7RBET4J7E0XQZ
+  gift_card:
+    description: A gift card object. Available if the relation `gift_card` is expanded.
+    type: object
+  order_id:
+    description: The ID of the Order that the Gift Card was used to pay for.
+    type: string
+    example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
+  order:
+    description: An order object. Available if the relation `order` is expanded.
+    type: object
+  amount:
+    description: The amount that was used from the Gift Card.
+    type: integer
+    example: 10
+  created_at:
+    description: The date with timezone at which the resource was created.
+    type: string
+    format: date-time
+  is_taxable:
+    description: Whether the transaction is taxable or not.
+    type: boolean
+    example: false
+  tax_rate:
+    description: The tax rate of the transaction
+    type: number
+    example: 0

docs/api/admin/components/schemas/idempotency_key.yaml

@@ -0,0 +1,55 @@
+title: Idempotency Key
+description: >-
+  Idempotency Key is used to continue a process in case of any failure that
+  might occur.
+x-resourceId: idempotency_key
+required:
+  - idempotency_key
+properties:
+  id:
+    type: string
+    description: The idempotency key's ID
+    example: ikey_01G8X9A7ESKAJXG2H0E6F1MW7A
+  idempotency_key:
+    description: >-
+      The unique randomly generated key used to determine the state of a
+      process.
+    type: string
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key
+      description: Learn more how to use the idempotency key.
+  created_at:
+    description: Date which the idempotency key was locked.
+    type: string
+    format: date-time
+  locked_at:
+    description: Date which the idempotency key was locked.
+    type: string
+    format: date-time
+  request_method:
+    description: The method of the request
+    type: string
+    example: POST
+  request_params:
+    type: object
+    description: The parameters passed to the request
+    example:
+      id: cart_01G8ZH853Y6TFXWPG5EYE81X63
+  request_path:
+    description: The request's path
+    type: string
+    example: /store/carts/cart_01G8ZH853Y6TFXWPG5EYE81X63/complete
+  response_code:
+    type: string
+    description: The response's code.
+    example: 200
+  response_body:
+    type: object
+    description: The response's body
+    example:
+      id: cart_01G8ZH853Y6TFXWPG5EYE81X63
+  recovery_point:
+    type: string
+    description: Where to continue from.
+    default: started

docs/api/admin/components/schemas/image.yaml

@@ -0,0 +1,31 @@
+title: Image
+description: Images holds a reference to a URL at which the image file can be found.
+x-resourceId: image
+required:
+  - url
+properties:
+  id:
+    type: string
+    description: The image's ID
+    example: img_01G749BFYR6T8JTVW6SGW3K3E6
+  url:
+    description: The URL at which the image file can be found.
+    type: string
+    format: uri
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/invite.yaml

@@ -0,0 +1,50 @@
+title: Invite
+description: Represents an invite
+x-resourceId: invite
+required:
+  - user_email
+properties:
+  id:
+    type: string
+    description: The invite's ID
+    example: invite_01G8TKE4XYCTHSCK2GDEP47RE1
+  user_email:
+    type: string
+    description: The email of the user being invited.
+    format: email
+  role:
+    type: string
+    description: The user's role.
+    enum:
+      - admin
+      - member
+      - developer
+    default: member
+  accepted:
+    type: boolean
+    description: Whether the invite was accepted or not.
+    example: false
+  token:
+    type: string
+    description: The token used to accept the invite.
+  expores_at:
+    type: string
+    description: The date the invite expires at.
+    format: date-time
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/line_item.yaml

@@ -0,0 +1,172 @@
+title: Line Item
+description: >-
+  Line Items represent purchasable units that can be added to a Cart for
+  checkout. When Line Items are purchased they will get copied to the resulting
+  order and can eventually be referenced in Fulfillments and Returns. Line Items
+  may also be created when processing Swaps and Claims.
+x-resourceId: line_item
+required:
+  - title
+  - unit_price
+  - quantity
+properties:
+  id:
+    type: string
+    description: The cart's ID
+    example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
+  cart_id:
+    description: The ID of the Cart that the Line Item belongs to.
+    type: string
+    example: cart_01G8ZH853Y6TFXWPG5EYE81X63
+  cart:
+    description: A cart object. Available if the relation `cart` is expanded.
+    type: object
+  order_id:
+    description: The ID of the Order that the Line Item belongs to.
+    type: string
+    example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
+  order:
+    description: An order object. Available if the relation `order` is expanded.
+    type: object
+  swap_id:
+    description: The id of the Swap that the Line Item belongs to.
+    type: string
+    example: null
+  swap:
+    description: A swap object. Available if the relation `swap` is expanded.
+    type: object
+  claim_order_id:
+    description: The id of the Claim that the Line Item belongs to.
+    type: string
+    example: null
+  claim_order:
+    description: A claim order object. Available if the relation `claim_order` is expanded.
+    type: object
+  tax_lines:
+    description: Available if the relation `tax_lines` is expanded.
+    type: array
+    items:
+      $ref: ./line_item_tax_line.yaml
+  adjustments:
+    description: Available if the relation `adjustments` is expanded.
+    type: array
+    items:
+      $ref: ./line_item_adjustment.yaml
+  title:
+    description: >-
+      The title of the Line Item, this should be easily identifiable by the
+      Customer.
+    type: string
+    example: Medusa Coffee Mug
+  description:
+    description: A more detailed description of the contents of the Line Item.
+    type: string
+    example: One Size
+  thumbnail:
+    description: A URL string to a small image of the contents of the Line Item.
+    type: string
+    format: uri
+    example: https://medusa-public-images.s3.eu-west-1.amazonaws.com/coffee-mug.png
+  is_return:
+    description: Is the item being returned
+    type: boolean
+    example: false
+  is_giftcard:
+    description: Flag to indicate if the Line Item is a Gift Card.
+    type: boolean
+    example: false
+  should_merge:
+    description: >-
+      Flag to indicate if new Line Items with the same variant should be merged
+      or added as an additional Line Item.
+    type: boolean
+    example: false
+  allow_discounts:
+    description: >-
+      Flag to indicate if the Line Item should be included when doing discount
+      calculations.
+    type: boolean
+    example: false
+  has_shipping:
+    description: Flag to indicate if the Line Item has fulfillment associated with it.
+    type: boolean
+    example: false
+  unit_price:
+    description: >-
+      The price of one unit of the content in the Line Item. This should be in
+      the currency defined by the Cart/Order/Swap/Claim that the Line Item
+      belongs to.
+    type: boolean
+    example: 8000
+  variant_id:
+    description: The id of the Product Variant contained in the Line Item.
+    type: string
+    example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6
+  variant:
+    description: >-
+      A product variant object. The Product Variant contained in the Line Item.
+      Available if the relation `variant` is expanded.
+    type: object
+  quantity:
+    description: The quantity of the content in the Line Item.
+    type: integer
+    example: 1
+  fulfilled_quantity:
+    description: The quantity of the Line Item that has been fulfilled.
+    type: integer
+    example: 0
+  returned_quantity:
+    description: The quantity of the Line Item that has been returned.
+    type: integer
+    example: 0
+  shipped_quantity:
+    description: The quantity of the Line Item that has been shipped.
+    type: integer
+    example: 0
+  refundable:
+    description: >-
+      The amount that can be refunded from the given Line Item. Takes taxes and
+      discounts into consideration.
+    type: integer
+    example: 0
+  subtotal:
+    type: integer
+    description: The subtotal of the line item
+    example: 8000
+  tax_total:
+    type: integer
+    description: The total of tax of the line item
+    example: 0
+  total:
+    type: integer
+    description: The total amount of the line item
+    example: 8000
+  original_total:
+    type: integer
+    description: The original total amount of the line item
+    example: 8000
+  original_tax_total:
+    type: integer
+    description: The original tax total amount of the line item
+    example: 0
+  discount_total:
+    type: integer
+    description: The total of discount of the line item
+    example: 0
+  gift_card_total:
+    type: integer
+    description: The total of the gift card of the line item
+    example: 0
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/line_item_adjustment.yaml

@@ -0,0 +1,39 @@
+title: Line Item Adjustment
+description: Represents an Line Item Adjustment
+x-resourceId: line_item_adjustment
+required:
+  - item_id
+  - description
+  - amount
+properties:
+  id:
+    type: string
+    description: The invite's ID
+    example: lia_01G8TKE4XYCTHSCK2GDEP47RE1
+  item_id:
+    type: string
+    description: The ID of the line item
+    example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
+  item:
+    description: Available if the relation `item` is expanded.
+    $ref: ./line_item.yaml
+  description:
+    type: string
+    description: The line item's adjustment description
+    example: Adjusted item's price.
+  discount_id:
+    type: string
+    description: The ID of the discount associated with the adjustment
+    example: disc_01F0YESMW10MGHWJKZSDDMN0VN
+  discount:
+    description: Available if the relation `discount` is expanded.
+    $ref: ./discount.yaml
+  amount:
+    type: number
+    description: The adjustment amount
+    example: 1000
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/line_item_tax_line.yaml

@@ -0,0 +1,44 @@
+title: Line Item Tax Line
+description: Represents an Line Item Tax Line
+x-resourceId: line_item_tax_line
+required:
+  - item_id
+  - rate
+  - name
+properties:
+  id:
+    type: string
+    description: The line item tax line's ID
+    example: litl_01G1G5V2DRX1SK6NQQ8VVX4HQ8
+  item_id:
+    type: string
+    description: The ID of the line item
+    example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
+  item:
+    description: Available if the relation `item` is expanded.
+    $ref: ./line_item.yaml
+  code:
+    description: A code to identify the tax type by
+    type: string
+    example: tax01
+  name:
+    description: A human friendly name for the tax
+    type: string
+    example: Tax Example
+  rate:
+    description: The numeric rate to charge tax by
+    type: number
+    example: 10
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/money_amount.yaml

@@ -0,0 +1,84 @@
+title: Money Amount
+description: >-
+  Money Amounts represents an amount that a given Product Variant can be
+  purcased for. Each Money Amount either has a Currency or Region associated
+  with it to indicate the pricing in a given Currency or, for fully region-based
+  pricing, the given price in a specific Region. If region-based pricing is used
+  the amount will be in the currency defined for the Reigon.
+x-resourceId: money_amount
+required:
+  - currency_code
+  - amount
+properties:
+  id:
+    type: string
+    description: The money amount's ID
+    example: ma_01F0YESHRFQNH5S8Q0PK84YYZN
+  currency_code:
+    description: The 3 character currency code that the Money Amount is given in.
+    type: string
+    example: usd
+    externalDocs:
+      url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+      description: See a list of codes.
+  currency:
+    description: Available if the relation `currency` is expanded.
+    $ref: ./currency.yaml
+  amount:
+    description: >-
+      The amount in the smallest currecny unit (e.g. cents 100 cents to charge
+      $1) that the Product Variant will cost.
+    type: integer
+    example: 100
+  min_quantity:
+    description: >-
+      The minimum quantity that the Money Amount applies to. If this value is
+      not set, the Money Amount applies to all quantities.
+    type: integer
+    example: 1
+  max_quantity:
+    description: >-
+      The maximum quantity that the Money Amount applies to. If this value is
+      not set, the Money Amount applies to all quantities.
+    type: integer
+    example: 1
+  price_list_id:
+    type: string
+    description: The ID of the price list associated with the money amount
+    example: pl_01G8X3CKJXCG5VXVZ87H9KC09W
+  price_list:
+    description: Available if the relation `price_list` is expanded.
+    $ref: ./price_list.yaml
+  variant_id:
+    description: The id of the Product Variant contained in the Line Item.
+    type: string
+    example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6
+  variant:
+    description: >-
+      The Product Variant contained in the Line Item. Available if the relation
+      `variant` is expanded.
+    type: object
+  region_id:
+    type: string
+    description: The region's ID
+    example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
+  region:
+    description: A region object. Available if the relation `region` is expanded.
+    type: object
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/note.yaml

@@ -0,0 +1,50 @@
+title: Note
+description: >-
+  Notes are elements which we can use in association with different resources to
+  allow users to describe additional information in relation to these.
+x-resourceId: note
+required:
+  - value
+  - resource_type
+  - resource_id
+properties:
+  id:
+    type: string
+    description: The note's ID
+    example: note_01G8TM8ENBMC7R90XRR1G6H26Q
+  resource_type:
+    description: The type of resource that the Note refers to.
+    type: string
+    example: order
+  resource_id:
+    description: The ID of the resource that the Note refers to.
+    type: string
+    example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
+  value:
+    description: The contents of the note.
+    type: string
+    example: This order must be fulfilled on Monday
+  author_id:
+    type: string
+    description: The ID of the author (user)
+    example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V
+  author:
+    description: Available if the relation `author` is expanded.
+    $ref: ./user.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/notification.yaml

@@ -0,0 +1,67 @@
+title: Notification
+description: >-
+  Notifications a communications sent via Notification Providers as a reaction
+  to internal events such as `order.placed`. Notifications can be used to show a
+  chronological timeline for communications sent to a Customer regarding an
+  Order, and enables resends.
+x-resourceId: notification
+required:
+  - resource_type
+  - resource_id
+  - to
+properties:
+  id:
+    type: string
+    description: The notification's ID
+    example: noti_01G53V9Y6CKMCGBM1P0X7C28RX
+  event_name:
+    description: The name of the event that the notification was sent for.
+    type: string
+    example: order.placed
+  resource_type:
+    description: The type of resource that the Notification refers to.
+    type: string
+    example: order
+  resource_id:
+    description: The ID of the resource that the Notification refers to.
+    type: string
+    example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
+  customer_id:
+    description: The ID of the Customer that the Notification was sent to.
+    type: string
+    example: cus_01G2SG30J8C85S4A5CHM2S1NS2
+  customer:
+    description: A customer object. Available if the relation `customer` is expanded.
+    type: object
+  to:
+    description: >-
+      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
+    type: string
+    example: user@example.com
+  data:
+    description: >-
+      The data that the Notification was sent with. This contains all the data
+      necessary for the Notification Provider to initiate a resend.
+    type: object
+    example: {}
+  resends:
+    description: The resends that have been completed after the original Notification.
+    type: array
+    items:
+      $ref: ./notification_resend.yaml
+  provider_id:
+    description: The id of the Notification Provider that handles the Notification.
+    type: string
+    example: sengrid
+  provider:
+    description: Available if the relation `provider` is expanded.
+    $ref: ./notification_provider.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time

docs/api/admin/components/schemas/notification_provider.yaml

@@ -0,0 +1,17 @@
+title: Notification Provider
+description: Represents a notification provider plugin and holds its installation status.
+x-resourceId: notification_provider
+required:
+  - id
+properties:
+  id:
+    description: The id of the notification provider as given by the plugin.
+    type: string
+    example: sendgrid
+  is_installed:
+    description: >-
+      Whether the plugin is installed in the current version. Plugins that are
+      no longer installed are not deleted by will have this field set to
+      `false`.
+    type: boolean
+    default: true

docs/api/admin/components/schemas/notification_resend.yaml

@@ -0,0 +1,61 @@
+title: Notification Resend
+description: A resend of a Notification.
+x-resourceId: notification_resend
+properties:
+  id:
+    description: The notification resend's ID
+    type: string
+    example: noti_01F0YET45G9NHP08Z66CE4QKBS
+  event_name:
+    description: The name of the event that the notification was sent for.
+    type: string
+    example: order.placed
+  resource_type:
+    description: The type of resource that the Notification refers to.
+    type: string
+    example: order
+  resource_id:
+    description: The ID of the resource that the Notification refers to.
+    type: string
+    example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
+  customer_id:
+    description: The ID of the Customer that the Notification was sent to.
+    type: string
+    example: cus_01G2SG30J8C85S4A5CHM2S1NS2
+  customer:
+    description: A customer object. Available if the relation `customer` is expanded.
+    type: object
+  to:
+    description: >-
+      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
+    type: string
+    example: user@example.com
+  data:
+    description: >-
+      The data that the Notification was sent with. This contains all the data
+      necessary for the Notification Provider to initiate a resend.
+    type: object
+    example: {}
+  parent_id:
+    description: The ID of the Notification that was originally sent.
+    type: string
+    example: noti_01G53V9Y6CKMCGBM1P0X7C28RX
+  parent_notification:
+    description: Available if the relation `parent_notification` is expanded.
+    $ref: ./notification.yaml
+  provider_id:
+    description: The ID of the Notification Provider that handles the Notification.
+    type: string
+    example: sengrid
+  provider:
+    description: Available if the relation `provider` is expanded.
+    $ref: ./notification_provider.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time

docs/api/admin/components/schemas/order.yaml

@@ -0,0 +1,268 @@
+title: Order
+description: Represents an order
+x-resourceId: order
+required:
+  - customer_id
+  - email
+  - region_id
+  - currency_code
+properties:
+  id:
+    type: string
+    description: The order's ID
+    example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
+  status:
+    type: string
+    description: The order's status
+    enum:
+      - pending
+      - completed
+      - archived
+      - canceled
+      - requires_action
+    default: pending
+  fulfillment_status:
+    type: string
+    description: The order's fulfillment status
+    enum:
+      - not_fulfilled
+      - partially_fulfilled
+      - fulfilled
+      - partially_shipped
+      - shipped
+      - partially_returned
+      - returned
+      - canceled
+      - requires_action
+    default: not_fulfilled
+  payment_status:
+    type: string
+    description: The order's payment status
+    enum:
+      - not_paid
+      - awaiting
+      - captured
+      - partially_refunded
+      - refuneded
+      - canceled
+      - requires_action
+    default: not_paid
+  display_id:
+    type: integer
+    description: The order's display ID
+    example: 2
+  cart_id:
+    type: string
+    description: The ID of the cart associated with the order
+    example: cart_01G8ZH853Y6TFXWPG5EYE81X63
+  cart:
+    description: A cart object. Available if the relation `cart` is expanded.
+    type: object
+  customer_id:
+    type: string
+    description: The ID of the customer associated with the order
+    example: cus_01G2SG30J8C85S4A5CHM2S1NS2
+  customer:
+    description: A customer object. Available if the relation `customer` is expanded.
+    type: object
+  email:
+    description: The email associated with the order
+    type: string
+    format: email
+  billing_address_id:
+    type: string
+    description: The ID of the billing address associated with the order
+    example: addr_01G8ZH853YPY9B94857DY91YGW
+  billing_address:
+    description: Available if the relation `billing_address` is expanded.
+    $ref: ./address.yaml
+  shipping_address_id:
+    type: string
+    description: The ID of the shipping address associated with the order
+    example: addr_01G8ZH853YPY9B94857DY91YGW
+  shipping_address:
+    description: Available if the relation `shipping_address` is expanded.
+    $ref: ./address.yaml
+  region_id:
+    type: string
+    description: The region's ID
+    example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
+  region:
+    description: A region object. Available if the relation `region` is expanded.
+    type: object
+  currency_code:
+    description: The 3 character currency code that is used in the order
+    type: string
+    example: usd
+    externalDocs:
+      url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+      description: See a list of codes.
+  currency:
+    description: Available if the relation `currency` is expanded.
+    $ref: ./currency.yaml
+  tax_rate:
+    description: The order's tax rate
+    type: number
+    example: 0
+  discounts:
+    type: array
+    description: >-
+      The discounts used in the order. Available if the relation `discounts` is
+      expanded.
+    items:
+      type: object
+      description: A discount object.
+  gift_cards:
+    type: array
+    description: >-
+      The gift cards used in the order. Available if the relation `gift_cards`
+      is expanded.
+    items:
+      type: object
+      description: A gift card object.
+  shipping_methods:
+    type: array
+    description: >-
+      The shipping methods used in the order. Available if the relation
+      `shipping_methods` is expanded.
+    items:
+      $ref: ./shipping_method.yaml
+  payments:
+    type: array
+    description: >-
+      The payments used in the order. Available if the relation `payments` is
+      expanded.
+    items:
+      $ref: ./payment.yaml
+  fulfillments:
+    type: array
+    description: >-
+      The fulfillments used in the order. Available if the relation
+      `fulfillments` is expanded.
+    items:
+      $ref: ./fulfillment.yaml
+  returns:
+    type: array
+    description: >-
+      The returns associated with the order. Available if the relation `returns`
+      is expanded.
+    items:
+      type: object
+      description: A return object.
+  claims:
+    type: array
+    description: >-
+      The claims associated with the order. Available if the relation `claims`
+      is expanded.
+    items:
+      type: object
+      description: A claim order object.
+  refunds:
+    type: array
+    description: >-
+      The refunds associated with the order. Available if the relation `refunds`
+      is expanded.
+    items:
+      type: object
+      description: A refund object.
+  swaps:
+    type: array
+    description: >-
+      The swaps associated with the order. Available if the relation `swaps` is
+      expanded.
+    items:
+      type: object
+      description: A swap object.
+  draft_order_id:
+    type: string
+    description: The ID of the draft order this order is associated with.
+    example: null
+  draft_order:
+    description: A draft order object. Available if the relation `draft_order` is expanded.
+    type: object
+  items:
+    type: array
+    description: >-
+      The line items that belong to the order. Available if the relation `items`
+      is expanded.
+    items:
+      $ref: ./line_item.yaml
+  gift_card_transactions:
+    type: array
+    description: >-
+      The gift card transactions used in the order. Available if the relation
+      `gift_card_transactions` is expanded.
+    items:
+      $ref: ./gift_card_transaction.yaml
+  canceled_at:
+    type: string
+    description: The date the order was canceled on.
+    format: date-time
+  no_notification:
+    description: >-
+      Flag for describing whether or not notifications related to this should be
+      send.
+    type: boolean
+    example: false
+  idempotency_key:
+    type: string
+    description: >-
+      Randomly generated key used to continue the processing of the order in
+      case of failure.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key
+      description: Learn more how to use the idempotency key.
+  external_id:
+    description: The ID of an external order.
+    type: string
+    example: null
+  sales_channel_id:
+    type: string
+    description: The ID of the sales channel this order is associated with.
+    example: null
+  sales_channel:
+    description: >-
+      A sales channel object. Available if the relation `sales_channel` is
+      expanded.
+    type: object
+  shipping_total:
+    type: integer
+    description: The total of shipping
+    example: 1000
+  discount_total:
+    type: integer
+    description: The total of discount
+    example: 800
+  tax_total:
+    type: integer
+    description: The total of tax
+    example: 0
+  refunded_total:
+    type: integer
+    description: The total amount refunded if the order is returned.
+    example: 0
+  total:
+    type: integer
+    description: The total amount of the order
+    example: 8200
+  subtotal:
+    type: integer
+    description: The subtotal of the order
+    example: 8000
+  paid_total:
+    type: integer
+    description: The total amount paid
+    example: 8000
+  refundable_amount:
+    type: integer
+    description: The amount that can be refunded
+    example: 8200
+  gift_card_total:
+    type: integer
+    description: The total of gift cards
+    example: 0
+  gift_card_tax_total:
+    type: integer
+    description: The total of gift cards with taxes
+    example: 0

docs/api/admin/components/schemas/payment.yaml

@@ -0,0 +1,96 @@
+title: Payment
+description: >-
+  Payments represent an amount authorized with a given payment method, Payments
+  can be captured, canceled or refunded.
+x-resourceId: payment
+required:
+  - amount
+  - currency_code
+  - provider_id
+properties:
+  id:
+    type: string
+    description: The payment's ID
+    example: pay_01G2SJNT6DEEWDFNAJ4XWDTHKE
+  swap_id:
+    description: The ID of the Swap that the Payment is used for.
+    type: string
+    example: null
+  swap:
+    description: A swap object. Available if the relation `swap` is expanded.
+    type: object
+  cart_id:
+    description: The id of the Cart that the Payment Session is created for.
+    type: string
+  cart:
+    description: A cart object. Available if the relation `cart` is expanded.
+    type: object
+  order_id:
+    description: The ID of the Order that the Payment is used for.
+    type: string
+    example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
+  order:
+    description: An order object. Available if the relation `order` is expanded.
+    type: object
+  amount:
+    description: The amount that the Payment has been authorized for.
+    type: integer
+    example: 100
+  currency_code:
+    description: The 3 character ISO currency code that the Payment is completed in.
+    type: string
+    example: usd
+    externalDocs:
+      url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+      description: See a list of codes.
+  currency:
+    description: Available if the relation `currency` is expanded.
+    $ref: ./currency.yaml
+  amount_refunded:
+    description: >-
+      The amount of the original Payment amount that has been refunded back to
+      the Customer.
+    type: integer
+    example: 0
+  provider_id:
+    description: The id of the Payment Provider that is responsible for the Payment
+    type: string
+    example: manual
+  data:
+    description: >-
+      The data required for the Payment Provider to identify, modify and process
+      the Payment. Typically this will be an object that holds an id to the
+      external payment session, but can be an empty object if the Payment
+      Provider doesn't hold any state.
+    type: object
+    example: {}
+  captured_at:
+    description: The date with timezone at which the Payment was captured.
+    type: string
+    format: date-time
+  canceled_at:
+    description: The date with timezone at which the Payment was canceled.
+    type: string
+    format: date-time
+  idempotency_key:
+    type: string
+    description: >-
+      Randomly generated key used to continue the completion of a payment in
+      case of failure.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key
+      description: Learn more how to use the idempotency key.
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/payment_provider.yaml

@@ -0,0 +1,17 @@
+title: Payment Provider
+description: Represents a Payment Provider plugin and holds its installation status.
+x-resourceId: payment_provider
+required:
+  - id
+properties:
+  id:
+    description: The id of the payment provider as given by the plugin.
+    type: string
+    example: manual
+  is_installed:
+    description: >-
+      Whether the plugin is installed in the current version. Plugins that are
+      no longer installed are not deleted by will have this field set to
+      `false`.
+    type: boolean
+    default: true

docs/api/admin/components/schemas/payment_session.yaml

@@ -0,0 +1,74 @@
+title: Payment Session
+description: >-
+  Payment Sessions are created when a Customer initilizes the checkout flow, and
+  can be used to hold the state of a payment flow. Each Payment Session is
+  controlled by a Payment Provider, who is responsible for the communication
+  with external payment services. Authorized Payment Sessions will eventually
+  get promoted to Payments to indicate that they are authorized for
+  capture/refunds/etc.
+x-resourceId: payment_session
+required:
+  - cart_id
+  - provider_id
+  - status
+properties:
+  id:
+    type: string
+    description: The payment session's ID
+    example: ps_01G901XNSRM2YS3ASN9H5KG3FZ
+  cart_id:
+    description: The id of the Cart that the Payment Session is created for.
+    type: string
+    example: cart_01G8ZH853Y6TFXWPG5EYE81X63
+  cart:
+    description: A cart object. Available if the relation `cart` is expanded.
+    type: object
+  provider_id:
+    description: The id of the Payment Provider that is responsible for the Payment Session
+    type: string
+    example: manual
+  is_selected:
+    description: >-
+      A flag to indicate if the Payment Session has been selected as the method
+      that will be used to complete the purchase.
+    type: boolean
+    example: true
+  status:
+    description: >-
+      Indicates the status of the Payment Session. Will default to `pending`,
+      and will eventually become `authorized`. Payment Sessions may have the
+      status of `requires_more` to indicate that further actions are to be
+      completed by the Customer.
+    type: string
+    enum:
+      - authorized
+      - pending
+      - requires_more
+      - error
+      - canceled
+    example: pending
+  data:
+    description: >-
+      The data required for the Payment Provider to identify, modify and process
+      the Payment Session. Typically this will be an object that holds an id to
+      the external payment session, but can be an empty object if the Payment
+      Provider doesn't hold any state.
+    type: object
+    example: {}
+  idempotency_key:
+    type: string
+    description: >-
+      Randomly generated key used to continue the completion of a cart in case
+      of failure.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key
+      description: Learn more how to use the idempotency key.
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time

docs/api/admin/components/schemas/price_list.yaml

@@ -0,0 +1,70 @@
+title: Price List
+description: >-
+  Price Lists represents a set of prices that overrides the default price for
+  one or more product variants.
+x-resourceId: price_list
+required:
+  - name
+  - description
+properties:
+  id:
+    type: string
+    description: The price list's ID
+    example: pl_01G8X3CKJXCG5VXVZ87H9KC09W
+  name:
+    type: string
+    description: The price list's name
+    example: VIP Prices
+  description:
+    type: string
+    description: The price list's description
+    example: Prices for VIP customers
+  type:
+    description: The type of Price List. This can be one of either `sale` or `override`.
+    type: string
+    enum:
+      - sale
+      - override
+    default: sale
+  status:
+    description: The status of the Price List
+    type: string
+    enum:
+      - active
+      - draft
+    default: draft
+  starts_at:
+    description: The date with timezone that the Price List starts being valid.
+    type: string
+    format: date-time
+  ends_at:
+    description: The date with timezone that the Price List stops being valid.
+    type: string
+    format: date-time
+  customer_groups:
+    description: >-
+      The Customer Groups that the Price List applies to. Available if the
+      relation `customer_groups` is expanded.
+    type: array
+    items:
+      type: object
+      description: A customer group object.
+  prices:
+    description: >-
+      The Money Amounts that are associated with the Price List. Available if
+      the relation `prices` is expanded.
+    type: array
+    items:
+      $ref: ./money_amount.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time

docs/api/admin/components/schemas/product.yaml

@@ -0,0 +1,188 @@
+title: Product
+description: >-
+  Products are a grouping of Product Variants that have common properties such
+  as images and descriptions. Products can have multiple options which define
+  the properties that Product Variants differ by.
+x-resourceId: product
+required:
+  - title
+  - profile_id
+properties:
+  id:
+    type: string
+    description: The product's ID
+    example: prod_01G1G5V2MBA328390B5AXJ610F
+  title:
+    description: A title that can be displayed for easy identification of the Product.
+    type: string
+    example: Medusa Coffee Mug
+  subtitle:
+    description: An optional subtitle that can be used to further specify the Product.
+    type: string
+  description:
+    description: A short description of the Product.
+    type: string
+    example: Every programmer's best friend.
+  handle:
+    description: A unique identifier for the Product (e.g. for slug structure).
+    type: string
+    example: coffee-mug
+  is_giftcard:
+    description: >-
+      Whether the Product represents a Gift Card. Products that represent Gift
+      Cards will automatically generate a redeemable Gift Card code once they
+      are purchased.
+    type: boolean
+    default: false
+  status:
+    description: The status of the product
+    type: string
+    enum:
+      - draft
+      - proposed
+      - published
+      - rejected
+    default: draft
+  images:
+    description: Images of the Product. Available if the relation `images` is expanded.
+    type: array
+    items:
+      $ref: ./image.yaml
+  thumbnail:
+    description: A URL to an image file that can be used to identify the Product.
+    type: string
+    format: uri
+  options:
+    description: >-
+      The Product Options that are defined for the Product. Product Variants of
+      the Product will have a unique combination of Product Option Values.
+      Available if the relation `options` is expanded.
+    type: array
+    items:
+      $ref: ./product_option.yaml
+  variants:
+    description: >-
+      The Product Variants that belong to the Product. Each will have a unique
+      combination of Product Option Values. Available if the relation `variants`
+      is expanded.
+    type: array
+    items:
+      $ref: ./product_variant.yaml
+  profile_id:
+    description: >-
+      The ID of the Shipping Profile that the Product belongs to. Shipping
+      Profiles have a set of defined Shipping Options that can be used to
+      Fulfill a given set of Products.
+    type: string
+    example: sp_01G1G5V239ENSZ5MV4JAR737BM
+  profile:
+    description: Available if the relation `profile` is expanded.
+    $ref: ./shipping_profile.yaml
+  weight:
+    description: >-
+      The weight of the Product Variant. May be used in shipping rate
+      calculations.
+    type: number
+    example: null
+  height:
+    description: >-
+      The height of the Product Variant. May be used in shipping rate
+      calculations.
+    type: number
+    example: null
+  width:
+    description: >-
+      The width of the Product Variant. May be used in shipping rate
+      calculations.
+    type: number
+    example: null
+  length:
+    description: >-
+      The length of the Product Variant. May be used in shipping rate
+      calculations.
+    type: number
+    example: null
+  hs_code:
+    description: >-
+      The Harmonized System code of the Product Variant. May be used by
+      Fulfillment Providers to pass customs information to shipping carriers.
+    type: string
+    example: null
+  origin_country:
+    description: >-
+      The country in which the Product Variant was produced. May be used by
+      Fulfillment Providers to pass customs information to shipping carriers.
+    type: string
+    example: null
+  mid_code:
+    description: >-
+      The Manufacturers Identification code that identifies the manufacturer of
+      the Product Variant. May be used by Fulfillment Providers to pass customs
+      information to shipping carriers.
+    type: string
+    example: null
+  material:
+    description: >-
+      The material and composition that the Product Variant is made of, May be
+      used by Fulfillment Providers to pass customs information to shipping
+      carriers.
+    type: string
+    example: null
+  collection_id:
+    type: string
+    description: The Product Collection that the Product belongs to
+    example: pcol_01F0YESBFAZ0DV6V831JXWH0BG
+  collection:
+    description: >-
+      A product collection object. Available if the relation `collection` is
+      expanded.
+    type: object
+  type_id:
+    type: string
+    description: The Product type that the Product belongs to
+    example: ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A
+  type:
+    description: Available if the relation `type` is expanded.
+    $ref: ./product_type.yaml
+  tags:
+    description: >-
+      The Product Tags assigned to the Product. Available if the relation `tags`
+      is expanded.
+    type: array
+    items:
+      $ref: ./product_tag.yaml
+  discountable:
+    description: >-
+      Whether the Product can be discounted. Discounts will not apply to Line
+      Items of this Product when this flag is set to `false`.
+    type: boolean
+    default: true
+  external_id:
+    description: The external ID of the product
+    type: string
+    example: null
+  sales_channels:
+    description: >-
+      The sales channels the product is associated with. Available if the
+      relation `sales_channels` is expanded.
+    type: array
+    items:
+      type: object
+      description: A sales channel object.
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/product_collection.yaml

@@ -0,0 +1,45 @@
+title: Product Collection
+description: Product Collections represents a group of Products that are related.
+x-resourceId: product_collection
+required:
+  - title
+properties:
+  id:
+    type: string
+    description: The product collection's ID
+    example: pcol_01F0YESBFAZ0DV6V831JXWH0BG
+  title:
+    description: The title that the Product Collection is identified by.
+    type: string
+    example: Summer Collection
+  handle:
+    description: >-
+      A unique string that identifies the Product Collection - can for example
+      be used in slug structures.
+    type: string
+    example: summer-collection
+  products:
+    description: >-
+      The Products contained in the Product Collection. Available if the
+      relation `products` is expanded.
+    type: array
+    items:
+      type: object
+      description: A product collection object.
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/product_option.yaml

@@ -0,0 +1,49 @@
+title: Product Option
+description: >-
+  Product Options define properties that may vary between different variants of
+  a Product. Common Product Options are "Size" and "Color", but Medusa doesn't
+  limit what Product Options that can be defined.
+x-resourceId: product_option
+required:
+  - title
+  - product_id
+properties:
+  id:
+    type: string
+    description: The product option's ID
+    example: opt_01F0YESHQBZVKCEXJ24BS6PCX3
+  title:
+    description: The title that the Product Option is defined by (e.g. "Size").
+    type: string
+    example: Size
+  values:
+    description: >-
+      The Product Option Values that are defined for the Product Option.
+      Available if the relation `values` is expanded.
+    type: array
+    items:
+      $ref: ./product_option_value.yaml
+  product_id:
+    description: The ID of the Product that the Product Option is defined for.
+    type: string
+    example: prod_01G1G5V2MBA328390B5AXJ610F
+  product:
+    description: A product object. Available if the relation `product` is expanded.
+    type: object
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/product_option_value.yaml

@@ -0,0 +1,54 @@
+title: Product Option Value
+description: >-
+  A value given to a Product Variant's option set. Product Variant have a
+  Product Option Value for each of the Product Options defined on the Product.
+x-resourceId: product_option_value
+required:
+  - value
+  - option_id
+  - variant_id
+properties:
+  id:
+    type: string
+    description: The product option value's ID
+    example: optval_01F0YESHR7S6ECD03RF6W12DSJ
+  value:
+    description: >-
+      The value that the Product Variant has defined for the specific Product
+      Option (e.g. if the Product Option is "Size" this value could be "Small",
+      "Medium" or "Large").
+    type: string
+    example: large
+  option_id:
+    description: The ID of the Product Option that the Product Option Value is defined for.
+    type: string
+    example: opt_01F0YESHQBZVKCEXJ24BS6PCX3
+  option:
+    description: Available if the relation `option` is expanded.
+    $ref: ./product_option.yaml
+  variant_id:
+    description: >-
+      The ID of the Product Variant that the Product Option Value is defined
+      for.
+    type: string
+    example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6
+  variant:
+    description: Available if the relation `variant` is expanded.
+    $ref: ./product_variant.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/product_tag.yaml

@@ -0,0 +1,31 @@
+title: Product Tag
+description: Product Tags can be added to Products for easy filtering and grouping.
+x-resourceId: product_tag
+required:
+  - value
+properties:
+  id:
+    type: string
+    description: The product tag's ID
+    example: ptag_01G8K2MTMG9168F2B70S1TAVK3
+  value:
+    description: The value that the Product Tag represents
+    type: string
+    example: Pants
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/product_tax_rate.yaml

@@ -0,0 +1,36 @@
+title: Product Tax Rate
+description: >-
+  Associates a tax rate with a product to indicate that the product is taxed in
+  a certain way
+x-resourceId: product_tax_rate
+required:
+  - product_id
+  - rate_id
+properties:
+  product_id:
+    description: The ID of the Product
+    type: string
+    example: prod_01G1G5V2MBA328390B5AXJ610F
+  product:
+    description: Available if the relation `product` is expanded.
+    $ref: ./product.yaml
+  rate_id:
+    description: The ID of the Tax Rate
+    type: string
+    example: txr_01G8XDBAWKBHHJRKH0AV02KXBR
+  tax_rate:
+    description: Available if the relation `tax_rate` is expanded.
+    $ref: ./tax_rate.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/product_type.yaml

@@ -0,0 +1,31 @@
+title: Product Type
+description: Product Type can be added to Products for filtering and reporting purposes.
+x-resourceId: product_type
+required:
+  - value
+properties:
+  id:
+    type: string
+    description: The product type's ID
+    example: ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A
+  value:
+    description: The value that the Product Type represents.
+    type: string
+    example: Clothing
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/product_type_tax_rate.yaml

@@ -0,0 +1,36 @@
+title: Product Type Tax Rate
+description: >-
+  Associates a tax rate with a product type to indicate that the product type is
+  taxed in a certain way
+x-resourceId: product_type_tax_rate
+required:
+  - product_type_id
+  - rate_id
+properties:
+  product_type_id:
+    description: The ID of the Product type
+    type: string
+    example: ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A
+  product_type:
+    description: Available if the relation `product_type` is expanded.
+    $ref: ./product_type.yaml
+  rate_id:
+    description: The id of the Tax Rate
+    type: string
+    example: txr_01G8XDBAWKBHHJRKH0AV02KXBR
+  tax_rate:
+    description: Available if the relation `tax_rate` is expanded.
+    $ref: ./tax_rate.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/product_variant.yaml

@@ -0,0 +1,149 @@
+title: Product Variant
+description: >-
+  Product Variants represent a Product with a specific set of Product Option
+  configurations. The maximum number of Product Variants that a Product can have
+  is given by the number of available Product Option combinations.
+x-resourceId: product_variant
+required:
+  - title
+  - product_id
+  - inventory_quantity
+properties:
+  id:
+    type: string
+    description: The product variant's ID
+    example: variant_01G1G5V2MRX2V3PVSR2WXYPFB6
+  title:
+    description: >-
+      A title that can be displayed for easy identification of the Product
+      Variant.
+    type: string
+    example: Small
+  product_id:
+    description: The ID of the Product that the Product Variant belongs to.
+    type: string
+    example: prod_01G1G5V2MBA328390B5AXJ610F
+  product:
+    description: A product object. Available if the relation `product` is expanded.
+    type: object
+  prices:
+    description: >-
+      The Money Amounts defined for the Product Variant. Each Money Amount
+      represents a price in a given currency or a price in a specific Region.
+      Available if the relation `prices` is expanded.
+    type: array
+    items:
+      $ref: ./money_amount.yaml
+  sku:
+    description: >-
+      The unique stock keeping unit used to identify the Product Variant. This
+      will usually be a unqiue identifer for the item that is to be shipped, and
+      can be referenced across multiple systems.
+    type: string
+    example: shirt-123
+  barcode:
+    description: >-
+      A generic field for a GTIN number that can be used to identify the Product
+      Variant.
+    type: string
+    example: null
+  ean:
+    description: An EAN barcode number that can be used to identify the Product Variant.
+    type: string
+    example: null
+  upc:
+    description: A UPC barcode number that can be used to identify the Product Variant.
+    type: string
+    example: null
+  variant_rank:
+    description: The ranking of this variant
+    type: number
+    default: 0
+  inventory_quantity:
+    description: The current quantity of the item that is stocked.
+    type: integer
+    example: 100
+  allow_backorder:
+    description: >-
+      Whether the Product Variant should be purchasable when
+      `inventory_quantity` is 0.
+    type: boolean
+    default: false
+  manage_inventory:
+    description: Whether Medusa should manage inventory for the Product Variant.
+    type: boolean
+    default: true
+  hs_code:
+    description: >-
+      The Harmonized System code of the Product Variant. May be used by
+      Fulfillment Providers to pass customs information to shipping carriers.
+    type: string
+    example: null
+  origin_country:
+    description: >-
+      The country in which the Product Variant was produced. May be used by
+      Fulfillment Providers to pass customs information to shipping carriers.
+    type: string
+    example: null
+  mid_code:
+    description: >-
+      The Manufacturers Identification code that identifies the manufacturer of
+      the Product Variant. May be used by Fulfillment Providers to pass customs
+      information to shipping carriers.
+    type: string
+    example: null
+  material:
+    description: >-
+      The material and composition that the Product Variant is made of, May be
+      used by Fulfillment Providers to pass customs information to shipping
+      carriers.
+    type: string
+    example: null
+  weight:
+    description: >-
+      The weight of the Product Variant. May be used in shipping rate
+      calculations.
+    type: number
+    example: null
+  height:
+    description: >-
+      The height of the Product Variant. May be used in shipping rate
+      calculations.
+    type: number
+    example: null
+  width:
+    description: >-
+      The width of the Product Variant. May be used in shipping rate
+      calculations.
+    type: number
+    example: null
+  length:
+    description: >-
+      The length of the Product Variant. May be used in shipping rate
+      calculations.
+    type: number
+    example: null
+  options:
+    description: >-
+      The Product Option Values specified for the Product Variant. Available if
+      the relation `options` is expanded.
+    type: array
+    items:
+      $ref: ./product_option_value.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/refund.yaml

@@ -0,0 +1,64 @@
+title: Refund
+description: >-
+  Refund represent an amount of money transfered back to the Customer for a
+  given reason. Refunds may occur in relation to Returns, Swaps and Claims, but
+  can also be initiated by a store operator.
+x-resourceId: refund
+required:
+  - order_id
+  - amount
+properties:
+  id:
+    type: string
+    description: The refund's ID
+    example: ref_01G1G5V27GYX4QXNARRQCW1N8T
+  order_id:
+    description: The id of the Order that the Refund is related to.
+    type: string
+    example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
+  amount:
+    description: The amount that has be refunded to the Customer.
+    type: integer
+    example: 1000
+  note:
+    description: An optional note explaining why the amount was refunded.
+    type: string
+    example: I didn't like it
+  reason:
+    description: >-
+      The reason given for the Refund, will automatically be set when processed
+      as part of a Swap, Claim or Return.
+    type: string
+    enum:
+      - discount
+      - return
+      - swap
+      - claim
+      - other
+    example: return
+  idempotency_key:
+    type: string
+    description: >-
+      Randomly generated key used to continue the completion of the refund in
+      case of failure.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key
+      description: Learn more how to use the idempotency key.
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/region.yaml

@@ -0,0 +1,102 @@
+title: Region
+description: >-
+  Regions hold settings for how Customers in a given geographical location shop.
+  The is, for example, where currencies and tax rates are defined. A Region can
+  consist of multiple countries to accomodate common shopping settings across
+  countries.
+x-resourceId: region
+required:
+  - name
+  - currency_code
+  - tax_rate
+properties:
+  id:
+    type: string
+    description: The cart's ID
+    example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
+  name:
+    description: >-
+      The name of the region as displayed to the customer. If the Region only
+      has one country it is recommended to write the country name.
+    type: string
+    example: EU
+  currency_code:
+    description: The 3 character currency code that the Region uses.
+    type: string
+    example: usd
+    externalDocs:
+      url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+      description: See a list of codes.
+  currency:
+    description: Available if the relation `currency` is expanded.
+    $ref: ./currency.yaml
+  tax_rate:
+    description: The tax rate that should be charged on purchases in the Region.
+    type: number
+    example: 0
+  tax_rates:
+    description: >-
+      The tax rates that are included in the Region. Available if the relation
+      `tax_rates` is expanded.
+    type: array
+    items:
+      $ref: ./tax_rate.yaml
+  tax_code:
+    description: >-
+      The tax code used on purchases in the Region. This may be used by other
+      systems for accounting purposes.
+    type: string
+    example: null
+  gift_cards_taxable:
+    description: Whether the gift cards are taxable or not in this region.
+    type: boolean
+    default: true
+  automatic_taxes:
+    description: Whether taxes should be automated in this region.
+    type: boolean
+    default: true
+  countries:
+    description: >-
+      The countries that are included in the Region. Available if the relation
+      `countries` is expanded.
+    type: array
+    items:
+      $ref: ./country.yaml
+  tax_provider_id:
+    type: string
+    description: The ID of the tax provider used in this region
+    example: null
+  tax_provider:
+    description: Available if the relation `tax_provider` is expanded.
+    $ref: ./tax_provider.yaml
+  payment_providers:
+    description: >-
+      The Payment Providers that can be used to process Payments in the Region.
+      Available if the relation `payment_providers` is expanded.
+    type: array
+    items:
+      $ref: ./payment_provider.yaml
+  fulfillment_providers:
+    description: >-
+      The Fulfillment Providers that can be used to fulfill orders in the
+      Region. Available if the relation `payment_providers` is expanded.
+    type: array
+    items:
+      $ref: ./fulfillment_provider.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/return.yaml

@@ -0,0 +1,98 @@
+title: Return
+description: >-
+  Return orders hold information about Line Items that a Customer wishes to send
+  back, along with how the items will be returned. Returns can be used as part
+  of a Swap.
+x-resourceId: return
+required:
+  - refund_amount
+properties:
+  id:
+    type: string
+    description: The return's ID
+    example: ret_01F0YET7XPCMF8RZ0Y151NZV2V
+  status:
+    description: Status of the Return.
+    type: string
+    enum:
+      - requested
+      - received
+      - requires_action
+      - canceled
+    default: requested
+  items:
+    description: >-
+      The Return Items that will be shipped back to the warehouse. Available if
+      the relation `items` is expanded.
+    type: array
+    items:
+      $ref: ./return_item.yaml
+  swap_id:
+    description: The ID of the Swap that the Return is a part of.
+    type: string
+    example: null
+  swap:
+    description: A swap object. Available if the relation `swap` is expanded.
+    type: object
+  order_id:
+    description: The ID of the Order that the Return is made from.
+    type: string
+    example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
+  order:
+    description: An order object. Available if the relation `order` is expanded.
+    type: object
+  claim_order_id:
+    description: The ID of the Claim that the Return is a part of.
+    type: string
+    example: null
+  claim_order:
+    description: A claim order object. Available if the relation `claim_order` is expanded.
+    type: object
+  shipping_method:
+    description: >-
+      The Shipping Method that will be used to send the Return back. Can be null
+      if the Customer facilitates the return shipment themselves. Available if
+      the relation `shipping_method` is expanded.
+    type: array
+    items:
+      $ref: ./shipping_method.yaml
+  shipping_data:
+    description: >-
+      Data about the return shipment as provided by the Fulfilment Provider that
+      handles the return shipment.
+    type: object
+    example: {}
+  refund_amount:
+    description: The amount that should be refunded as a result of the return.
+    type: integer
+    example: 1000
+  no_notification:
+    description: When set to true, no notification will be sent related to this return.
+    type: boolean
+    example: false
+  idempotency_key:
+    type: string
+    description: >-
+      Randomly generated key used to continue the completion of the return in
+      case of failure.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key
+      description: Learn more how to use the idempotency key.
+  received_at:
+    description: The date with timezone at which the return was received.
+    type: string
+    format: date-time
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/return_item.yaml

@@ -0,0 +1,57 @@
+title: Return Item
+description: >-
+  Correlates a Line Item with a Return, keeping track of the quantity of the
+  Line Item that will be returned.
+x-resourceId: return_item
+required:
+  - return_id
+  - item_id
+properties:
+  return_id:
+    description: The id of the Return that the Return Item belongs to.
+    type: string
+    example: ret_01F0YET7XPCMF8RZ0Y151NZV2V
+  return_order:
+    description: Available if the relation `return_order` is expanded.
+    $ref: ./return.yaml
+  item_id:
+    description: The id of the Line Item that the Return Item references.
+    type: string
+    example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
+  item:
+    description: Available if the relation `item` is expanded.
+    $ref: ./line_item.yaml
+  quantity:
+    description: The quantity of the Line Item that is included in the Return.
+    type: integer
+    example: 1
+  is_requested:
+    description: >-
+      Whether the Return Item was requested initially or received unexpectedly
+      in the warehouse.
+    type: boolean
+    default: true
+  requested_quantity:
+    description: The quantity that was originally requested to be returned.
+    type: integer
+    example: 1
+  recieved_quantity:
+    description: The quantity that was received in the warehouse.
+    type: integer
+    example: 1
+  reason_id:
+    description: The ID of the reason for returning the item.
+    type: string
+    example: rr_01G8X82GCCV2KSQHDBHSSAH5TQ
+  reason:
+    description: Available if the relation `reason` is expanded.
+    $ref: ./return_reason.yaml
+  note:
+    description: An optional note with additional details about the Return.
+    type: string
+    example: I didn't like it.
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/return_reason.yaml

@@ -0,0 +1,52 @@
+title: Return Reason
+description: >-
+  A Reason for why a given product is returned. A Return Reason can be used on
+  Return Items in order to indicate why a Line Item was returned.
+x-resourceId: return_reason
+required:
+  - value
+  - label
+properties:
+  id:
+    type: string
+    description: The cart's ID
+    example: rr_01G8X82GCCV2KSQHDBHSSAH5TQ
+  description:
+    description: A description of the Reason.
+    type: string
+    example: Items that are damaged
+  label:
+    description: A text that can be displayed to the Customer as a reason.
+    type: string
+    example: Damaged goods
+  value:
+    description: The value to identify the reason by.
+    type: string
+    example: damaged
+  parent_return_reason_id:
+    type: string
+    description: The ID of the parent reason.
+    example: null
+  parent_return_reason:
+    description: Available if the relation `parent_return_reason` is expanded.
+    $ref: ./return_reason.yaml
+  return_reason_children:
+    description: Available if the relation `return_reason_children` is expanded.
+    $ref: ./return_reason.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/sales_channel.yaml

@@ -0,0 +1,34 @@
+title: Sales Channel
+description: A Sales Channel
+x-resourceId: sales_channel
+required:
+  - name
+properties:
+  id:
+    type: string
+    description: The sales channel's ID
+    example: sc_01G8X9A7ESKAJXG2H0E6F1MW7A
+  name:
+    description: The name of the sales channel.
+    type: string
+    example: Market
+  description:
+    description: The description of the sales channel.
+    type: string
+    example: Multi-vendor market
+  is_disabled:
+    description: Specify if the sales channel is enabled or disabled.
+    type: boolean
+    default: false
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time

docs/api/admin/components/schemas/sales_channel_tax_line.yaml

@@ -0,0 +1,44 @@
+title: Sales Channel
+description: A Sales Channel
+x-resourceId: sales_channel_tax_line
+required:
+  - shipping_method_id
+  - rate
+  - name
+properties:
+  id:
+    type: string
+    description: The line item tax line's ID
+    example: smtl_01G1G5V2DRX1SK6NQQ8VVX4HQ8
+  shipping_method_id:
+    type: string
+    description: The ID of the line item
+    example: sm_01F0YET7DR2E7CYVSDHM593QG2
+  shipping_method:
+    description: Available if the relation `shipping_method` is expanded.
+    $ref: ./shipping_method.yaml
+  code:
+    description: A code to identify the tax type by
+    type: string
+    example: tax01
+  name:
+    description: A human friendly name for the tax
+    type: string
+    example: Tax Example
+  rate:
+    description: The numeric rate to charge tax by
+    type: number
+    example: 10
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/shipping_method.yaml

@@ -0,0 +1,76 @@
+title: Shipping Method
+description: >-
+  Shipping Methods represent a way in which an Order or Return can be shipped.
+  Shipping Methods are built from a Shipping Option, but may contain additional
+  details, that can be necessary for the Fulfillment Provider to handle the
+  shipment.
+x-resourceId: shipping_method
+required:
+  - shipping_option_id
+  - price
+properties:
+  id:
+    type: string
+    description: The shipping method's ID
+    example: sm_01F0YET7DR2E7CYVSDHM593QG2
+  shipping_option_id:
+    description: The id of the Shipping Option that the Shipping Method is built from.
+    type: string
+    example: so_01G1G5V27GYX4QXNARRQCW1N8T
+  shipping_option:
+    description: Available if the relation `shipping_option` is expanded.
+    $ref: ./shipping_option.yaml
+  order_id:
+    description: The id of the Order that the Shipping Method is used on.
+    type: string
+    example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
+  order:
+    description: An order object. Available if the relation `order` is expanded.
+    type: object
+  return_id:
+    description: The id of the Return that the Shipping Method is used on.
+    type: string
+    example: null
+  return_order:
+    description: A return object. Available if the relation `return_order` is expanded.
+    type: object
+  swap_id:
+    description: The id of the Swap that the Shipping Method is used on.
+    type: string
+    example: null
+  swap:
+    description: A swap object. Available if the relation `swap` is expanded.
+    type: object
+  cart_id:
+    description: The id of the Cart that the Shipping Method is used on.
+    type: string
+    example: cart_01G8ZH853Y6TFXWPG5EYE81X63
+  cart:
+    description: A cart object. Available if the relation `cart` is expanded.
+    type: object
+  claim_order_id:
+    description: The id of the Claim that the Shipping Method is used on.
+    type: string
+    example: null
+  claim_order:
+    description: A claim order object. Available if the relation `claim_order` is expanded.
+    type: object
+  tax_lines:
+    type: array
+    description: Available if the relation `tax_lines` is expanded.
+    items:
+      $ref: ./tax_line.yaml
+  price:
+    description: >-
+      The amount to charge for the Shipping Method. The currency of the price is
+      defined by the Region that the Order that the Shipping Method belongs to
+      is a part of.
+    type: integer
+    example: 200
+  data:
+    description: >-
+      Additional data that the Fulfillment Provider needs to fulfill the
+      shipment. This is used in combination with the Shipping Options data, and
+      may contain information such as a drop point id.
+    type: object
+    example: {}

docs/api/admin/components/schemas/shipping_option.yaml

@@ -0,0 +1,103 @@
+title: Shipping Option
+description: >-
+  Shipping Options represent a way in which an Order or Return can be shipped.
+  Shipping Options have an associated Fulfillment Provider that will be used
+  when the fulfillment of an Order is initiated. Shipping Options themselves
+  cannot be added to Carts, but serve as a template for Shipping Methods. This
+  distinction makes it possible to customize individual Shipping Methods with
+  additional information.
+x-resourceId: shipping_option
+required:
+  - name
+  - region_id
+  - profile_id
+  - provider_id
+  - price_type
+properties:
+  id:
+    type: string
+    description: The shipping option's ID
+    example: so_01G1G5V27GYX4QXNARRQCW1N8T
+  name:
+    description: >-
+      The name given to the Shipping Option - this may be displayed to the
+      Customer.
+    type: string
+    example: PostFake Standard
+  region_id:
+    type: string
+    description: The region's ID
+    example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
+  region:
+    description: A region object. Available if the relation `region` is expanded.
+    type: object
+  profile_id:
+    description: >-
+      The ID of the Shipping Profile that the shipping option belongs to.
+      Shipping Profiles have a set of defined Shipping Options that can be used
+      to Fulfill a given set of Products.
+    type: string
+    example: sp_01G1G5V239ENSZ5MV4JAR737BM
+  profile:
+    description: Available if the relation `profile` is expanded.
+    $ref: ./shipping_profile.yaml
+  provider_id:
+    description: >-
+      The id of the Fulfillment Provider, that will be used to process
+      Fulfillments from the Shipping Option.
+    type: string
+    example: manual
+  provider:
+    description: Available if the relation `provider` is expanded.
+    $ref: ./fulfillment_provider.yaml
+  price_type:
+    description: >-
+      The type of pricing calculation that is used when creatin Shipping Methods
+      from the Shipping Option. Can be `flat_rate` for fixed prices or
+      `calculated` if the Fulfillment Provider can provide price calulations.
+    type: string
+    enum:
+      - flat_rate
+      - calculated
+    example: flat_rate
+  amount:
+    description: >-
+      The amount to charge for shipping when the Shipping Option price type is
+      `flat_rate`.
+    type: integer
+    example: 200
+  is_return:
+    description: Flag to indicate if the Shipping Option can be used for Return shipments.
+    type: boolean
+    default: false
+  requirements:
+    description: >-
+      The requirements that must be satisfied for the Shipping Option to be
+      available for a Cart. Available if the relation `requirements` is
+      expanded.
+    type: array
+    items:
+      $ref: ./shipping_option_requirement.yaml
+  data:
+    description: >-
+      The data needed for the Fulfillment Provider to identify the Shipping
+      Option.
+    type: object
+    example: {}
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/shipping_option_requirement.yaml

@@ -0,0 +1,43 @@
+title: Shipping Option Requirement
+description: >-
+  A requirement that a Cart must satisfy for the Shipping Option to be available
+  to the Cart.
+x-resourceId: shipping_option_requirement
+required:
+  - shipping_option_id
+  - type
+  - amount
+properties:
+  id:
+    type: string
+    description: The shipping option requirement's ID
+    example: sor_01G1G5V29AB4CTNDRFSRWSRKWD
+  shipping_option_id:
+    description: >-
+      The id of the Shipping Option that the hipping option requirement belongs
+      to
+    type: string
+    example: so_01G1G5V27GYX4QXNARRQCW1N8T
+  shipping_option:
+    description: Available if the relation `shipping_option` is expanded.
+    $ref: ./shipping_option.yaml
+  type:
+    description: >-
+      The type of the requirement, this defines how the value will be compared
+      to the Cart's total. `min_subtotal` requirements define the minimum
+      subtotal that is needed for the Shipping Option to be available, while the
+      `max_subtotal` defines the maximum subtotal that the Cart can have for the
+      Shipping Option to be available.
+    type: string
+    enum:
+      - min_subtotal
+      - max_subtotal
+    example: min_subtotal
+  amount:
+    description: The amount to compare the Cart subtotal to.
+    type: integer
+    example: 100
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time

docs/api/admin/components/schemas/shipping_profile.yaml

@@ -0,0 +1,62 @@
+title: Shipping Profile
+description: >-
+  Shipping Profiles have a set of defined Shipping Options that can be used to
+  fulfill a given set of Products.
+x-resourceId: shipping_profile
+required:
+  - name
+  - type
+properties:
+  id:
+    type: string
+    description: The shipping profile's ID
+    example: sp_01G1G5V239ENSZ5MV4JAR737BM
+  name:
+    description: >-
+      The name given to the Shipping profile - this may be displayed to the
+      Customer.
+    type: string
+    example: Default Shipping Profile
+  type:
+    description: >-
+      The type of the Shipping Profile, may be `default`, `gift_card` or
+      `custom`.
+    type: string
+    enum:
+      - default
+      - gift_card
+      - custom
+    example: default
+  products:
+    description: >-
+      The Products that the Shipping Profile defines Shipping Options for.
+      Available if the relation `products` is expanded.
+    type: array
+    items:
+      type: object
+      description: A product object.
+  shipping_options:
+    description: >-
+      The Shipping Options that can be used to fulfill the Products in the
+      Shipping Profile. Available if the relation `shipping_options` is
+      expanded.
+    type: array
+    items:
+      $ref: ./shipping_option.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/shipping_tax_rate.yaml

@@ -0,0 +1,36 @@
+title: Shipping Tax Rate
+description: >-
+  Associates a tax rate with a shipping option to indicate that the shipping
+  option is taxed in a certain way
+x-resourceId: shipping_tax_rate
+required:
+  - shipping_option_id
+  - rate_id
+properties:
+  shipping_option_id:
+    description: The ID of the Shipping Option
+    type: string
+    example: so_01G1G5V27GYX4QXNARRQCW1N8T
+  shipping_option:
+    description: Available if the relation `shipping_option` is expanded.
+    $ref: ./shipping_option.yaml
+  rate_id:
+    description: The ID of the Tax Rate
+    type: string
+    example: txr_01G8XDBAWKBHHJRKH0AV02KXBR
+  tax_rate:
+    description: Available if the relation `tax_rate` is expanded.
+    $ref: ./tax_rate.yaml
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/staged_job.yaml

@@ -0,0 +1,18 @@
+title: Staged Job
+description: A staged job resource
+x-resourceId: staged_job
+required:
+  - event_name
+properties:
+  id:
+    type: string
+    description: The staged job's ID
+    example: job_01F0YET7BZTARY9MKN1SJ7AAXF
+  event_name:
+    description: The name of the event
+    type: string
+    example: order.placed
+  data:
+    description: Data necessary for the job
+    type: object
+    example: {}

docs/api/admin/components/schemas/store.yaml

@@ -0,0 +1,59 @@
+title: Store
+description: Holds settings for the Store, such as name, currencies, etc.
+x-resourceId: store
+properties:
+  id:
+    type: string
+    description: The store's ID
+    example: store_01G1G5V21KADXNGH29BJMAJ4B4
+  name:
+    description: The name of the Store - this may be displayed to the Customer.
+    type: string
+    example: Medusa Store
+  default_currency_code:
+    description: The 3 character currency code that is the default of the store.
+    type: string
+    example: usd
+    externalDocs:
+      url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+      description: See a list of codes.
+  default_currency:
+    description: Available if the relation `default_currency` is expanded.
+    $ref: ./currency.yaml
+  currencies:
+    description: >-
+      The currencies that are enabled for the Store. Available if the relation
+      `currencies` is expanded.
+    type: array
+    items:
+      $ref: ./currency.yaml
+  swap_link_template:
+    description: >-
+      A template to generate Swap links from. Use {{cart_id}} to include the
+      Swap's `cart_id` in the link.
+    type: string
+    example: null
+  payment_link_template:
+    description: >-
+      A template to generate Payment links from. Use {{cart_id}} to include the
+      payment's `cart_id` in the link.
+    type: string
+    example: null
+  invite_link_template:
+    description: A template to generate Invite links from
+    type: string
+    example: null
+  default_sales_channel_id:
+    type: string
+    description: The sales channel ID the cart is associated with.
+    example: null
+  default_sales_channel:
+    description: >-
+      A sales channel object. Available if the relation `default_sales_channel`
+      is expanded.
+    type: object
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/swap.yaml

@@ -0,0 +1,149 @@
+title: Swap
+description: >-
+  Swaps can be created when a Customer wishes to exchange Products that they
+  have purchased to different Products. Swaps consist of a Return of previously
+  purchased Products and a Fulfillment of new Products, the amount paid for the
+  Products being returned will be used towards payment for the new Products. In
+  the case where the amount paid for the the Products being returned exceed the
+  amount to be paid for the new Products, a Refund will be issued for the
+  difference.
+x-resourceId: swap
+required:
+  - fulfillment_status
+  - payment_status
+  - order_id
+properties:
+  id:
+    type: string
+    description: The swap's ID
+    example: swap_01F0YET86Y9G92D3YDR9Y6V676
+  fulfillment_status:
+    description: The status of the Fulfillment of the Swap.
+    type: string
+    enum:
+      - not_fulfilled
+      - fulfilled
+      - shipped
+      - canceled
+      - requires_action
+    example: not_fulfilled
+  payment_status:
+    description: >-
+      The status of the Payment of the Swap. The payment may either refer to the
+      refund of an amount or the authorization of a new amount.
+    type: string
+    enum:
+      - not_paid
+      - awaiting
+      - captured
+      - confirmed
+      - canceled
+      - difference_refunded
+      - partially_refunded
+      - refunded
+      - requires_action
+    example: not_paid
+  order_id:
+    description: The ID of the Order where the Line Items to be returned where purchased.
+    type: string
+    example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
+  order:
+    description: An order object. Available if the relation `order` is expanded.
+    type: object
+  additional_items:
+    description: >-
+      The new Line Items to ship to the Customer. Available if the relation
+      `additional_items` is expanded.
+    type: array
+    items:
+      $ref: ./line_item.yaml
+  return_order:
+    description: >-
+      A return order object. The Return that is issued for the return part of
+      the Swap. Available if the relation `return_order` is expanded.
+    type: object
+  fulfillments:
+    description: >-
+      The Fulfillments used to send the new Line Items. Available if the
+      relation `fulfillments` is expanded.
+    type: array
+    items:
+      $ref: ./fulfillment.yaml
+  payment:
+    description: >-
+      The Payment authorized when the Swap requires an additional amount to be
+      charged from the Customer. Available if the relation `payment` is
+      expanded.
+    $ref: ./payment.yaml
+  difference_due:
+    description: >-
+      The difference that is paid or refunded as a result of the Swap. May be
+      negative when the amount paid for the returned items exceed the total of
+      the new Products.
+    type: integer
+    example: 0
+  shipping_address_id:
+    description: >-
+      The Address to send the new Line Items to - in most cases this will be the
+      same as the shipping address on the Order.
+    type: string
+    example: addr_01G8ZH853YPY9B94857DY91YGW
+  shipping_address:
+    description: Available if the relation `shipping_address` is expanded.
+    $ref: ./address.yaml
+  shipping_methods:
+    description: >-
+      The Shipping Methods used to fulfill the addtional items purchased.
+      Available if the relation `shipping_methods` is expanded.
+    type: array
+    items:
+      $ref: ./shipping_method.yaml
+  cart_id:
+    description: The id of the Cart that the Customer will use to confirm the Swap.
+    type: string
+    example: cart_01G8ZH853Y6TFXWPG5EYE81X63
+  cart:
+    description: A cart object. Available if the relation `cart` is expanded.
+    type: object
+  allow_backorder:
+    description: If true, swaps can be completed with items out of stock
+    type: boolean
+    default: false
+  idempotency_key:
+    type: string
+    description: >-
+      Randomly generated key used to continue the completion of the swap in case
+      of failure.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key
+      description: Learn more how to use the idempotency key.
+  confirmed_at:
+    description: The date with timezone at which the Swap was confirmed by the Customer.
+    type: string
+    format: date-time
+  canceled_at:
+    description: The date with timezone at which the Swap was canceled.
+    type: string
+    format: date-time
+  no_notification:
+    description: If set to true, no notification will be sent related to this swap
+    type: boolean
+    example: false
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/tax_line.yaml

@@ -0,0 +1,36 @@
+title: Tax Line
+description: Line item that specifies an amount of tax to add to a line item.
+x-resourceId: tax_line
+required:
+  - rate
+  - name
+properties:
+  id:
+    type: string
+    description: The tax line's ID
+    example: tl_01G1G5V2DRX1SK6NQQ8VVX4HQ8
+  code:
+    description: A code to identify the tax type by
+    type: string
+    example: tax01
+  name:
+    description: A human friendly name for the tax
+    type: string
+    example: Tax Example
+  rate:
+    description: The numeric rate to charge tax by
+    type: number
+    example: 10
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/tax_provider.yaml

@@ -0,0 +1,15 @@
+title: Tax Provider
+description: The tax service used to calculate taxes
+x-resourceId: tax_provider
+properties:
+  id:
+    description: The id of the tax provider as given by the plugin.
+    type: string
+    example: manual
+  is_installed:
+    description: >-
+      Whether the plugin is installed in the current version. Plugins that are
+      no longer installed are not deleted by will have this field set to
+      `false`.
+    type: boolean
+    default: true

docs/api/admin/components/schemas/tax_rate.yaml

@@ -0,0 +1,81 @@
+title: Tax Rate
+description: >-
+  A Tax Rate can be used to associate a certain rate to charge on products
+  within a given Region
+x-resourceId: line_item
+required:
+  - name
+  - region_id
+properties:
+  id:
+    type: string
+    description: The tax rate's ID
+    example: txr_01G8XDBAWKBHHJRKH0AV02KXBR
+  rate:
+    description: The numeric rate to charge
+    type: number
+    example: 10
+  code:
+    description: A code to identify the tax type by
+    type: string
+    example: tax01
+  name:
+    description: A human friendly name for the tax
+    type: string
+    example: Tax Example
+  region_id:
+    type: string
+    description: The id of the Region that the rate belongs to
+    example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
+  region:
+    description: A region object. Available if the relation `region` is expanded.
+    type: object
+  products:
+    type: array
+    description: >-
+      The products that belong to this tax rate. Available if the relation
+      `products` is expanded.
+    items:
+      type: object
+      description: A product object.
+  product_types:
+    type: array
+    description: >-
+      The product types that belong to this tax rate. Available if the relation
+      `product_types` is expanded.
+    items:
+      type: object
+      description: A product type object.
+  shipping_options:
+    type: array
+    description: >-
+      The shipping options that belong to this tax rate. Available if the
+      relation `shipping_options` is expanded.
+    items:
+      type: object
+      description: A shipping option object.
+  product_count:
+    description: The count of products
+    type: integer
+    example: null
+  product_type_count:
+    description: The count of product types
+    type: integer
+    example: null
+  shipping_option_count:
+    description: The count of shipping options
+    type: integer
+    example: null
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/tracking_link.yaml

@@ -0,0 +1,55 @@
+title: Tracking Link
+description: >-
+  Tracking Link holds information about tracking numbers for a Fulfillment.
+  Tracking Links can optionally contain a URL that can be visited to see the
+  status of the shipment.
+x-resourceId: tracking_link
+required:
+  - tracking_number
+  - fulfillment_id
+properties:
+  id:
+    type: string
+    description: The tracking link's ID
+    example: tlink_01G8ZH853Y6TFXWPG5EYE81X63
+  url:
+    description: The URL at which the status of the shipment can be tracked.
+    type: string
+    format: uri
+  tracking_number:
+    description: The tracking number given by the shipping carrier.
+    type: string
+    format: RH370168054CN
+  fulfillment_id:
+    type: string
+    description: The id of the Fulfillment that the Tracking Link references.
+    example: ful_01G8ZRTMQCA76TXNAT81KPJZRF
+  fulfillment:
+    description: Available if the relation `fulfillment` is expanded.
+    $ref: ./fulfillment.yaml
+  idempotency_key:
+    type: string
+    description: >-
+      Randomly generated key used to continue the completion of a process in
+      case of failure.
+    externalDocs:
+      url: >-
+        https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key
+      description: Learn more how to use the idempotency key.
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/components/schemas/user.yaml

@@ -0,0 +1,43 @@
+title: User
+description: Represents a User who can manage store settings.
+x-resourceId: user
+required:
+  - email
+properties:
+  id:
+    type: string
+    description: The user's ID
+    example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V
+  email:
+    description: The email of the User
+    type: string
+    format: email
+  first_name:
+    description: The first name of the User
+    type: string
+    example: Levi
+  last_name:
+    description: The last name of the User
+    type: string
+    example: Bogan
+  api_token:
+    description: An API token associated with the user.
+    type: string
+    example: null
+  created_at:
+    type: string
+    description: The date with timezone at which the resource was created.
+    format: date-time
+  updated_at:
+    type: string
+    description: The date with timezone at which the resource was updated.
+    format: date-time
+  deleted_at:
+    type: string
+    description: The date with timezone at which the resource was deleted.
+    format: date-time
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/admin/openapi.yaml

@@ -0,0 +1,353 @@
+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:
+  /auth:
+    $ref: paths/auth.yaml
+  /batch-jobs/{id}/cancel:
+    $ref: paths/batch-jobs_{id}_cancel.yaml
+  /batch-jobs/{id}/confirm:
+    $ref: paths/batch-jobs_{id}_confirm.yaml
+  /batch-jobs:
+    $ref: paths/batch-jobs.yaml
+  /batch-jobs/{id}:
+    $ref: paths/batch-jobs_{id}.yaml
+  /collections/{id}/products/batch:
+    $ref: paths/collections_{id}_products_batch.yaml
+  /collections:
+    $ref: paths/collections.yaml
+  /collections/{id}:
+    $ref: paths/collections_{id}.yaml
+  /customer-groups/{id}/customers/batch:
+    $ref: paths/customer-groups_{id}_customers_batch.yaml
+  /customer-groups:
+    $ref: paths/customer-groups.yaml
+  /customer-groups/{id}:
+    $ref: paths/customer-groups_{id}.yaml
+  /customer-groups/{id}/customers:
+    $ref: paths/customer-groups_{id}_customers.yaml
+  /customers:
+    $ref: paths/customers.yaml
+  /customers/{id}:
+    $ref: paths/customers_{id}.yaml
+  /discounts/{id}/regions/{region_id}:
+    $ref: paths/discounts_{id}_regions_{region_id}.yaml
+  /discounts/{discount_id}/conditions:
+    $ref: paths/discounts_{discount_id}_conditions.yaml
+  /discounts:
+    $ref: paths/discounts.yaml
+  /discounts/{id}/dynamic-codes:
+    $ref: paths/discounts_{id}_dynamic-codes.yaml
+  /discounts/{discount_id}/conditions/{condition_id}:
+    $ref: paths/discounts_{discount_id}_conditions_{condition_id}.yaml
+  /discounts/{id}:
+    $ref: paths/discounts_{id}.yaml
+  /discounts/{id}/dynamic-codes/{code}:
+    $ref: paths/discounts_{id}_dynamic-codes_{code}.yaml
+  /discounts/code/{code}:
+    $ref: paths/discounts_code_{code}.yaml
+  /apps/authorizations:
+    $ref: paths/apps_authorizations.yaml
+  /apps:
+    $ref: paths/apps.yaml
+  /draft-orders:
+    $ref: paths/draft-orders.yaml
+  /draft-orders/{id}/line-items:
+    $ref: paths/draft-orders_{id}_line-items.yaml
+  /draft-orders/{id}:
+    $ref: paths/draft-orders_{id}.yaml
+  /draft-orders/{id}/line-items/{line_id}:
+    $ref: paths/draft-orders_{id}_line-items_{line_id}.yaml
+  /draft-orders/{id}/pay:
+    $ref: paths/draft-orders_{id}_pay.yaml
+  /admin/draft-orders/{id}:
+    $ref: paths/admin_draft-orders_{id}.yaml
+  /gift-cards:
+    $ref: paths/gift-cards.yaml
+  /gift-cards/{id}:
+    $ref: paths/gift-cards_{id}.yaml
+  /invites/accept:
+    $ref: paths/invites_accept.yaml
+  /invites:
+    $ref: paths/invites.yaml
+  /invites/{invite_id}:
+    $ref: paths/invites_{invite_id}.yaml
+  /invites/{invite_id}/resend:
+    $ref: paths/invites_{invite_id}_resend.yaml
+  /notes:
+    $ref: paths/notes.yaml
+  /notes/{id}:
+    $ref: paths/notes_{id}.yaml
+  /notifications:
+    $ref: paths/notifications.yaml
+  /notifications/{id}/resend:
+    $ref: paths/notifications_{id}_resend.yaml
+  /orders/{id}/shipping-methods:
+    $ref: paths/orders_{id}_shipping-methods.yaml
+  /orders/{id}/archive:
+    $ref: paths/orders_{id}_archive.yaml
+  /orders/{id}/claims/{claim_id}/cancel:
+    $ref: paths/orders_{id}_claims_{claim_id}_cancel.yaml
+  /orders/{id}/claims/{claim_id}/fulfillments/{fulfillment_id}/cancel:
+    $ref: >-
+      paths/orders_{id}_claims_{claim_id}_fulfillments_{fulfillment_id}_cancel.yaml
+  /orders/{id}/swaps/{swap_id}/fulfillments/{fulfillment_id}/cancel:
+    $ref: >-
+      paths/orders_{id}_swaps_{swap_id}_fulfillments_{fulfillment_id}_cancel.yaml
+  /orders/{id}/fulfillments/{fulfillment_id}/cancel:
+    $ref: paths/orders_{id}_fulfillments_{fulfillment_id}_cancel.yaml
+  /orders/{id}/cancel:
+    $ref: paths/orders_{id}_cancel.yaml
+  /orders/{id}/swaps/{swap_id}/cancel:
+    $ref: paths/orders_{id}_swaps_{swap_id}_cancel.yaml
+  /orders/{id}/capture:
+    $ref: paths/orders_{id}_capture.yaml
+  /orders/{id}/complete:
+    $ref: paths/orders_{id}_complete.yaml
+  /orders/{id}/claims/{claim_id}/shipments:
+    $ref: paths/orders_{id}_claims_{claim_id}_shipments.yaml
+  /order/{id}/claims:
+    $ref: paths/order_{id}_claims.yaml
+  /orders/{id}/fulfillment:
+    $ref: paths/orders_{id}_fulfillment.yaml
+  /orders/{id}/shipment:
+    $ref: paths/orders_{id}_shipment.yaml
+  /orders/{id}/swaps/{swap_id}/shipments:
+    $ref: paths/orders_{id}_swaps_{swap_id}_shipments.yaml
+  /order/{id}/swaps:
+    $ref: paths/order_{id}_swaps.yaml
+  /orders/{id}/claims/{claim_id}/fulfillments:
+    $ref: paths/orders_{id}_claims_{claim_id}_fulfillments.yaml
+  /orders/{id}/swaps/{swap_id}/fulfillments:
+    $ref: paths/orders_{id}_swaps_{swap_id}_fulfillments.yaml
+  /orders/{id}:
+    $ref: paths/orders_{id}.yaml
+  /orders:
+    $ref: paths/orders.yaml
+  /orders/{id}/swaps/{swap_id}/process-payment:
+    $ref: paths/orders_{id}_swaps_{swap_id}_process-payment.yaml
+  /orders/{id}/refund:
+    $ref: paths/orders_{id}_refund.yaml
+  /orders/{id}/return:
+    $ref: paths/orders_{id}_return.yaml
+  /order/{id}/claims/{claim_id}:
+    $ref: paths/order_{id}_claims_{claim_id}.yaml
+  /price-lists/{id}/prices/batch:
+    $ref: paths/price-lists_{id}_prices_batch.yaml
+  /price-lists:
+    $ref: paths/price-lists.yaml
+  /price-lists/{id}:
+    $ref: paths/price-lists_{id}.yaml
+  /price-lists/{id}/products/{product_id}/prices:
+    $ref: paths/price-lists_{id}_products_{product_id}_prices.yaml
+  /price-lists/{id}/variants/{variant_id}/prices:
+    $ref: paths/price-lists_{id}_variants_{variant_id}_prices.yaml
+  /price-lists/:id/products:
+    $ref: paths/price-lists_:id_products.yaml
+  /product-tags:
+    $ref: paths/product-tags.yaml
+  /product-types:
+    $ref: paths/product-types.yaml
+  /products/{id}/options:
+    $ref: paths/products_{id}_options.yaml
+  /products:
+    $ref: paths/products.yaml
+  /products/{id}/variants:
+    $ref: paths/products_{id}_variants.yaml
+  /products/{id}/options/{option_id}:
+    $ref: paths/products_{id}_options_{option_id}.yaml
+  /products/{id}:
+    $ref: paths/products_{id}.yaml
+  /products/{id}/variants/{variant_id}:
+    $ref: paths/products_{id}_variants_{variant_id}.yaml
+  /products/tag-usage:
+    $ref: paths/products_tag-usage.yaml
+  /products/types:
+    $ref: paths/products_types.yaml
+  /products/{id}/metadata:
+    $ref: paths/products_{id}_metadata.yaml
+  /regions/{id}/countries:
+    $ref: paths/regions_{id}_countries.yaml
+  /regions/{id}/fulfillment-providers:
+    $ref: paths/regions_{id}_fulfillment-providers.yaml
+  /regions/{id}/payment-providers:
+    $ref: paths/regions_{id}_payment-providers.yaml
+  /regions:
+    $ref: paths/regions.yaml
+  /regions/{id}:
+    $ref: paths/regions_{id}.yaml
+  /regions/{id}/fulfillment-options:
+    $ref: paths/regions_{id}_fulfillment-options.yaml
+  /regions/{id}/countries/{country_code}:
+    $ref: paths/regions_{id}_countries_{country_code}.yaml
+  /regions/{id}/fulfillment-providers/{provider_id}:
+    $ref: paths/regions_{id}_fulfillment-providers_{provider_id}.yaml
+  /regions/{id}/payment-providers/{provider_id}:
+    $ref: paths/regions_{id}_payment-providers_{provider_id}.yaml
+  /return-reasons:
+    $ref: paths/return-reasons.yaml
+  /return-reasons/{id}:
+    $ref: paths/return-reasons_{id}.yaml
+  /returns/{id}/cancel:
+    $ref: paths/returns_{id}_cancel.yaml
+  /returns:
+    $ref: paths/returns.yaml
+  /returns/{id}/receive:
+    $ref: paths/returns_{id}_receive.yaml
+  /sales-channels/{id}/products/batch:
+    $ref: paths/sales-channels_{id}_products_batch.yaml
+  /sales-channels:
+    $ref: paths/sales-channels.yaml
+  /sales-channels/{id}:
+    $ref: paths/sales-channels_{id}.yaml
+  /shipping-options:
+    $ref: paths/shipping-options.yaml
+  /shipping-options/{id}:
+    $ref: paths/shipping-options_{id}.yaml
+  /shipping-profiles:
+    $ref: paths/shipping-profiles.yaml
+  /shipping-profiles/{id}:
+    $ref: paths/shipping-profiles_{id}.yaml
+  /store/currencies/{code}:
+    $ref: paths/store_currencies_{code}.yaml
+  /store:
+    $ref: paths/store.yaml
+  /store/payment-providers:
+    $ref: paths/store_payment-providers.yaml
+  /store/tax-providers:
+    $ref: paths/store_tax-providers.yaml
+  /swaps/{id}:
+    $ref: paths/swaps_{id}.yaml
+  /swaps:
+    $ref: paths/swaps.yaml
+  /tax-rates/:id/product-types/batch:
+    $ref: paths/tax-rates_:id_product-types_batch.yaml
+  /tax-rates/:id/products/batch:
+    $ref: paths/tax-rates_:id_products_batch.yaml
+  /tax-rates/:id/shipping-options/batch:
+    $ref: paths/tax-rates_:id_shipping-options_batch.yaml
+  /tax-rates:
+    $ref: paths/tax-rates.yaml
+  /tax-rates/{id}:
+    $ref: paths/tax-rates_{id}.yaml
+  /tax-rates/:id:
+    $ref: paths/tax-rates_:id.yaml
+  /uploads:
+    $ref: paths/uploads.yaml
+  /users:
+    $ref: paths/users.yaml
+  /users/{id}:
+    $ref: paths/users_{id}.yaml
+  /users/password-token:
+    $ref: paths/users_password-token.yaml
+  /users/reset-password:
+    $ref: paths/users_reset-password.yaml
+  /variants:
+    $ref: paths/variants.yaml

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

@@ -0,0 +1,67 @@
+post:
+  operationId: PostDraftOrdersDraftOrder
+  summary: Update a Draft Order"
+  description: Updates a Draft Order.
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the Draft Order.
+      schema:
+        type: string
+  requestBody:
+    content:
+      application/json:
+        schema:
+          properties:
+            region_id:
+              type: string
+              description: The ID of the Region to create the Draft Order in.
+            country_code:
+              type: string
+              description: The 2 character ISO code for the Country.
+              externalDocs:
+                url: >-
+                  https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
+                description: See a list of codes.
+            email:
+              type: string
+              description: An email to be used on the Draft Order.
+              format: email
+            billing_address:
+              description: The Address to be used for billing purposes.
+              $ref: ../components/schemas/address.yaml
+            shipping_address:
+              description: The Address to be used for shipping.
+              $ref: ../components/schemas/address.yaml
+            discounts:
+              description: An array of Discount codes to add to the Draft Order.
+              type: array
+              items:
+                type: object
+                required:
+                  - code
+                properties:
+                  code:
+                    description: The code that a Discount is identifed by.
+                    type: string
+            no_notification_order:
+              description: >-
+                An optional flag passed to the resulting order to determine use
+                of notifications.
+              type: boolean
+            customer_id:
+              description: The ID of the Customer to associate the Draft Order with.
+              type: string
+  tags:
+    - Draft Order
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              draft_order:
+                $ref: ../components/schemas/draft-order.yaml

docs/api/admin/paths/apps.yaml

@@ -0,0 +1,18 @@
+get:
+  operationId: GetApps
+  summary: List applications
+  description: Retrieve a list of applications.
+  x-authenticated: true
+  tags:
+    - App
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              apps:
+                type: array
+                items:
+                  $ref: ../components/schemas/OAuth.yaml

docs/api/admin/paths/apps_authorizations.yaml

@@ -0,0 +1,34 @@
+post:
+  operationId: PostApps
+  summary: Generates a token for an application.
+  description: Generates a token for an application.
+  x-authenticated: true
+  requestBody:
+    content:
+      application/json:
+        schema:
+          required:
+            - application_name
+            - state
+            - code
+          properties:
+            application_name:
+              type: string
+              description: Name of the application for the token to be generated for.
+            state:
+              type: string
+              description: State of the application.
+            code:
+              type: string
+              description: The code for the generated token.
+  tags:
+    - App
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              apps:
+                $ref: ../components/schemas/OAuth.yaml

docs/api/admin/paths/auth.yaml

@@ -0,0 +1,62 @@
+post:
+  operationId: PostAuth
+  summary: Authenticate a User
+  x-authenticated: false
+  description: Logs a User in and authorizes them to manage Store settings.
+  parameters: []
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+          required:
+            - email
+            - password
+          properties:
+            email:
+              type: string
+              description: The User's email.
+            password:
+              type: string
+              description: The User's password.
+  tags:
+    - Auth
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              user:
+                $ref: ../components/schemas/user.yaml
+    '401':
+      description: The user doesn't exist or the credentials are incorrect.
+delete:
+  operationId: DeleteAuth
+  summary: Delete Session
+  x-authenticated: true
+  description: Deletes the current session for the logged in user.
+  tags:
+    - Auth
+  responses:
+    '200':
+      description: OK
+get:
+  operationId: GetAuth
+  summary: Get Session
+  x-authenticated: true
+  description: Gets the currently logged in User.
+  tags:
+    - Auth
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              user:
+                $ref: ../components/schemas/user.yaml
+    '400':
+      description: An error occurred.

docs/api/admin/paths/batch-jobs.yaml

@@ -0,0 +1,318 @@
+post:
+  operationId: PostBatchJobs
+  summary: Create a Batch Job
+  description: Creates a Batch Job.
+  x-authenticated: true
+  requestBody:
+    content:
+      application/json:
+        schema:
+          required:
+            - type
+            - context
+          properties:
+            type:
+              type: string
+              description: The type of batch job to start.
+              example: product-export
+            context:
+              type: object
+              description: >-
+                Additional infomration regarding the batch to be used for
+                processing.
+              example:
+                shape:
+                  prices:
+                    - region: null
+                      currency_code: eur
+                  dynamicImageColumnCount: 4
+                  dynamicOptionColumnCount: 2
+                list_config:
+                  skip: 0
+                  take: 50
+                  order:
+                    created_at: DESC
+                  relations:
+                    - variants
+                    - variant.prices
+                    - images
+            dry_run:
+              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
+  tags:
+    - Batch Job
+  responses:
+    '201':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              batch_job:
+                $ref: ../components/schemas/batch_job.yaml
+get:
+  operationId: GetBatchJobs
+  summary: List Batch Jobs
+  description: Retrieve a list of Batch Jobs.
+  x-authenticated: true
+  parameters:
+    - in: query
+      name: limit
+      description: The number of batch jobs to return.
+      schema:
+        type: integer
+        default: 10
+    - in: query
+      name: offset
+      description: The number of batch jobs to skip before results.
+      schema:
+        type: integer
+        default: 0
+    - in: query
+      name: id
+      style: form
+      explode: false
+      description: Filter by the batch ID
+      schema:
+        oneOf:
+          - type: string
+            description: batch job ID
+          - type: array
+            description: multiple batch job IDs
+            items:
+              type: string
+    - in: query
+      name: type
+      style: form
+      explode: false
+      description: Filter by the batch type
+      schema:
+        type: array
+        items:
+          type: string
+    - in: query
+      name: confirmed_at
+      style: form
+      explode: false
+      description: >-
+        Date comparison for when resulting collections was confirmed, i.e. less
+        than, greater than etc.
+      schema:
+        type: object
+        properties:
+          lt:
+            type: string
+            description: filter by dates less than this date
+            format: date
+          gt:
+            type: string
+            description: filter by dates greater than this date
+            format: date
+          lte:
+            type: string
+            description: filter by dates less than or equal to this date
+            format: date
+          gte:
+            type: string
+            description: filter by dates greater than or equal to this date
+            format: date
+    - in: query
+      name: pre_processed_at
+      style: form
+      explode: false
+      description: >-
+        Date comparison for when resulting collections was pre processed, i.e.
+        less than, greater than etc.
+      schema:
+        type: object
+        properties:
+          lt:
+            type: string
+            description: filter by dates less than this date
+            format: date
+          gt:
+            type: string
+            description: filter by dates greater than this date
+            format: date
+          lte:
+            type: string
+            description: filter by dates less than or equal to this date
+            format: date
+          gte:
+            type: string
+            description: filter by dates greater than or equal to this date
+            format: date
+    - in: query
+      name: completed_at
+      style: form
+      explode: false
+      description: >-
+        Date comparison for when resulting collections was completed, i.e. less
+        than, greater than etc.
+      schema:
+        type: object
+        properties:
+          lt:
+            type: string
+            description: filter by dates less than this date
+            format: date
+          gt:
+            type: string
+            description: filter by dates greater than this date
+            format: date
+          lte:
+            type: string
+            description: filter by dates less than or equal to this date
+            format: date
+          gte:
+            type: string
+            description: filter by dates greater than or equal to this date
+            format: date
+    - in: query
+      name: failed_at
+      style: form
+      explode: false
+      description: >-
+        Date comparison for when resulting collections was failed, i.e. less
+        than, greater than etc.
+      schema:
+        type: object
+        properties:
+          lt:
+            type: string
+            description: filter by dates less than this date
+            format: date
+          gt:
+            type: string
+            description: filter by dates greater than this date
+            format: date
+          lte:
+            type: string
+            description: filter by dates less than or equal to this date
+            format: date
+          gte:
+            type: string
+            description: filter by dates greater than or equal to this date
+            format: date
+    - in: query
+      name: canceled_at
+      style: form
+      explode: false
+      description: >-
+        Date comparison for when resulting collections was canceled, i.e. less
+        than, greater than etc.
+      schema:
+        type: object
+        properties:
+          lt:
+            type: string
+            description: filter by dates less than this date
+            format: date
+          gt:
+            type: string
+            description: filter by dates greater than this date
+            format: date
+          lte:
+            type: string
+            description: filter by dates less than or equal to this date
+            format: date
+          gte:
+            type: string
+            description: filter by dates greater than or equal to this date
+            format: date
+    - in: query
+      name: order
+      description: Field used to order retrieved batch jobs
+      schema:
+        type: string
+    - in: query
+      name: expand
+      description: >-
+        (Comma separated) Which fields should be expanded in each order of the
+        result.
+      schema:
+        type: string
+    - in: query
+      name: fields
+      description: >-
+        (Comma separated) Which fields should be included in each order of the
+        result.
+      schema:
+        type: string
+    - in: query
+      name: created_at
+      style: form
+      explode: false
+      description: >-
+        Date comparison for when resulting collections was created, i.e. less
+        than, greater than etc.
+      schema:
+        type: object
+        properties:
+          lt:
+            type: string
+            description: filter by dates less than this date
+            format: date
+          gt:
+            type: string
+            description: filter by dates greater than this date
+            format: date
+          lte:
+            type: string
+            description: filter by dates less than or equal to this date
+            format: date
+          gte:
+            type: string
+            description: filter by dates greater than or equal to this date
+            format: date
+    - in: query
+      name: updated_at
+      style: form
+      explode: false
+      description: >-
+        Date comparison for when resulting collections was updated, i.e. less
+        than, greater than etc.
+      schema:
+        type: object
+        properties:
+          lt:
+            type: string
+            description: filter by dates less than this date
+            format: date
+          gt:
+            type: string
+            description: filter by dates greater than this date
+            format: date
+          lte:
+            type: string
+            description: filter by dates less than or equal to this date
+            format: date
+          gte:
+            type: string
+            description: filter by dates greater than or equal to this date
+            format: date
+  tags:
+    - Batch Job
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              batch_jobs:
+                type: array
+                items:
+                  $ref: ../components/schemas/batch_job.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/batch-jobs_{id}.yaml

@@ -0,0 +1,23 @@
+get:
+  operationId: GetBatchJobsBatchJob
+  summary: Retrieve a Batch Job
+  description: Retrieves a Batch Job.
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the Batch Job
+      schema:
+        type: string
+  tags:
+    - Batch Job
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              batch_job:
+                $ref: ../components/schemas/batch_job.yaml

docs/api/admin/paths/batch-jobs_{id}_cancel.yaml

@@ -0,0 +1,23 @@
+post:
+  operationId: PostBatchJobsBatchJobCancel
+  summary: Marks a batch job as canceled
+  description: Marks a batch job as canceled
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the batch job.
+      schema:
+        type: string
+  tags:
+    - Batch Job
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              batch_job:
+                $ref: ../components/schemas/batch_job.yaml

docs/api/admin/paths/batch-jobs_{id}_confirm.yaml

@@ -0,0 +1,23 @@
+post:
+  operationId: PostBatchJobsBatchJobConfirmProcessing
+  summary: Confirm a batch job
+  description: Confirms that a previously requested batch job should be executed.
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the batch job.
+      schema:
+        type: string
+  tags:
+    - Batch Job
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              batch_job:
+                $ref: ../components/schemas/batch_job.yaml

docs/api/admin/paths/collections.yaml

@@ -0,0 +1,157 @@
+post:
+  operationId: PostCollections
+  summary: Create a Product Collection
+  description: Creates a Product Collection.
+  x-authenticated: true
+  requestBody:
+    content:
+      application/json:
+        schema:
+          required:
+            - title
+          properties:
+            title:
+              type: string
+              description: The title to identify the Collection by.
+            handle:
+              type: string
+              description: >-
+                An optional handle to be used in slugs, if none is provided we
+                will kebab-case the title.
+            metadata:
+              description: >-
+                An optional set of key-value pairs to hold additional
+                information.
+              type: object
+  tags:
+    - Collection
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              collection:
+                $ref: ../components/schemas/product_collection.yaml
+get:
+  operationId: GetCollections
+  summary: List Product Collections
+  description: Retrieve a list of Product Collection.
+  x-authenticated: true
+  parameters:
+    - in: query
+      name: limit
+      description: The number of collections to return.
+      schema:
+        type: integer
+        default: 10
+    - in: query
+      name: offset
+      description: The number of collections to skip before the results.
+      schema:
+        type: integer
+        default: 0
+    - in: query
+      name: title
+      description: The title of collections to return.
+      schema:
+        type: string
+    - in: query
+      name: handle
+      description: The handle of collections to return.
+      schema:
+        type: string
+    - in: query
+      name: q
+      description: a search term to search titles and handles.
+      schema:
+        type: string
+    - in: query
+      name: created_at
+      description: Date comparison for when resulting collections were created.
+      schema:
+        type: object
+        properties:
+          lt:
+            type: string
+            description: filter by dates less than this date
+            format: date
+          gt:
+            type: string
+            description: filter by dates greater than this date
+            format: date
+          lte:
+            type: string
+            description: filter by dates less than or equal to this date
+            format: date
+          gte:
+            type: string
+            description: filter by dates greater than or equal to this date
+            format: date
+    - in: query
+      name: updated_at
+      description: Date comparison for when resulting collections were updated.
+      schema:
+        type: object
+        properties:
+          lt:
+            type: string
+            description: filter by dates less than this date
+            format: date
+          gt:
+            type: string
+            description: filter by dates greater than this date
+            format: date
+          lte:
+            type: string
+            description: filter by dates less than or equal to this date
+            format: date
+          gte:
+            type: string
+            description: filter by dates greater than or equal to this date
+            format: date
+    - in: query
+      name: deleted_at
+      description: Date comparison for when resulting collections were deleted.
+      schema:
+        type: object
+        properties:
+          lt:
+            type: string
+            description: filter by dates less than this date
+            format: date
+          gt:
+            type: string
+            description: filter by dates greater than this date
+            format: date
+          lte:
+            type: string
+            description: filter by dates less than or equal to this date
+            format: date
+          gte:
+            type: string
+            description: filter by dates greater than or equal to this date
+            format: date
+  tags:
+    - Collection
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              collections:
+                type: array
+                items:
+                  $ref: ../components/schemas/product_collection.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/collections_{id}.yaml

@@ -0,0 +1,96 @@
+delete:
+  operationId: DeleteCollectionsCollection
+  summary: Delete a Product Collection
+  description: Deletes a Product Collection.
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the Collection.
+      schema:
+        type: string
+  tags:
+    - Collection
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              id:
+                type: string
+                description: The ID of the deleted Collection
+              object:
+                type: string
+                description: The type of the object that was deleted.
+                default: product-collection
+              deleted:
+                type: boolean
+                description: Whether the collection was deleted successfully or not.
+                default: true
+get:
+  operationId: GetCollectionsCollection
+  summary: Retrieve a Product Collection
+  description: Retrieves a Product Collection.
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the Product Collection
+      schema:
+        type: string
+  tags:
+    - Collection
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              collection:
+                $ref: ../components/schemas/product_collection.yaml
+post:
+  operationId: PostCollectionsCollection
+  summary: Update a Product Collection
+  description: Updates a Product Collection.
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the Collection.
+      schema:
+        type: string
+  requestBody:
+    content:
+      application/json:
+        schema:
+          properties:
+            title:
+              type: string
+              description: The title to identify the Collection by.
+            handle:
+              type: string
+              description: >-
+                An optional handle to be used in slugs, if none is provided we
+                will kebab-case the title.
+            metadata:
+              description: >-
+                An optional set of key-value pairs to hold additional
+                information.
+              type: object
+  tags:
+    - Collection
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              collection:
+                $ref: ../components/schemas/product_collection.yaml

docs/api/admin/paths/collections_{id}_products_batch.yaml

@@ -0,0 +1,83 @@
+post:
+  operationId: PostProductsToCollection
+  summary: Updates products associated with a Product Collection
+  description: Updates products associated with a Product Collection
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the Collection.
+      schema:
+        type: string
+  requestBody:
+    content:
+      application/json:
+        schema:
+          required:
+            - product_ids
+          properties:
+            product_ids:
+              description: An array of Product IDs to add to the Product Collection.
+              type: array
+              items:
+                description: The ID of a Product to add to the Product Collection.
+                type: string
+  tags:
+    - Collection
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              collection:
+                $ref: ../components/schemas/product_collection.yaml
+delete:
+  operationId: DeleteProductsFromCollection
+  summary: Removes products associated with a Product Collection
+  description: Removes products associated with a Product Collection
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the Collection.
+      schema:
+        type: string
+  requestBody:
+    content:
+      application/json:
+        schema:
+          required:
+            - product_ids
+          properties:
+            product_ids:
+              description: An array of Product IDs to remove from the Product Collection.
+              type: array
+              items:
+                description: The ID of a Product to add to the Product Collection.
+                type: string
+  tags:
+    - Collection
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              id:
+                type: string
+                description: The ID of the collection
+              object:
+                type: string
+                description: The type of object the removal was executed on
+                default: product-collection
+              removed_products:
+                description: The IDs of the products removed from the collection
+                type: array
+                items:
+                  description: The ID of a Product to add to the Product Collection.
+                  type: string

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

@@ -0,0 +1,170 @@
+post:
+  operationId: PostCustomerGroups
+  summary: Create a CustomerGroup
+  description: Creates a CustomerGroup.
+  x-authenticated: true
+  parameters: []
+  tags:
+    - Customer Group
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              customer_group:
+                $ref: ../components/schemas/customer_group.yaml
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+          required:
+            - name
+          properties:
+            name:
+              type: string
+              description: Name of the customer group
+            metadata:
+              type: object
+              description: Metadata for the customer.
+get:
+  operationId: GetCustomerGroups
+  summary: Retrieve a list of customer groups
+  description: Retrieve a list of customer groups.
+  x-authenticated: true
+  parameters:
+    - in: query
+      name: q
+      description: Query used for searching customer group names.
+      schema:
+        type: string
+    - in: query
+      name: offset
+      description: How many groups to skip in the result.
+      schema:
+        type: integer
+        default: 0
+    - in: query
+      name: order
+      description: the field used to order the customer groups.
+      schema:
+        type: string
+    - in: query
+      name: id
+      style: form
+      explode: false
+      description: Filter by the customer group ID
+      schema:
+        oneOf:
+          - type: string
+            description: customer group ID
+          - type: array
+            description: multiple customer group IDs
+            items:
+              type: string
+          - type: object
+            properties:
+              lt:
+                type: string
+                description: filter by IDs less than this ID
+              gt:
+                type: string
+                description: filter by IDs greater than this ID
+              lte:
+                type: string
+                description: filter by IDs less than or equal to this ID
+              gte:
+                type: string
+                description: filter by IDs greater than or equal to this ID
+    - in: query
+      name: name
+      style: form
+      explode: false
+      description: Filter by the customer group name
+      schema:
+        type: array
+        description: multiple customer group names
+        items:
+          type: string
+          description: customer group name
+    - in: query
+      name: created_at
+      description: Date comparison for when resulting customer groups were created.
+      schema:
+        type: object
+        properties:
+          lt:
+            type: string
+            description: filter by dates less than this date
+            format: date
+          gt:
+            type: string
+            description: filter by dates greater than this date
+            format: date
+          lte:
+            type: string
+            description: filter by dates less than or equal to this date
+            format: date
+          gte:
+            type: string
+            description: filter by dates greater than or equal to this date
+            format: date
+    - in: query
+      name: updated_at
+      description: Date comparison for when resulting customer groups were updated.
+      schema:
+        type: object
+        properties:
+          lt:
+            type: string
+            description: filter by dates less than this date
+            format: date
+          gt:
+            type: string
+            description: filter by dates greater than this date
+            format: date
+          lte:
+            type: string
+            description: filter by dates less than or equal to this date
+            format: date
+          gte:
+            type: string
+            description: filter by dates greater than or equal to this date
+            format: date
+    - in: query
+      name: limit
+      description: Limit the number of customer groups returned.
+      schema:
+        type: integer
+        default: 10
+    - in: query
+      name: expand
+      description: >-
+        (Comma separated) Which fields should be expanded in each customer
+        groups of the result.
+      schema:
+        type: string
+  tags:
+    - Customer Group
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              customer_groups:
+                type: array
+                items:
+                  $ref: ../components/schemas/customer_group.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/customer-groups_{id}.yaml

@@ -0,0 +1,99 @@
+delete:
+  operationId: DeleteCustomerGroupsCustomerGroup
+  summary: Delete a CustomerGroup
+  description: Deletes a CustomerGroup.
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the Customer Group
+      schema:
+        type: string
+  tags:
+    - Customer Group
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              id:
+                type: string
+                description: The ID of the deleted customer group.
+              object:
+                type: string
+                description: The type of the object that was deleted.
+                default: customer_group
+              deleted:
+                type: boolean
+                description: Whether the customer group was deleted successfully or not.
+                default: true
+get:
+  operationId: GetCustomerGroupsGroup
+  summary: Retrieve a CustomerGroup
+  description: Retrieves a Customer Group.
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the Customer Group.
+      schema:
+        type: string
+    - in: query
+      name: expand
+      description: (Comma separated) Which fields should be expanded in the customer group.
+      schema:
+        type: string
+    - in: query
+      name: fields
+      description: (Comma separated) Which fields should be included in the customer group.
+      schema:
+        type: string
+  tags:
+    - Customer Group
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              customer_group:
+                $ref: ../components/schemas/customer_group.yaml
+post:
+  operationId: PostCustomerGroupsGroup
+  summary: Update a CustomerGroup
+  description: Update a CustomerGroup.
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the customer group.
+      schema:
+        type: string
+  requestBody:
+    content:
+      application/json:
+        schema:
+          properties:
+            name:
+              description: Name of the customer group
+              type: string
+            metadata:
+              description: Metadata for the customer.
+              type: object
+  tags:
+    - Customer Group
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              customer_group:
+                $ref: ../components/schemas/customer_group.yaml

docs/api/admin/paths/customer-groups_{id}_customers.yaml

@@ -0,0 +1,34 @@
+get:
+  operationId: GetCustomerGroupsGroupCustomers
+  summary: List Customers
+  description: Retrieves a list of customers in a customer group
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the customer group.
+      schema:
+        type: string
+  tags:
+    - Customer Group
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              customers:
+                type: array
+                items:
+                  $ref: ../components/schemas/customer.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/customer-groups_{id}_customers_batch.yaml

@@ -0,0 +1,80 @@
+post:
+  operationId: PostCustomerGroupsGroupCustomersBatch
+  summary: 'Add a list of customers to a customer group '
+  description: Adds a list of customers, represented by id's, to a customer group.
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the customer group.
+      schema:
+        type: string
+  requestBody:
+    content:
+      application/json:
+        schema:
+          required:
+            - customer_ids
+          properties:
+            customer_ids:
+              description: The ids of the customers to add
+              type: array
+              items:
+                required:
+                  - id
+                properties:
+                  id:
+                    description: ID of the customer
+                    type: string
+  tags:
+    - Customer Group
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              customer_group:
+                $ref: ../components/schemas/customer_group.yaml
+delete:
+  operationId: DeleteCustomerGroupsGroupCustomerBatch
+  summary: 'Remove a list of customers from a customer group '
+  description: Removes a list of customers, represented by id's, from a customer group.
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the customer group.
+      schema:
+        type: string
+  requestBody:
+    content:
+      application/json:
+        schema:
+          required:
+            - customer_ids
+          properties:
+            customer_ids:
+              description: The ids of the customers to remove
+              type: array
+              items:
+                required:
+                  - id
+                properties:
+                  id:
+                    description: ID of the customer
+                    type: string
+  tags:
+    - Customer Group
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              customer_group:
+                $ref: ../components/schemas/customer_group.yaml

docs/api/admin/paths/customers.yaml

@@ -0,0 +1,98 @@
+post:
+  operationId: PostCustomers
+  summary: Create a Customer
+  description: Creates a Customer.
+  x-authenticated: true
+  requestBody:
+    content:
+      application/json:
+        schema:
+          required:
+            - email
+            - first_name
+            - last_name
+            - password
+          properties:
+            email:
+              type: string
+              description: The customer's email.
+              format: email
+            first_name:
+              type: string
+              description: The customer's first name.
+            last_name:
+              type: string
+              description: The customer's last name.
+            password:
+              type: string
+              description: The customer's password.
+              format: password
+            phone:
+              type: string
+              description: The customer's phone number.
+            metadata:
+              description: >-
+                An optional set of key-value pairs to hold additional
+                information.
+              type: object
+  tags:
+    - Customer
+  responses:
+    '201':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              customer:
+                $ref: ../components/schemas/customer.yaml
+get:
+  operationId: GetCustomers
+  summary: List Customers
+  description: Retrieves a list of Customers.
+  x-authenticated: true
+  parameters:
+    - in: query
+      name: limit
+      description: The number of items to return.
+      schema:
+        type: integer
+        default: 50
+    - in: query
+      name: offset
+      description: The items to skip before result.
+      schema:
+        type: integer
+        default: 0
+    - in: query
+      name: expand
+      description: (Comma separated) Which fields should be expanded in each customer.
+      schema:
+        type: string
+    - in: query
+      name: q
+      description: a search term to search email, first_name, and last_name.
+      schema:
+        type: string
+  tags:
+    - Customer
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              customers:
+                type: array
+                items:
+                  $ref: ../components/schemas/customer.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/customers_{id}.yaml

@@ -0,0 +1,103 @@
+get:
+  operationId: GetCustomersCustomer
+  summary: Retrieve a Customer
+  description: Retrieves a Customer.
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the Customer.
+      schema:
+        type: string
+    - in: query
+      name: expand
+      description: (Comma separated) Which fields should be expanded in the customer.
+      schema:
+        type: string
+    - in: query
+      name: fields
+      description: (Comma separated) Which fields should be included in the customer.
+      schema:
+        type: string
+  tags:
+    - Customer
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              customer:
+                $ref: ../components/schemas/customer.yaml
+post:
+  operationId: PostCustomersCustomer
+  summary: Update a Customer
+  description: Updates a Customer.
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the Customer.
+      schema:
+        type: string
+    - in: query
+      name: expand
+      description: (Comma separated) Which fields should be expanded in each customer.
+      schema:
+        type: string
+    - in: query
+      name: fields
+      description: (Comma separated) Which fields should be retrieved in each customer.
+      schema:
+        type: string
+  requestBody:
+    content:
+      application/json:
+        schema:
+          properties:
+            email:
+              type: string
+              description: The Customer's email.
+              format: email
+            first_name:
+              type: string
+              description: The Customer's first name.
+            last_name:
+              type: string
+              description: The Customer's last name.
+            phone:
+              type: string
+              description: The Customer's phone number.
+            password:
+              type: string
+              description: The Customer's password.
+              format: password
+            groups:
+              type: array
+              items:
+                required:
+                  - id
+                properties:
+                  id:
+                    description: The ID of a customer group
+                    type: string
+              description: A list of customer groups to which the customer belongs.
+            metadata:
+              description: >-
+                An optional set of key-value pairs to hold additional
+                information.
+              type: object
+  tags:
+    - Customer
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              customer:
+                $ref: ../components/schemas/customer.yaml

docs/api/admin/paths/discounts.yaml

@@ -0,0 +1,250 @@
+post:
+  operationId: PostDiscounts
+  summary: Creates a Discount
+  x-authenticated: true
+  description: >-
+    Creates a Discount with a given set of rules that define how the Discount
+    behaves.
+  parameters:
+    - in: query
+      name: expand
+      description: (Comma separated) Which fields should be expanded in each customer.
+      schema:
+        type: string
+    - in: query
+      name: fields
+      description: (Comma separated) Which fields should be retrieved in each customer.
+      schema:
+        type: string
+  requestBody:
+    content:
+      application/json:
+        schema:
+          required:
+            - code
+            - rule
+          properties:
+            code:
+              type: string
+              description: A unique code that will be used to redeem the Discount
+            is_dynamic:
+              type: boolean
+              description: >-
+                Whether the Discount should have multiple instances of itself,
+                each with a different code. This can be useful for automatically
+                generated codes that all have to follow a common set of rules.
+              default: false
+            rule:
+              description: The Discount Rule that defines how Discounts are calculated
+              type: object
+              required:
+                - type
+                - value
+                - allocation
+              properties:
+                description:
+                  type: string
+                  description: A short description of the discount
+                type:
+                  type: string
+                  description: >-
+                    The type of the Discount, can be `fixed` for discounts that
+                    reduce the price by a fixed amount, `percentage` for
+                    percentage reductions or `free_shipping` for shipping
+                    vouchers.
+                  enum:
+                    - fixed
+                    - percentage
+                    - free_shipping
+                value:
+                  type: number
+                  description: >-
+                    The value that the discount represents; this will depend on
+                    the type of the discount
+                allocation:
+                  type: string
+                  description: The scope that the discount should apply to.
+                  enum:
+                    - total
+                    - item
+                conditions:
+                  type: array
+                  description: >-
+                    A set of conditions that can be used to limit when  the
+                    discount can be used. Only one of `products`,
+                    `product_types`, `product_collections`, `product_tags`, and
+                    `customer_groups` should be provided.
+                  items:
+                    type: object
+                    required:
+                      - operator
+                    properties:
+                      operator:
+                        type: string
+                        description: Operator of the condition
+                        enum:
+                          - in
+                          - not_in
+                      products:
+                        type: array
+                        description: >-
+                          list of product IDs if the condition is applied on
+                          products.
+                        items:
+                          type: string
+                      product_types:
+                        type: array
+                        description: >-
+                          list of product type IDs if the condition is applied
+                          on product types.
+                        items:
+                          type: string
+                      product_collections:
+                        type: array
+                        description: >-
+                          list of product collection IDs if the condition is
+                          applied on product collections.
+                        items:
+                          type: string
+                      product_tags:
+                        type: array
+                        description: >-
+                          list of product tag IDs if the condition is applied on
+                          product tags.
+                        items:
+                          type: string
+                      customer_groups:
+                        type: array
+                        description: >-
+                          list of customer group IDs if the condition is applied
+                          on customer groups.
+                        items:
+                          type: string
+            is_disabled:
+              type: boolean
+              description: >-
+                Whether the Discount code is disabled on creation. You will have
+                to enable it later to make it available to Customers.
+              default: false
+            starts_at:
+              type: string
+              format: date-time
+              description: The time at which the Discount should be available.
+            ends_at:
+              type: string
+              format: date-time
+              description: The time at which the Discount should no longer be available.
+            valid_duration:
+              type: string
+              description: Duration the discount runs between
+              example: P3Y6M4DT12H30M5S
+            regions:
+              description: >-
+                A list of Region ids representing the Regions in which the
+                Discount can be used.
+              type: array
+              items:
+                type: string
+            usage_limit:
+              type: number
+              description: Maximum times the discount can be used
+            metadata:
+              description: >-
+                An optional set of key-value pairs to hold additional
+                information.
+              type: object
+  tags:
+    - Discount
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              discount:
+                $ref: ../components/schemas/discount.yaml
+get:
+  operationId: GetDiscounts
+  summary: List Discounts
+  x-authenticated: true
+  description: Retrieves a list of Discounts
+  parameters:
+    - in: query
+      name: q
+      description: Search query applied on the code field.
+      schema:
+        type: string
+    - in: query
+      name: rule
+      description: Discount Rules filters to apply on the search
+      schema:
+        type: object
+        properties:
+          type:
+            type: string
+            enum:
+              - fixed
+              - percentage
+              - free_shipping
+            description: >-
+              The type of the Discount, can be `fixed` for discounts that reduce
+              the price by a fixed amount, `percentage` for percentage
+              reductions or `free_shipping` for shipping vouchers.
+          allocation:
+            type: string
+            enum:
+              - total
+              - item
+            description: >-
+              The value that the discount represents; this will depend on the
+              type of the discount
+    - in: query
+      name: is_dynamic
+      description: Return only dynamic discounts.
+      schema:
+        type: boolean
+    - in: query
+      name: is_disabled
+      description: Return only disabled discounts.
+      schema:
+        type: boolean
+    - 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
+  tags:
+    - Discount
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              discounts:
+                type: array
+                items:
+                  $ref: ../components/schemas/discount.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/discounts_code_{code}.yaml

@@ -0,0 +1,33 @@
+get:
+  operationId: GetDiscountsDiscountCode
+  summary: Retrieve a Discount by code
+  description: Retrieves a Discount by its discount code
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: code
+      required: true
+      description: The code of the Discount
+      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
+  tags:
+    - Discount
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              discount:
+                $ref: ../components/schemas/discount.yaml