{ "openapi": "3.0.0", "info": { "version": "1.0.0", "title": "Medusa Storefront API", "description": "API reference for Medusa's Storefront endpoints. All endpoints are prefixed with `/store`.\n\n## Authentication\n\nTo send requests as an authenticated customer, you must use the Cookie Session ID.\n\n\n\n## Expanding Fields\n\nIn many endpoints you'll find an `expand` query parameter that can be passed to the endpoint. You can use the `expand` query parameter to unpack an entity's relations and return them in the response.\n\nPlease note that the relations you pass to `expand` replace any relations that are expanded by default in the request.\n\n### Expanding One Relation\n\nFor example, when you retrieve a product, you can retrieve its collection by passing to the `expand` query parameter the value `collection`:\n\n```bash\ncurl \"http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand=collection\"\n```\n\n### Expanding Multiple Relations\n\nYou can expand more than one relation by separating the relations in the `expand` query parameter with a comma.\n\nFor example, to retrieve both the variants and the collection of a product, pass to the `expand` query parameter the value `variants,collection`:\n\n```bash\ncurl \"http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand=variants,collection\"\n```\n\n### Prevent Expanding Relations\n\nSome requests expand relations by default. You can prevent that by passing an empty expand value to retrieve an entity without any extra relations.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand\"\n```\n\nThis would retrieve the product with only its properties, without any relations like `collection`.\n\n## Selecting Fields\n\nIn many endpoints you'll find a `fields` query parameter that can be passed to the endpoint. You can use the `fields` query parameter to specify which fields in the entity should be returned in the response.\n\nPlease note that if you pass a `fields` query parameter, only the fields you pass in the value along with the `id` of the entity will be returned in the response.\n\nAlso, the `fields` query parameter does not affect the expanded relations. You'll have to use the `expand` parameter instead.\n\n### Selecting One Field\n\nFor example, when you retrieve a list of products, you can retrieve only the titles of the products by passing `title` as a value to the `fields` query parameter:\n\n```bash\ncurl \"http://localhost:9000/store/products?fields=title\"\n```\n\nAs mentioned above, the expanded relations such as `variants` will still be returned as they're not affected by the `fields` parameter.\n\nYou can ensure that only the `title` field is returned by passing an empty value to the `expand` query parameter. For example:\n\n```bash\ncurl \"http://localhost:9000/store/products?fields=title&expand\"\n```\n\n### Selecting Multiple Fields\n\nYou can pass more than one field by seperating the field names in the `fields` query parameter with a comma.\n\nFor example, to select the `title` and `handle` of a product:\n\n```bash\ncurl \"http://localhost:9000/store/products?fields=title,handle\"\n```\n\n### Retrieve Only the ID\n\nYou can pass an empty `fields` query parameter to return only the ID of an entity. For example:\n\n```bash\ncurl \"http://localhost:9000/store/products?fields\"\n```\n\nYou can also pair with an empty `expand` query parameter to ensure that the relations aren't retrieved as well. For example:\n\n```bash\ncurl \"http://localhost:9000/store/products?fields&expand\"\n```\n\n## Query Parameter Types\n\nThis section covers how to pass some common data types as query parameters. This is useful if you're sending requests to the API endpoints and not using our JS Client. For example, when using cURL or Postman.\n\n### Strings\n\nYou can pass a string value in the form of `=`.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/store/products?title=Shirt\"\n```\n\nIf the string has any characters other than letters and numbers, you must encode them.\n\nFor example, if the string has spaces, you can encode the space with `+` or `%20`:\n\n```bash\ncurl \"http://localhost:9000/store/products?title=Blue%20Shirt\"\n```\n\nYou can use tools like [this one](https://www.urlencoder.org/) to learn how a value can be encoded.\n\n### Integers\n\nYou can pass an integer value in the form of `=`.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/store/products?offset=1\"\n```\n\n### Boolean\n\nYou can pass a boolean value in the form of `=`.\n\nFor example:\n\n```bash\ncurl \"http://localhost:9000/store/products?is_giftcard=true\"\n```\n\n### Date and DateTime\n\nYou can pass a date value in the form `=`. The date must be in the format `YYYY-MM-DD`.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/store/products?created_at[lt]=2023-02-17\"\n```\n\nYou can also pass the time using the format `YYYY-MM-DDTHH:MM:SSZ`. Please note that the `T` and `Z` here are fixed.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/store/products?created_at[lt]=2023-02-17T07:22:30Z\"\n```\n\n### Array\n\nEach array value must be passed as a separate query parameter in the form `[]=`. You can also specify the index of each parameter in the brackets `[0]=`.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/store/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7\"\n```\n\nNote that the `-g` parameter passed to `curl` disables errors being thrown for using the brackets. Read more [here](https://curl.se/docs/manpage.html#-g).\n\n### Object\n\nObject parameters must be passed as separate query parameters in the form `[]=`.\n\nFor example:\n\n```bash\ncurl -g \"http://localhost:9000/store/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17\"\n```\n\n## Pagination\n\n### Query Parameters\n\nIn listing endpoints, such as list customers or list products, you can control the pagination using the query parameters `limit` and `offset`.\n\n`limit` is used to specify the maximum number of items that can be return in the response. `offset` is used to specify how many items to skip before returning the resulting entities.\n\nYou can use the `offset` query parameter to change between pages. For example, if the limit is 50, at page 1 the offset should be 0; at page 2 the offset should be 50, and so on.\n\nFor example, to limit the number of products returned in the List Products endpoint:\n\n```bash\ncurl \"http://localhost:9000/store/products?limit=5\"\n```\n\n### Response Fields\n\nIn the response of listing endpoints, aside from the entities retrieved, there are three pagination-related fields returned: `count`, `limit`, and `offset`.\n\nSimilar to the query parameters, `limit` is the maximum number of items that can be returned in the response, and `field` is the number of items that were skipped before the entities in the result.\n\n`count` is the total number of available items of this entity. It can be used to determine how many pages are there.\n\nFor example, if the `count` is 100 and the `limit` is 50, you can divide the `count` by the `limit` to get the number of pages: `100/50 = 2 pages`.\n\n### Sort Order\n\nThe `order` field available on endpoints supporting pagination allows you to sort the retrieved items by an attribute of that item. For example, you can sort products by their `created_at` attribute by setting `order` to `created_at`:\n\n```bash\ncurl \"http://localhost:9000/list/products?order=created_at\"\n```\n\nBy default, the sort direction will be ascending. To change it to descending, pass a dash (`-`) before the attribute name. For example:\n\n```bash\ncurl \"http://localhost:9000/list/products?order=-created_at\"\n```\n\nThis sorts the products by their `created_at` attribute in the descending order.\n", "license": { "name": "MIT", "url": "https://github.com/medusajs/medusa/blob/master/LICENSE" } }, "tags": [ { "name": "Auth", "description": "Authentication endpoints allow customers to manage their session, such as login or log out.\nWhen a customer is logged in, the cookie header is set indicating the customer's login session.\n", "externalDocs": { "description": "How to implement customer profiles in your storefront", "url": "https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles" } }, { "name": "Carts", "description": "A cart is a virtual shopping bag that customers can use to add items they want to purchase.\nA cart is then used to checkout and place an order.\n", "externalDocs": { "description": "How to implement cart functionality in your storefront", "url": "https://docs.medusajs.com/modules/carts-and-checkout/storefront/implement-cart" } }, { "name": "Customers", "description": "A customer can register and manage their information such as addresses, orders, payment methods, and more.\n", "externalDocs": { "description": "How to implement customer profiles in your storefront", "url": "https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles" } }, { "name": "Gift Cards", "description": "Customers can use gift cards during checkout to deduct the gift card's balance from the checkout total.\nThe Gift Card endpoints allow retrieving a gift card's details by its code. A gift card can be applied to a cart using the Carts endpoints.\n", "externalDocs": { "description": "How to use gift cards in a storefront", "url": "https://docs.medusajs.com/modules/gift-cards/storefront/use-gift-cards" } }, { "name": "Orders", "description": "Orders are purchases made by customers, typically through a storefront.\nOrders are placed and created using the Carts endpoints. The Orders endpoints allow retrieving and claiming orders.\n", "externalDocs": { "description": "How to retrieve order details in a storefront", "url": "https://docs.medusajs.com/modules/orders/storefront/retrieve-order-details" } }, { "name": "Order Edits", "description": "Order edits are changes made to items in an order such as adding, updating their quantity, or deleting them. Order edits are created by the admin.\nA customer can review order edit requests created by an admin and confirm or decline them.\n", "externalDocs": { "description": "How to handle order edits in a storefront", "url": "https://docs.medusajs.com/modules/orders/storefront/handle-order-edits" } }, { "name": "Payment Collections", "description": "A payment collection is useful for managing additional payments, such as for Order Edits, or installment payments.\n" }, { "name": "Products", "description": "Products are saleable items in a store. This also includes [saleable gift cards](https://docs.medusajs.com/modules/gift-cards/storefront/use-gift-cards) in a store.\nUsing these endpoints, you can filter products by categories, collections, sales channels, and more.\n", "externalDocs": { "description": "How to show products in a storefront", "url": "https://docs.medusajs.com/modules/products/storefront/show-products" } }, { "name": "Product Variants", "description": "Product variants are the actual salable item in your store. Each variant is a combination of the different option values available on the product.\n" }, { "name": "Product Categories", "description": "Products can be categoriezed into categories. A product can be associated more than one category.\nUsing these endpoints, you can list or retrieve a category's details and products.\n", "externalDocs": { "description": "How to use product categories in a storefront", "url": "https://docs.medusajs.com/modules/products/storefront/use-categories" } }, { "name": "Product Collections", "description": "A product collection is used to organize products for different purposes such as marketing or discount purposes. For example, you can create a Summer Collection.\nUsing these endpoints, you can list or retrieve a collection's details and products.\n" }, { "name": "Product Tags", "description": "Product tags are string values that can be used to filter products by.\nProducts can have more than one tag, and products can share tags.\n" }, { "name": "Product Types", "description": "Product types are string values that can be used to filter products by.\nProducts can have more than one tag, and products can share types.\n" }, { "name": "Regions", "description": "Regions are different countries or geographical regions that the commerce store serves customers in.\nCustomers can choose what region they're in, which can be used to change the prices shown based on the region and its currency.\n", "externalDocs": { "description": "How to use regions in a storefront", "url": "https://docs.medusajs.com/modules/regions-and-currencies/storefront/use-regions" } }, { "name": "Returns", "description": "A return can be created by a customer to return items in an order.\n", "externalDocs": { "description": "How to create a return in a storefront", "url": "https://docs.medusajs.com/modules/orders/storefront/create-return" } }, { "name": "Return Reasons", "description": "Return reasons are key-value pairs that are used to specify why an order return is being created.\n" }, { "name": "Shipping Options", "description": "A shipping option is used to define the available shipping methods during checkout or when creating a return.\n", "externalDocs": { "description": "Shipping Option architecture", "url": "https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-option" } }, { "name": "Swaps", "description": "A swap is created by a customer or an admin to exchange an item with a new one.\nCreating a swap implicitely includes creating a return for the item being exchanged.\n", "externalDocs": { "description": "How to create a swap in a storefront", "url": "https://docs.medusajs.com/modules/orders/storefront/create-swap" } } ], "servers": [ { "url": "https://api.medusa-commerce.com" } ], "paths": { "/store/auth": { "get": { "operationId": "GetAuth", "summary": "Get Current Customer", "description": "Retrieve the currently logged in Customer's details.", "x-authenticated": true, "x-codegen": { "method": "getSession" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged\nmedusa.auth.getSession()\n.then(({ customer }) => {\n console.log(customer.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/auth' \\\n-H 'Cookie: connect.sid={sid}'\n" } ], "security": [ { "cookie_auth": [] } ], "tags": [ "Auth" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreAuthRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } }, "post": { "operationId": "PostAuth", "summary": "Customer Login", "description": "Log a customer in and includes the Cookie session in the response header. The cookie session can be used in subsequent requests to authenticate the customer. When using Medusa's JS or Medusa React clients, the cookie is automatically attached to subsequent requests.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostAuthReq" } } } }, "x-codegen": { "method": "authenticate" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.auth.authenticate({\n email: \"user@example.com\",\n password: \"user@example.com\"\n})\n.then(({ customer }) => {\n console.log(customer.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/auth' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"email\": \"user@example.com\",\n \"password\": \"supersecret\"\n}'\n" } ], "tags": [ "Auth" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreAuthRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/incorrect_credentials" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } }, "delete": { "operationId": "DeleteAuth", "summary": "Customer Log out", "description": "Delete the current session for the logged in customer.", "x-authenticated": true, "x-codegen": { "method": "deleteSession" }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X DELETE 'https://medusa-url.com/store/auth' \\\n-H 'Cookie: connect.sid={sid}'\n" } ], "security": [ { "cookie_auth": [] } ], "tags": [ "Auth" ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/auth/{email}": { "get": { "operationId": "GetAuthEmail", "summary": "Check if Email Exists", "description": "Check if there's a customer already registered with the provided email.", "parameters": [ { "in": "path", "name": "email", "schema": { "type": "string", "format": "email" }, "required": true, "description": "The email to check." } ], "x-codegen": { "method": "exists" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.auth.exists(\"user@example.com\")\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/auth/user@example.com'\n" } ], "tags": [ "Auth" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreGetAuthEmailRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/carts": { "post": { "operationId": "PostCart", "summary": "Create a Cart", "description": "Create a Cart. Although optional, specifying the cart's region and sales channel can affect the cart's pricing and\nthe products that can be added to the cart respectively. So, make sure to set those early on and change them if necessary, such as when the customer changes their region.\n\nIf a customer is logged in, the cart's customer ID and email will automatically be set.\n", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostCartReq" } } } }, "x-codegen": { "method": "create" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.create()\n.then(({ cart }) => {\n console.log(cart.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/carts'\n" } ], "tags": [ "Carts" ], "responses": { "200": { "description": "Successfully created a new Cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCartsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/carts/{id}": { "get": { "operationId": "GetCartsCart", "summary": "Get a Cart", "description": "Retrieve a Cart's details. This includes recalculating its totals.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Cart.", "schema": { "type": "string" } } ], "x-codegen": { "method": "retrieve" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.retrieve(cartId)\n.then(({ cart }) => {\n console.log(cart.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/carts/{id}'\n" } ], "tags": [ "Carts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCartsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } }, "post": { "operationId": "PostCartsCart", "summary": "Update a Cart", "description": "Update a Cart's details. If the cart has payment sessions and the region was not changed, the payment sessions are updated. The cart's totals are also recalculated.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Cart.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostCartsCartReq" } } } }, "x-codegen": { "method": "update" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.update(cartId, {\n email: \"user@example.com\"\n})\n.then(({ cart }) => {\n console.log(cart.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"email\": \"user@example.com\"\n}'\n" } ], "tags": [ "Carts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCartsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/carts/{id}/complete": { "post": { "summary": "Complete a Cart", "operationId": "PostCartsCartComplete", "description": "Complete a cart and place an order or create a swap, based on what the cart is created for. This includes attempting to authorize the cart's payment.\nIf authorizing the payment requires more action, the cart will not be completed and the order will not be placed or the swap will not be created.\n\nAn idempotency key will be generated if none is provided in the header `Idempotency-Key` and added to\nthe response. If an error occurs during cart completion or the request is interrupted for any reason, the cart completion can be retried by passing the idempotency\nkey in the `Idempotency-Key` header.\n", "externalDocs": { "description": "Cart completion overview", "url": "https://docs.medusajs.com/modules/carts-and-checkout/cart#cart-completion" }, "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The Cart ID.", "schema": { "type": "string" } } ], "x-codegen": { "method": "complete" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.complete(cartId)\n.then(({ cart }) => {\n console.log(cart.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}/complete'\n" } ], "tags": [ "Carts" ], "responses": { "200": { "description": "If the payment of the cart was successfully authorized, but requires further action from the customer, the response body will contain the cart with an updated payment session. Otherwise, if the payment was authorized and the cart was successfully completed, the response body will contain either the newly created order or swap, depending on what the cart was created for.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCompleteCartRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/carts/{id}/discounts/{code}": { "delete": { "operationId": "DeleteCartsCartDiscountsDiscount", "summary": "Remove Discount", "description": "Remove a Discount from a Cart. This only removes the application of the discount, and not completely delete it. The totals will be re-calculated and the payment sessions will be refreshed after the removal.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Cart.", "schema": { "type": "string" } }, { "in": "path", "name": "code", "required": true, "description": "The unique discount code.", "schema": { "type": "string" } } ], "x-codegen": { "method": "deleteDiscount" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.deleteDiscount(cartId, code)\n.then(({ cart }) => {\n console.log(cart.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X DELETE 'https://medusa-url.com/store/carts/{id}/discounts/{code}'\n" } ], "tags": [ "Carts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCartsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/carts/{id}/line-items": { "post": { "operationId": "PostCartsCartLineItems", "summary": "Add a Line Item", "description": "Generates a Line Item with a given Product Variant and adds it to the Cart", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The id of the Cart to add the Line Item to.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostCartsCartLineItemsReq" } } } }, "x-codegen": { "method": "createLineItem" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.lineItems.create(cart_id, {\n variant_id,\n quantity: 1\n})\n.then(({ cart }) => {\n console.log(cart.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}/line-items' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"variant_id\": \"{variant_id}\",\n \"quantity\": 1\n}'\n" } ], "tags": [ "Carts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCartsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/carts/{id}/line-items/{line_id}": { "post": { "operationId": "PostCartsCartLineItemsItem", "summary": "Update a Line Item", "description": "Update a line item's quantity.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Cart.", "schema": { "type": "string" } }, { "in": "path", "name": "line_id", "required": true, "description": "The ID of the Line Item.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostCartsCartLineItemsItemReq" } } } }, "x-codegen": { "method": "updateLineItem" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.lineItems.update(cartId, lineId, {\n quantity: 1\n})\n.then(({ cart }) => {\n console.log(cart.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}/line-items/{line_id}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"quantity\": 1\n}'\n" } ], "tags": [ "Carts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCartsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } }, "delete": { "operationId": "DeleteCartsCartLineItemsItem", "summary": "Delete a Line Item", "description": "Delete a Line Item from a Cart. The payment sessions will be updated and the totals will be recalculated.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Cart.", "schema": { "type": "string" } }, { "in": "path", "name": "line_id", "required": true, "description": "The ID of the Line Item.", "schema": { "type": "string" } } ], "x-codegen": { "method": "deleteLineItem" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.lineItems.delete(cartId, lineId)\n.then(({ cart }) => {\n console.log(cart.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X DELETE 'https://medusa-url.com/store/carts/{id}/line-items/{line_id}'\n" } ], "tags": [ "Carts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCartsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/carts/{id}/payment-session": { "post": { "operationId": "PostCartsCartPaymentSession", "summary": "Select a Payment Session", "description": "Select the Payment Session that will be used to complete the cart. This is typically used when the customer chooses their preferred payment method during checkout. The totals of the cart will be recalculated.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Cart.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostCartsCartPaymentSessionReq" } } } }, "x-codegen": { "method": "setPaymentSession" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.setPaymentSession(cartId, {\n provider_id: \"manual\"\n})\n.then(({ cart }) => {\n console.log(cart.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}/payment-sessions' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"provider_id\": \"manual\"\n}'\n" } ], "tags": [ "Carts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCartsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/carts/{id}/payment-sessions": { "post": { "operationId": "PostCartsCartPaymentSessions", "summary": "Create Payment Sessions", "description": "Create Payment Sessions for each of the available Payment Providers in the Cart's Region. If there only one payment session is created, it will be selected by default. The creation of the payment session uses the payment provider and may require sending requests to third-party services.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Cart.", "schema": { "type": "string" } } ], "x-codegen": { "method": "createPaymentSessions" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.createPaymentSessions(cartId)\n.then(({ cart }) => {\n console.log(cart.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}/payment-sessions'\n" } ], "tags": [ "Carts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCartsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/carts/{id}/payment-sessions/{provider_id}": { "post": { "operationId": "PostCartsCartPaymentSessionUpdate", "summary": "Update a Payment Session", "description": "Update a Payment Session with additional data. This can be useful depending on the payment provider used. All payment sessions are updated and cart totals are recalculated afterwards.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Cart.", "schema": { "type": "string" } }, { "in": "path", "name": "provider_id", "required": true, "description": "The ID of the payment provider.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostCartsCartPaymentSessionUpdateReq" } } } }, "x-codegen": { "method": "updatePaymentSession" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.updatePaymentSession(cartId, \"manual\", {\n data: {\n\n }\n})\n.then(({ cart }) => {\n console.log(cart.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}/payment-sessions/manual' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"data\": {}\n}'\n" } ], "tags": [ "Carts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCartsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } }, "delete": { "operationId": "DeleteCartsCartPaymentSessionsSession", "summary": "Delete a Payment Session", "description": "Delete a Payment Session in a Cart. May be useful if a payment has failed. The totals will be recalculated.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Cart.", "schema": { "type": "string" } }, { "in": "path", "name": "provider_id", "required": true, "description": "The ID of the Payment Provider used to create the Payment Session to be deleted.", "schema": { "type": "string" } } ], "x-codegen": { "method": "deletePaymentSession" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.deletePaymentSession(cartId, \"manual\")\n.then(({ cart }) => {\n console.log(cart.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X DELETE 'https://medusa-url.com/store/carts/{id}/payment-sessions/{provider_id}'\n" } ], "tags": [ "Carts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCartsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/carts/{id}/payment-sessions/{provider_id}/refresh": { "post": { "operationId": "PostCartsCartPaymentSessionsSession", "summary": "Refresh a Payment Session", "description": "Refresh a Payment Session to ensure that it is in sync with the Cart. This is usually not necessary, but is provided for edge cases.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Cart.", "schema": { "type": "string" } }, { "in": "path", "name": "provider_id", "required": true, "description": "The ID of the Payment Provider that created the Payment Session to be refreshed.", "schema": { "type": "string" } } ], "x-codegen": { "method": "refreshPaymentSession" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.refreshPaymentSession(cartId, \"manual\")\n.then(({ cart }) => {\n console.log(cart.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}/payment-sessions/{provider_id}/refresh'\n" } ], "tags": [ "Carts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCartsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/carts/{id}/shipping-methods": { "post": { "operationId": "PostCartsCartShippingMethod", "summary": "Add Shipping Method", "description": "Add a Shipping Method to the Cart. The validation of the `data` field is handled by the fulfillment provider of the chosen shipping option.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The cart ID.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostCartsCartShippingMethodReq" } } } }, "x-codegen": { "method": "addShippingMethod" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.carts.addShippingMethod(cartId, {\n option_id\n})\n.then(({ cart }) => {\n console.log(cart.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}/shipping-methods' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"option_id\": \"{option_id}\",\n}'\n" } ], "tags": [ "Carts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCartsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/carts/{id}/taxes": { "post": { "operationId": "PostCartsCartTaxes", "summary": "Calculate Cart Taxes", "description": "Calculate the taxes for a cart. This is useful if the `automatic_taxes` field of the cart's region is set to `false`. If the cart's region uses a tax provider other than Medusa's system provider, this may lead to sending requests to third-party services.", "externalDocs": { "description": "How to calculate taxes manually during checkout", "url": "https://docs.medusajs.com/modules/taxes/storefront/manual-calculation" }, "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The Cart ID.", "schema": { "type": "string" } } ], "x-codegen": { "method": "calculateTaxes" }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/carts/{id}/taxes'\n" } ], "tags": [ "Carts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCartsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/collections": { "get": { "operationId": "GetCollections", "summary": "List Collections", "description": "Retrieve a list of product collections. The product collections can be filtered by fields such as `handle` or `created_at`. The product collections can also be paginated.", "parameters": [ { "in": "query", "name": "offset", "description": "The number of product collections to skip when retrieving the product collections.", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "limit", "description": "Limit the number of product collections returned.", "schema": { "type": "integer", "default": 10 } }, { "in": "query", "name": "handle", "style": "form", "explode": false, "description": "Filter by handles", "schema": { "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "created_at", "description": "Filter by a creation date range.", "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": "Filter by an update date range.", "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" } } } } ], "x-codegen": { "method": "list", "queryParams": "StoreGetCollectionsParams" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.collections.list()\n.then(({ collections, limit, offset, count }) => {\n console.log(collections.length);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/collections'\n" } ], "tags": [ "Product Collections" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCollectionsListRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/collections/{id}": { "get": { "operationId": "GetCollectionsCollection", "summary": "Get a Collection", "description": "Retrieve a Product Collection's details.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The id of the Product Collection", "schema": { "type": "string" } } ], "x-codegen": { "method": "retrieve" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.collections.retrieve(collectionId)\n.then(({ collection }) => {\n console.log(collection.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/collections/{id}'\n" } ], "tags": [ "Product Collections" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCollectionsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/customers": { "post": { "operationId": "PostCustomers", "summary": "Create a Customer", "description": "Register a new customer. This will also automatically authenticate the customer and set their login session in the response Cookie header. The cookie session can be used in subsequent requests to authenticate the customer. When using Medusa's JS or Medusa React clients, the cookie is automatically attached to subsequent requests.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostCustomersReq" } } } }, "x-codegen": { "method": "create" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.customers.create({\n first_name: \"Alec\",\n last_name: \"Reynolds\",\n email: \"user@example.com\",\n password: \"supersecret\"\n})\n.then(({ customer }) => {\n console.log(customer.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/customers' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"first_name\": \"Alec\",\n \"last_name\": \"Reynolds\",\n \"email\": \"user@example.com\",\n \"password\": \"supersecret\"\n}'\n" } ], "tags": [ "Customers" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCustomersRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "description": "A customer with the same email exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "The error code" }, "type": { "type": "string", "description": "The type of error" }, "message": { "type": "string", "description": "Human-readable message with details about the error" } } }, "example": { "code": "invalid_request_error", "type": "duplicate_error", "message": "A customer with the given email already has an account. Log in instead" } } } }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/customers/me": { "get": { "operationId": "GetCustomersCustomer", "summary": "Get a Customer", "description": "Retrieve the logged-in Customer's details.", "x-authenticated": true, "x-codegen": { "method": "retrieve" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged\nmedusa.customers.retrieve()\n.then(({ customer }) => {\n console.log(customer.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/customers/me' \\\n-H 'Cookie: connect.sid={sid}'\n" } ], "security": [ { "cookie_auth": [] } ], "tags": [ "Customers" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCustomersRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } }, "post": { "operationId": "PostCustomersCustomer", "summary": "Update Customer", "description": "Update the logged-in customer's details.", "x-authenticated": true, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostCustomersCustomerReq" } } } }, "x-codegen": { "method": "update" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged\nmedusa.customers.update({\n first_name: \"Laury\"\n})\n.then(({ customer }) => {\n console.log(customer.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/customers/me' \\\n-H 'Cookie: connect.sid={sid}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"first_name\": \"Laury\"\n}'\n" } ], "security": [ { "cookie_auth": [] } ], "tags": [ "Customers" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCustomersRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/customers/me/addresses": { "post": { "operationId": "PostCustomersCustomerAddresses", "summary": "Add a Shipping Address", "description": "Add a Shipping Address to a Customer's saved addresses.", "x-authenticated": true, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostCustomersCustomerAddressesReq" } } } }, "x-codegen": { "method": "addAddress" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged\nmedusa.customers.addresses.addAddress({\n address: {\n first_name: \"Celia\",\n last_name: \"Schumm\",\n address_1: \"225 Bednar Curve\",\n city: \"Danielville\",\n country_code: \"US\",\n postal_code: \"85137\",\n phone: \"981-596-6748 x90188\",\n company: \"Wyman LLC\",\n province: \"Georgia\",\n }\n})\n.then(({ customer }) => {\n console.log(customer.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/customers/me/addresses' \\\n-H 'Cookie: connect.sid={sid}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"address\": {\n \"first_name\": \"Celia\",\n \"last_name\": \"Schumm\",\n \"address_1\": \"225 Bednar Curve\",\n \"city\": \"Danielville\",\n \"country_code\": \"US\",\n \"postal_code\": \"85137\"\n }\n}'\n" } ], "security": [ { "cookie_auth": [] } ], "tags": [ "Customers" ], "responses": { "200": { "description": "A successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCustomersRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/customers/me/addresses/{address_id}": { "post": { "operationId": "PostCustomersCustomerAddressesAddress", "summary": "Update a Shipping Address", "description": "Update the logged-in customer's saved Shipping Address's details.", "x-authenticated": true, "parameters": [ { "in": "path", "name": "address_id", "required": true, "description": "The ID of the Address.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostCustomersCustomerAddressesAddressReq" } } } }, "x-codegen": { "method": "updateAddress" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged\nmedusa.customers.addresses.updateAddress(addressId, {\n first_name: \"Gina\"\n})\n.then(({ customer }) => {\n console.log(customer.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/customers/me/addresses/{address_id}' \\\n-H 'Cookie: connect.sid={sid}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"first_name\": \"Gina\"\n}'\n" } ], "security": [ { "cookie_auth": [] } ], "tags": [ "Customers" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCustomersRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } }, "delete": { "operationId": "DeleteCustomersCustomerAddressesAddress", "summary": "Delete an Address", "description": "Delete an Address from the Customer's saved addresses.", "x-authenticated": true, "parameters": [ { "in": "path", "name": "address_id", "required": true, "description": "The id of the Address to remove.", "schema": { "type": "string" } } ], "x-codegen": { "method": "deleteAddress" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged\nmedusa.customers.addresses.deleteAddress(addressId)\n.then(({ customer }) => {\n console.log(customer.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X DELETE 'https://medusa-url.com/store/customers/me/addresses/{address_id}' \\\n-H 'Cookie: connect.sid={sid}'\n" } ], "security": [ { "cookie_auth": [] } ], "tags": [ "Customers" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCustomersRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/customers/me/orders": { "get": { "operationId": "GetCustomersCustomerOrders", "summary": "List Orders", "description": "Retrieve a list of the logged-in Customer's Orders. The orders can be filtered by fields such as `status` or `fulfillment_status`. The orders can also be paginated.", "x-authenticated": true, "parameters": [ { "in": "query", "name": "q", "description": "term to search orders' display ID, email, shipping address's first name, customer's first name, customer's last name, and customer's phone number.", "schema": { "type": "string" } }, { "in": "query", "name": "id", "description": "Filter by ID.", "schema": { "type": "string" } }, { "in": "query", "name": "status", "style": "form", "explode": false, "description": "Filter by status.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "pending", "completed", "archived", "canceled", "requires_action" ] } } }, { "in": "query", "name": "fulfillment_status", "style": "form", "explode": false, "description": "Fulfillment status to search for.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "not_fulfilled", "partially_fulfilled", "fulfilled", "partially_shipped", "shipped", "partially_returned", "returned", "canceled", "requires_action" ] } } }, { "in": "query", "name": "payment_status", "style": "form", "explode": false, "description": "Payment status to search for.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "not_paid", "awaiting", "captured", "partially_refunded", "refunded", "canceled", "requires_action" ] } } }, { "in": "query", "name": "display_id", "description": "Filter by display ID.", "schema": { "type": "string" } }, { "in": "query", "name": "cart_id", "description": "Filter by cart ID.", "schema": { "type": "string" } }, { "in": "query", "name": "email", "description": "Filter by email.", "schema": { "type": "string" } }, { "in": "query", "name": "region_id", "description": "Filter by region ID.", "schema": { "type": "string" } }, { "in": "query", "name": "currency_code", "style": "form", "explode": false, "description": "Filter by the 3 character ISO currency code of the order.", "schema": { "type": "string", "externalDocs": { "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes", "description": "See a list of codes." } } }, { "in": "query", "name": "tax_rate", "description": "Filter by tax rate.", "schema": { "type": "string" } }, { "in": "query", "name": "created_at", "description": "Filter by a creation date range.", "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": "Filter by an update date range.", "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", "description": "Filter by a cancelation date range.", "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 orders returned.", "schema": { "type": "integer", "default": 10 } }, { "in": "query", "name": "offset", "description": "The number of orders to skip when retrieving the orders.", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "expand", "description": "Comma-separated relations that should be expanded in the returned orders.", "schema": { "type": "string" } }, { "in": "query", "name": "fields", "description": "Comma-separated fields that should be included in the returned orders.", "schema": { "type": "string" } } ], "x-codegen": { "method": "listOrders", "queryParams": "StoreGetCustomersCustomerOrdersParams" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged\nmedusa.customers.listOrders()\n.then(({ orders, limit, offset, count }) => {\n console.log(orders);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/customers/me/orders' \\\n-H 'Cookie: connect.sid={sid}'\n" } ], "security": [ { "cookie_auth": [] } ], "tags": [ "Customers" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCustomersListOrdersRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/customers/me/payment-methods": { "get": { "operationId": "GetCustomersCustomerPaymentMethods", "summary": "Get Saved Payment Methods", "description": "Retrieve the logged-in customer's saved payment methods. This endpoint only works with payment providers created with the deprecated Payment Service interface. The payment methods are saved using the Payment Service's third-party service, and not on the Medusa backend. So, they're retrieved from the third-party service.", "x-authenticated": true, "deprecated": true, "x-codegen": { "method": "listPaymentMethods" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged\nmedusa.customers.paymentMethods.list()\n.then(({ payment_methods }) => {\n console.log(payment_methods.length);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/customers/me/payment-methods' \\\n-H 'Cookie: connect.sid={sid}'\n" } ], "security": [ { "cookie_auth": [] } ], "tags": [ "Customers" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCustomersListPaymentMethodsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/customers/password-reset": { "post": { "operationId": "PostCustomersResetPassword", "summary": "Reset Password", "description": "Reset a Customer's password using a password token created by a previous request to the Request Password Reset endpoint. If the password token expired, you must create a new one.", "externalDocs": { "description": "How to reset password", "url": "https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles#reset-password" }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostCustomersResetPasswordReq" } } } }, "x-codegen": { "method": "resetPassword" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.customers.resetPassword({\n email: \"user@example.com\",\n password: \"supersecret\",\n token: \"supersecrettoken\"\n})\n.then(({ customer }) => {\n console.log(customer.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/customers/password-reset' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"email\": \"user@example.com\",\n \"password\": \"supersecret\",\n \"token\": \"supersecrettoken\"\n}'\n" } ], "tags": [ "Customers" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCustomersResetPasswordRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/customers/password-token": { "post": { "operationId": "PostCustomersCustomerPasswordToken", "summary": "Request Password Reset", "description": "Create a reset password token to be used in a subsequent Reset Password endpoint. This emits the event `customer.password_reset`. If a notification provider is installed in the Medusa backend and is configured to handle this event, a notification to the customer, such as an email, may be sent with reset instructions.", "externalDocs": { "description": "How to reset password", "url": "https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles#reset-password" }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostCustomersCustomerPasswordTokenReq" } } } }, "x-codegen": { "method": "generatePasswordToken" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.customers.generatePasswordToken({\n email: \"user@example.com\"\n})\n.then(() => {\n // successful\n})\n.catch(() => {\n // failed\n})\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/customers/password-token' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"email\": \"user@example.com\"\n}'\n" } ], "tags": [ "Customers" ], "responses": { "204": { "description": "OK" }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/gift-cards/{code}": { "get": { "operationId": "GetGiftCardsCode", "summary": "Get Gift Card by Code", "description": "Retrieve a Gift Card's details by its associated unique code.", "parameters": [ { "in": "path", "name": "code", "required": true, "description": "The unique Gift Card code.", "schema": { "type": "string" } } ], "x-codegen": { "method": "retrieve" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.giftCards.retrieve(code)\n.then(({ gift_card }) => {\n console.log(gift_card.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/gift-cards/{code}'\n" } ], "tags": [ "Gift Cards" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreGiftCardsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/order-edits/{id}": { "get": { "operationId": "GetOrderEditsOrderEdit", "summary": "Retrieve an Order Edit", "description": "Retrieve an Order Edit's details.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the OrderEdit.", "schema": { "type": "string" } } ], "x-codegen": { "method": "retrieve" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.orderEdits.retrieve(orderEditId)\n.then(({ order_edit }) => {\n console.log(order_edit.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/order-edits/{id}'\n" } ], "tags": [ "Order Edits" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreOrderEditsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/order-edits/{id}/complete": { "post": { "operationId": "PostOrderEditsOrderEditComplete", "summary": "Complete an Order Edit", "description": "Complete an Order Edit and reflect its changes on the original order. Any additional payment required must be authorized first using the Payment Collection endpoints.", "externalDocs": { "description": "How to handle order edits in a storefront", "url": "https://docs.medusajs.com/modules/orders/storefront/handle-order-edits" }, "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Order Edit.", "schema": { "type": "string" } } ], "x-codegen": { "method": "complete" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.orderEdits.complete(orderEditId)\n .then(({ order_edit }) => {\n console.log(order_edit.id)\n })\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/order-edits/{id}/complete'\n" } ], "tags": [ "Order Edits" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreOrderEditsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/order-edits/{id}/decline": { "post": { "operationId": "PostOrderEditsOrderEditDecline", "summary": "Decline an Order Edit", "description": "Decline an Order Edit. The changes are not reflected on the original order.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the OrderEdit.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostOrderEditsOrderEditDecline" } } } }, "x-codegen": { "method": "decline" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.orderEdits.decline(orderEditId)\n .then(({ order_edit }) => {\n console.log(order_edit.id);\n })\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/order-edits/{id}/decline'\n" } ], "tags": [ "Order Edits" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreOrderEditsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/orders": { "get": { "operationId": "GetOrders", "summary": "Look Up an Order", "description": "Look up an order using filters. If the filters don't narrow down the results to a single order, a 404 response is returned with no orders.", "parameters": [ { "in": "query", "name": "display_id", "required": true, "description": "Filter by ID.", "schema": { "type": "number" } }, { "in": "query", "name": "fields", "description": "Comma-separated fields that should be expanded in the returned order.", "schema": { "type": "string" } }, { "in": "query", "name": "expand", "description": "Comma-separated relations that should be expanded in the returned order.", "schema": { "type": "string" } }, { "in": "query", "name": "email", "style": "form", "explode": false, "description": "Filter by email.", "required": true, "schema": { "type": "string", "format": "email" } }, { "in": "query", "name": "shipping_address", "style": "form", "explode": false, "description": "Filter by the shipping address's postal code.", "schema": { "type": "object", "properties": { "postal_code": { "type": "string", "description": "The postal code of the shipping address" } } } } ], "x-codegen": { "method": "lookupOrder", "queryParams": "StoreGetOrdersParams" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.orders.lookupOrder({\n display_id: 1,\n email: \"user@example.com\"\n})\n.then(({ order }) => {\n console.log(order.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/orders?display_id=1&email=user@example.com'\n" } ], "tags": [ "Orders" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreOrdersRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/orders/batch/customer/token": { "post": { "operationId": "PostOrdersCustomerOrderClaim", "summary": "Claim Order", "description": "Allow the logged-in customer to claim ownership of one or more orders. This generates a token that can be used later on to verify the claim using the endpoint Verify Order Claim. This also emits the event `order-update-token.created`. So, if you have a notification provider installed that handles this event and sends the customer a notification, such as an email, the customer should receive instructions on how to finalize their claim ownership.", "externalDocs": { "description": "How to implement claim-order flow in a storefront", "url": "https://docs.medusajs.com/modules/orders/storefront/implement-claim-order" }, "x-authenticated": true, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostCustomersCustomerOrderClaimReq" } } } }, "x-codegen": { "method": "requestCustomerOrders" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.orders.requestCustomerOrders({\n order_ids,\n})\n.then(() => {\n // successful\n})\n.catch(() => {\n // an error occurred\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/batch/customer/token' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"order_ids\": [\"id\"],\n}'\n" } ], "security": [ { "api_token": [] }, { "cookie_auth": [] } ], "tags": [ "Orders" ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/orders/cart/{cart_id}": { "get": { "operationId": "GetOrdersOrderCartId", "summary": "Get by Cart ID", "description": "Retrieve an Order's details by the ID of the Cart that was used to create the Order.", "parameters": [ { "in": "path", "name": "cart_id", "required": true, "description": "The ID of Cart.", "schema": { "type": "string" } } ], "x-codegen": { "method": "retrieveByCartId" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.orders.retrieveByCartId(cartId)\n.then(({ order }) => {\n console.log(order.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/orders/cart/{cart_id}'\n" } ], "tags": [ "Orders" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreOrdersRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/orders/customer/confirm": { "post": { "operationId": "PostOrdersCustomerOrderClaimsCustomerOrderClaimAccept", "summary": "Verify Order Claim", "description": "Verify the claim order token provided to the customer when they request ownership of an order.", "externalDocs": { "description": "How to implement claim-order flow in a storefront", "url": "https://docs.medusajs.com/modules/orders/storefront/implement-claim-order" }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostCustomersCustomerAcceptClaimReq" } } } }, "x-codegen": { "method": "confirmRequest" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.orders.confirmRequest(\n token,\n)\n.then(() => {\n // successful\n})\n.catch(() => {\n // an error occurred\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/orders/customer/confirm' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"token\": \"{token}\",\n}'\n" } ], "security": [ { "api_token": [] }, { "cookie_auth": [] } ], "tags": [ "Orders" ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/orders/{id}": { "get": { "operationId": "GetOrdersOrder", "summary": "Get an Order", "description": "Retrieve an Order's details.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Order.", "schema": { "type": "string" } }, { "in": "query", "name": "fields", "description": "Comma-separated fields that should be expanded in the returned order.", "schema": { "type": "string" } }, { "in": "query", "name": "expand", "description": "Comma-separated relations that should be included in the returned order.", "schema": { "type": "string" } } ], "x-codegen": { "method": "retrieve" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.orders.retrieve(orderId)\n.then(({ order }) => {\n console.log(order.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/orders/{id}'\n" } ], "tags": [ "Orders" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreOrdersRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/payment-collections/{id}": { "get": { "operationId": "GetPaymentCollectionsPaymentCollection", "summary": "Get a PaymentCollection", "description": "Retrieve a Payment Collection's details.", "x-authenticated": false, "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the PaymentCollection.", "schema": { "type": "string" } }, { "in": "query", "name": "fields", "description": "Comma-separated fields that should be expanded in the returned payment collection.", "schema": { "type": "string" } }, { "in": "query", "name": "expand", "description": "Comma-separated relations that should be expanded in the returned payment collection.", "schema": { "type": "string" } } ], "x-codegen": { "method": "retrieve", "queryParams": "StoreGetPaymentCollectionsParams" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.paymentCollections.retrieve(paymentCollectionId)\n .then(({ payment_collection }) => {\n console.log(payment_collection.id)\n })\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/payment-collections/{id}'\n" } ], "security": [ { "api_token": [] }, { "cookie_auth": [] } ], "tags": [ "Payment Collections" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePaymentCollectionsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/payment-collections/{id}/sessions": { "post": { "operationId": "PostPaymentCollectionsSessions", "summary": "Create a Payment Session", "description": "Create a Payment Session for a payment provider in a Payment Collection.", "x-authenticated": false, "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Payment Collection.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePaymentCollectionSessionsReq" } } } }, "x-codegen": { "method": "managePaymentSession" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.paymentCollections.managePaymentSession(payment_id, { provider_id: \"stripe\" })\n.then(({ payment_collection }) => {\n console.log(payment_collection.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/payment-collections/{id}/sessions' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"provider_id\": \"stripe\"\n}'\n" } ], "security": [ { "api_token": [] }, { "cookie_auth": [] } ], "tags": [ "Payment Collections" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePaymentCollectionsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/payment-collections/{id}/sessions/batch": { "post": { "operationId": "PostPaymentCollectionsPaymentCollectionSessionsBatch", "summary": "Manage Payment Sessions", "description": "Create, update, or delete a list of payment sessions of a Payment Collections. If a payment session is not provided in the `sessions` array, it's deleted.", "x-authenticated": false, "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Payment Collections.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostPaymentCollectionsBatchSessionsReq" } } } }, "x-codegen": { "method": "managePaymentSessionsBatch" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\n\n// Total amount = 10000\n\n// Example 1: Adding two new sessions\nmedusa.paymentCollections.managePaymentSessionsBatch(paymentId, {\n sessions: [\n {\n provider_id: \"stripe\",\n amount: 5000,\n },\n {\n provider_id: \"manual\",\n amount: 5000,\n },\n ]\n})\n.then(({ payment_collection }) => {\n console.log(payment_collection.id);\n});\n\n// Example 2: Updating one session and removing the other\nmedusa.paymentCollections.managePaymentSessionsBatch(paymentId, {\n sessions: [\n {\n provider_id: \"stripe\",\n amount: 10000,\n session_id: \"ps_123456\"\n },\n ]\n})\n.then(({ payment_collection }) => {\n console.log(payment_collection.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/batch' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"sessions\": [\n {\n \"provider_id\": \"stripe\",\n \"amount\": 5000\n },\n {\n \"provider_id\": \"manual\",\n \"amount\": 5000\n }\n ]\n}'\n" } ], "security": [ { "api_token": [] }, { "cookie_auth": [] } ], "tags": [ "Payment Collections" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePaymentCollectionsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/payment-collections/{id}/sessions/batch/authorize": { "post": { "operationId": "PostPaymentCollectionsSessionsBatchAuthorize", "summary": "Authorize PaymentSessions", "description": "Authorize the Payment Sessions of a Payment Collection.", "x-authenticated": false, "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Payment Collections.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostPaymentCollectionsBatchSessionsAuthorizeReq" } } } }, "x-codegen": { "method": "authorizePaymentSessionsBatch" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.paymentCollections.authorize(paymentId)\n.then(({ payment_collection }) => {\n console.log(payment_collection.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/batch/authorize'\n" } ], "security": [ { "api_token": [] }, { "cookie_auth": [] } ], "tags": [ "Payment Collections" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePaymentCollectionsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/payment-collections/{id}/sessions/{session_id}": { "post": { "operationId": "PostPaymentCollectionsPaymentCollectionPaymentSessionsSession", "summary": "Refresh a Payment Session", "description": "Refresh a Payment Session's data to ensure that it is in sync with the Payment Collection.", "x-authenticated": false, "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The id of the PaymentCollection.", "schema": { "type": "string" } }, { "in": "path", "name": "session_id", "required": true, "description": "The id of the Payment Session to be refreshed.", "schema": { "type": "string" } } ], "x-codegen": { "method": "refreshPaymentSession" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.paymentCollections.refreshPaymentSession(paymentCollectionId, sessionId)\n.then(({ payment_session }) => {\n console.log(payment_session.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/{session_id}'\n" } ], "tags": [ "Payment Collections" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePaymentCollectionsSessionRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/payment-collections/{id}/sessions/{session_id}/authorize": { "post": { "operationId": "PostPaymentCollectionsSessionsSessionAuthorize", "summary": "Authorize Payment Session", "description": "Authorize a Payment Session of a Payment Collection.", "x-authenticated": false, "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Payment Collections.", "schema": { "type": "string" } }, { "in": "path", "name": "session_id", "required": true, "description": "The ID of the Payment Session.", "schema": { "type": "string" } } ], "x-codegen": { "method": "authorizePaymentSession" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.paymentCollections.authorize(paymentId, sessionId)\n.then(({ payment_collection }) => {\n console.log(payment_collection.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/payment-collections/{id}/sessions/{session_id}/authorize'\n" } ], "security": [ { "api_token": [] }, { "cookie_auth": [] } ], "tags": [ "Payment Collections" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePaymentCollectionsSessionRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/product-categories": { "get": { "operationId": "GetProductCategories", "summary": "List Product Categories", "description": "Retrieve a list of product categories. The product categories can be filtered by fields such as `handle` or `q`. The product categories can also be paginated. This endpoint can also be used to retrieve a product category by its handle.", "x-featureFlag": "product_categories", "externalDocs": { "description": "How to retrieve a product category by its handle", "url": "https://docs.medusajs.com/modules/products/storefront/use-categories#get-a-category-by-its-handle" }, "parameters": [ { "in": "query", "name": "q", "description": "term used to search product category's names and handles.", "schema": { "type": "string" } }, { "in": "query", "name": "handle", "description": "Filter by handle.", "schema": { "type": "string" } }, { "in": "query", "name": "parent_category_id", "description": "Filter by the ID of a parent category. Only children of the provided parent category are retrieved.", "schema": { "type": "string" } }, { "in": "query", "name": "include_descendants_tree", "description": "Whether all nested categories inside a category should be retrieved.", "schema": { "type": "boolean" } }, { "in": "query", "name": "offset", "description": "The number of product categories to skip when retrieving the product categories.", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "limit", "description": "Limit the number of product categories returned.", "schema": { "type": "integer", "default": 100 } }, { "in": "query", "name": "expand", "description": "Comma-separated relations that should be expanded in the returned product categories.", "schema": { "type": "string" } }, { "in": "query", "name": "fields", "description": "Comma-separated fields that should be included in the returned product categories.", "schema": { "type": "string" } } ], "x-codegen": { "method": "list", "queryParams": "StoreGetProductCategoriesParams" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.productCategories.list()\n.then(({ product_categories, limit, offset, count }) => {\n console.log(product_categories.length);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/product-categories' \\\n-H 'Authorization: Bearer {api_token}'\n" } ], "security": [ { "api_token": [] }, { "cookie_auth": [] } ], "tags": [ "Product Categories" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreGetProductCategoriesRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/product-categories/{id}": { "get": { "operationId": "GetProductCategoriesCategory", "summary": "Get a Product Category", "description": "Retrieve a Product Category's details.", "x-featureFlag": "product_categories", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Product Category", "schema": { "type": "string" } }, { "in": "query", "name": "fields", "description": "Comma-separated fields that should be expanded in the returned product category.", "schema": { "type": "string" } }, { "in": "query", "name": "expand", "description": "Comma-separated relations that should be expanded in the returned product category.", "schema": { "type": "string" } } ], "x-codegen": { "method": "retrieve", "queryParams": "StoreGetProductCategoriesCategoryParams" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.productCategories.retrieve(productCategoryId)\n .then(({ product_category }) => {\n console.log(product_category.id);\n });\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/product-categories/{id}' \\\n-H 'Authorization: Bearer {api_token}'\n" } ], "security": [ { "api_token": [] }, { "cookie_auth": [] } ], "tags": [ "Product Categories" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreGetProductCategoriesCategoryRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/product-tags": { "get": { "operationId": "GetProductTags", "summary": "List Product Tags", "description": "Retrieve a list of product tags. The product tags can be filtered by fields such as `id` or `q`. The product tags can also be sorted or paginated.", "x-authenticated": true, "x-codegen": { "method": "list", "queryParams": "StoreGetProductTagsParams" }, "parameters": [ { "in": "query", "name": "limit", "description": "Limit the number of product tags returned.", "schema": { "type": "integer", "default": 20 } }, { "in": "query", "name": "offset", "description": "The number of product tags to skip when retrieving the product tags.", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "order", "description": "A product-tag field to sort-order the retrieved product tags by.", "schema": { "type": "string" } }, { "in": "query", "name": "discount_condition_id", "description": "Filter by the ID of a discount condition. When provided, only tags that the discount condition applies for will be retrieved.", "schema": { "type": "string" } }, { "in": "query", "name": "value", "style": "form", "explode": false, "description": "Filter by tag values.", "schema": { "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "id", "style": "form", "explode": false, "description": "Filter by IDs.", "schema": { "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "q", "description": "term to search product tag's value.", "schema": { "type": "string" } }, { "in": "query", "name": "created_at", "description": "Filter by a creation date range.", "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": "Filter by an update date range.", "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" } } } } ], "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.productTags.list()\n.then(({ product_tags }) => {\n console.log(product_tags.length);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/product-tags'\n" } ], "tags": [ "Product Tags" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreProductTagsListRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/product-types": { "get": { "operationId": "GetProductTypes", "summary": "List Product Types", "description": "Retrieve a list of product types. The product types can be filtered by fields such as `value` or `q`. The product types can also be sorted or paginated.", "x-authenticated": true, "parameters": [ { "in": "query", "name": "limit", "description": "Limit the number of product types returned.", "schema": { "type": "integer", "default": 20 } }, { "in": "query", "name": "offset", "description": "The number of product types to skip when retrieving the product types.", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "order", "description": "A product-type field to sort-order the retrieved product types by.", "schema": { "type": "string" } }, { "in": "query", "name": "discount_condition_id", "description": "Filter by the ID of a discount condition. When provided, only types that the discount condition applies for will be retrieved.", "schema": { "type": "string" } }, { "in": "query", "name": "value", "style": "form", "explode": false, "description": "Filter by type values.", "schema": { "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "id", "style": "form", "explode": false, "description": "Filter by IDs.", "schema": { "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "q", "description": "term to search product type's value.", "schema": { "type": "string" } }, { "in": "query", "name": "created_at", "description": "Filter by a creation date range.", "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": "Filter by an update date range.", "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" } } } } ], "x-codegen": { "method": "list", "queryParams": "StoreGetProductTypesParams" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\n// must be previously logged in or use api token\nmedusa.productTypes.list()\n.then(({ product_types }) => {\n console.log(product_types.length);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/product-types'\n" } ], "security": [ { "api_token": [] }, { "cookie_auth": [] } ], "tags": [ "Product Types" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreProductTypesListRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/products": { "get": { "operationId": "GetProducts", "summary": "List Products", "description": "Retrieves a list of products. The products can be filtered by fields such as `id` or `q`. The products can also be sorted or paginated.\nThis endpoint can also be used to retrieve a product by its handle.\n\nFor accurate and correct pricing of the products based on the customer's context, it's highly recommended to pass fields such as\n`region_id`, `currency_code`, and `cart_id` when available.\n\nPassing `sales_channel_id` ensures retrieving only products available in the specified sales channel.\nYou can alternatively use a publishable API key in the request header instead of passing a `sales_channel_id`.\n", "externalDocs": { "description": "How to retrieve a product by its handle", "url": "https://docs.medusajs.com/modules/products/storefront/show-products#retrieve-product-by-handle" }, "parameters": [ { "in": "query", "name": "q", "description": "term used to search products' title, description, variant's title, variant's sku, and collection's title.", "schema": { "type": "string" } }, { "in": "query", "name": "id", "style": "form", "explode": false, "description": "Filter by IDs.", "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, { "in": "query", "name": "sales_channel_id", "style": "form", "explode": false, "description": "Filter by sales channel IDs. When provided, only products available in the selected sales channels are retrieved. Alternatively, you can pass a publishable API key in the request header and this will have the same effect.", "schema": { "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "collection_id", "style": "form", "explode": false, "description": "Filter by product collection IDs. When provided, only products that belong to the specified product collections are retrieved.", "schema": { "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "type_id", "style": "form", "explode": false, "description": "Filter by product type IDs. When provided, only products that belong to the specified product types are retrieved.", "schema": { "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "tags", "style": "form", "explode": false, "description": "Filter by product tag IDs. When provided, only products that belong to the specified product tags are retrieved.", "schema": { "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "title", "description": "Filter by title.", "schema": { "type": "string" } }, { "in": "query", "name": "description", "description": "Filter by description", "schema": { "type": "string" } }, { "in": "query", "name": "handle", "description": "Filter by handle.", "schema": { "type": "string" } }, { "in": "query", "name": "is_giftcard", "description": "Whether to retrieve regular products or gift-card products.", "schema": { "type": "boolean" } }, { "in": "query", "name": "created_at", "description": "Filter by a creation date range.", "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": "Filter by an update date range.", "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": "category_id", "style": "form", "explode": false, "description": "Filter by product category IDs. When provided, only products that belong to the specified product categories are retrieved.", "schema": { "type": "array", "x-featureFlag": "product_categories", "items": { "type": "string" } } }, { "in": "query", "name": "include_category_children", "style": "form", "explode": false, "description": "Whether to include child product categories when filtering using the `category_id` field.", "schema": { "type": "boolean", "x-featureFlag": "product_categories" } }, { "in": "query", "name": "offset", "description": "The number of products to skip when retrieving the products.", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "limit", "description": "Limit the number of products returned.", "schema": { "type": "integer", "default": 100 } }, { "in": "query", "name": "expand", "description": "Comma-separated relations that should be expanded in the returned products.", "schema": { "type": "string" } }, { "in": "query", "name": "fields", "description": "Comma-separated fields that should be included in the returned products.", "schema": { "type": "string" } }, { "in": "query", "name": "order", "description": "A product field to sort-order the retrieved products by.", "schema": { "type": "string" } }, { "in": "query", "name": "cart_id", "description": "The ID of the cart. This is useful for accurate pricing based on the cart's context.", "schema": { "type": "string" } }, { "in": "query", "name": "region_id", "description": "The ID of the region. This is useful for accurate pricing based on the selected region.", "schema": { "type": "string" } }, { "in": "query", "name": "currency_code", "style": "form", "explode": false, "description": "A 3 character ISO currency code. This is useful for accurate pricing based on the selected currency.", "schema": { "type": "string", "externalDocs": { "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes", "description": "See a list of codes." } } } ], "x-codegen": { "method": "list", "queryParams": "StoreGetProductsParams" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.products.list()\n.then(({ products, limit, offset, count }) => {\n console.log(products.length);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/products'\n" } ], "tags": [ "Products" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreProductsListRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/products/search": { "post": { "operationId": "PostProductsSearch", "summary": "Search Products", "description": "Run a search query on products using the search service installed on the Medusa backend. The searching is handled through the search service, so the returned data's format depends on the search service you're using.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostSearchReq" } } } }, "x-codegen": { "method": "search" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.products.search({\n q: \"Shirt\"\n})\n.then(({ hits }) => {\n console.log(hits.length);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/products/search' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"q\": \"Shirt\"\n}'\n" } ], "tags": [ "Products" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostSearchRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/products/{id}": { "get": { "operationId": "GetProductsProduct", "summary": "Get a Product", "description": "Retrieve a Product's details. For accurate and correct pricing of the product based on the customer's context, it's highly recommended to pass fields such as\n`region_id`, `currency_code`, and `cart_id` when available.\n\nPassing `sales_channel_id` ensures retrieving only products available in the current sales channel.\nYou can alternatively use a publishable API key in the request header instead of passing a `sales_channel_id`.\n", "externalDocs": { "description": "How to pass product pricing parameters", "url": "https://docs.medusajs.com/modules/products/storefront/show-products#product-pricing-parameters" }, "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Product.", "schema": { "type": "string" } }, { "in": "query", "name": "sales_channel_id", "description": "The ID of the sales channel the customer is viewing the product from.", "schema": { "type": "string" } }, { "in": "query", "name": "cart_id", "description": "The ID of the cart. This is useful for accurate pricing based on the cart's context.", "schema": { "type": "string" } }, { "in": "query", "name": "region_id", "description": "The ID of the region. This is useful for accurate pricing based on the selected region.", "schema": { "type": "string" } }, { "in": "query", "name": "expand", "description": "Comma-separated relations that should be expanded in the returned product.", "schema": { "type": "string" } }, { "in": "query", "name": "fields", "description": "Comma-separated fields that should be included in the returned product.", "schema": { "type": "string" } }, { "in": "query", "name": "currency_code", "style": "form", "explode": false, "description": "A 3 character ISO currency code. This is useful for accurate pricing based on the selected currency.", "schema": { "type": "string", "externalDocs": { "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes", "description": "See a list of codes." } } } ], "x-codegen": { "method": "retrieve", "queryParams": "StoreGetProductsProductParams" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.products.retrieve(productId)\n.then(({ product }) => {\n console.log(product.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/products/{id}'\n" } ], "tags": [ "Products" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreProductsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/regions": { "get": { "operationId": "GetRegions", "summary": "List Regions", "description": "Retrieve a list of regions. The regions can be filtered by fields such as `created_at`. The regions can also be paginated. This endpoint is useful to show the customer all available regions to choose from.", "externalDocs": { "description": "How to use regions in a storefront", "url": "https://docs.medusajs.com/modules/regions-and-currencies/storefront/use-regions" }, "parameters": [ { "in": "query", "name": "offset", "description": "The number of regions to skip when retrieving the regions.", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "limit", "description": "Limit the number of regions returned.", "schema": { "type": "integer", "default": 100 } }, { "in": "query", "name": "created_at", "description": "Filter by a creation date range.", "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": "Filter by an update date range.", "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" } } } } ], "x-codegen": { "method": "list", "queryParams": "StoreGetRegionsParams" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.regions.list()\n.then(({ regions }) => {\n console.log(regions.length);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/regions'\n" } ], "tags": [ "Regions" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreRegionsListRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/regions/{id}": { "get": { "operationId": "GetRegionsRegion", "summary": "Get a Region", "description": "Retrieve a Region's details.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Region.", "schema": { "type": "string" } } ], "x-codegen": { "method": "retrieve" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.regions.retrieve(regionId)\n.then(({ region }) => {\n console.log(region.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/regions/{id}'\n" } ], "tags": [ "Regions" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreRegionsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/return-reasons": { "get": { "operationId": "GetReturnReasons", "summary": "List Return Reasons", "description": "Retrieve a list of Return Reasons. This is useful when implementing a Create Return flow in the storefront.", "x-codegen": { "method": "list" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.returnReasons.list()\n.then(({ return_reasons }) => {\n console.log(return_reasons.length);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/return-reasons'\n" } ], "tags": [ "Return Reasons" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreReturnReasonsListRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/return-reasons/{id}": { "get": { "operationId": "GetReturnReasonsReason", "summary": "Get a Return Reason", "description": "Retrieve a Return Reason's details.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The id of the Return Reason.", "schema": { "type": "string" } } ], "x-codegen": { "method": "retrieve" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.returnReasons.retrieve(reasonId)\n.then(({ return_reason }) => {\n console.log(return_reason.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/return-reasons/{id}'\n" } ], "tags": [ "Return Reasons" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreReturnReasonsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/returns": { "post": { "operationId": "PostReturns", "summary": "Create Return", "description": "Create a Return for an Order. If a return shipping method is specified, the return is automatically fulfilled.", "externalDocs": { "description": "How to create a return in a storefront", "url": "https://docs.medusajs.com/modules/orders/storefront/create-return" }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostReturnsReq" } } } }, "x-codegen": { "method": "create" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.returns.create({\n order_id,\n items: [\n {\n item_id,\n quantity: 1\n }\n ]\n})\n.then((data) => {\n console.log(data.return.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/returns' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"order_id\": \"asfasf\",\n \"items\": [\n {\n \"item_id\": \"assfasf\",\n \"quantity\": 1\n }\n ]\n}'\n" } ], "tags": [ "Returns" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreReturnsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/shipping-options": { "get": { "operationId": "GetShippingOptions", "summary": "Get Shipping Options", "description": "Retrieve a list of Shipping Options.", "parameters": [ { "in": "query", "name": "is_return", "description": "Whether return shipping options should be included. By default, all shipping options are returned.", "schema": { "type": "boolean" } }, { "in": "query", "name": "product_ids", "description": "\"Comma-separated list of Product IDs to filter Shipping Options by. If provided, only shipping options that can be used with the provided products are retrieved.\"", "schema": { "type": "string" } }, { "in": "query", "name": "region_id", "description": "\"The ID of the region that the shipping options belong to. If not provided, all shipping options are retrieved.\"", "schema": { "type": "string" } } ], "x-codegen": { "method": "list", "queryParams": "StoreGetShippingOptionsParams" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.shippingOptions.list()\n.then(({ shipping_options }) => {\n console.log(shipping_options.length);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/shipping-options'\n" } ], "tags": [ "Shipping Options" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreShippingOptionsListRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/shipping-options/{cart_id}": { "get": { "operationId": "GetShippingOptionsCartId", "summary": "List for Cart", "description": "Retrieve a list of Shipping Options available for a cart.", "externalDocs": { "description": "How to implement shipping step in checkout", "url": "https://docs.medusajs.com/modules/carts-and-checkout/storefront/implement-checkout-flow#shipping-step" }, "parameters": [ { "in": "path", "name": "cart_id", "required": true, "description": "The ID of the Cart.", "schema": { "type": "string" } } ], "x-codegen": { "method": "listCartOptions" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.shippingOptions.listCartOptions(cartId)\n.then(({ shipping_options }) => {\n console.log(shipping_options.length);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/shipping-options/{cart_id}'\n" } ], "tags": [ "Shipping Options" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCartShippingOptionsListRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/swaps": { "post": { "operationId": "PostSwaps", "summary": "Create a Swap", "description": "Create a Swap for an Order. This will also create a return and associate it with the swap. If a return shipping option is specified, the return will automatically be fulfilled.\nTo complete the swap, you must use the Complete Cart endpoint passing it the ID of the swap's cart.\n\nAn idempotency key will be generated if none is provided in the header `Idempotency-Key` and added to\nthe response. If an error occurs during swap creation or the request is interrupted for any reason, the swap creation can be retried by passing the idempotency\nkey in the `Idempotency-Key` header.\n", "externalDocs": { "description": "How to create a swap", "url": "https://docs.medusajs.com/modules/orders/storefront/create-swap" }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePostSwapsReq" } } } }, "x-codegen": { "method": "create" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.swaps.create({\n order_id,\n return_items: [\n {\n item_id,\n quantity: 1\n }\n ],\n additional_items: [\n {\n variant_id,\n quantity: 1\n }\n ]\n})\n.then(({ swap }) => {\n console.log(swap.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://medusa-url.com/store/swaps' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"order_id\": \"{order_id}\",\n \"return_items\": [\n {\n \"item_id\": \"{item_id}\",\n \"quantity\": 1\n }\n ],\n \"additional_items\": [\n {\n \"variant_id\": \"{variant_id}\",\n \"quantity\": 1\n }\n ]\n}'\n" } ], "tags": [ "Swaps" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreSwapsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/swaps/{cart_id}": { "get": { "operationId": "GetSwapsSwapCartId", "summary": "Get by Cart ID", "description": "Retrieve a Swap's details by the ID of its cart.", "parameters": [ { "in": "path", "name": "cart_id", "required": true, "description": "The id of the Cart", "schema": { "type": "string" } } ], "x-codegen": { "method": "retrieveByCartId" }, "x-codeSamples": [ { "lang": "JavaScript", "label": "JS Client", "source": "import Medusa from \"@medusajs/medusa-js\"\nconst medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })\nmedusa.swaps.retrieveByCartId(cartId)\n.then(({ swap }) => {\n console.log(swap.id);\n});\n" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/swaps/{cart_id}'\n" } ], "tags": [ "Swaps" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreSwapsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/variants": { "get": { "operationId": "GetVariants", "summary": "Get Product Variants", "description": "Retrieves a list of product variants. The product variants can be filtered by fields such as `id` or `title`. The product variants can also be paginated.\n\nFor accurate and correct pricing of the product variants based on the customer's context, it's highly recommended to pass fields such as\n`region_id`, `currency_code`, and `cart_id` when available.\n\nPassing `sales_channel_id` ensures retrieving only variants of products available in the specified sales channel.\nYou can alternatively use a publishable API key in the request header instead of passing a `sales_channel_id`.\n", "externalDocs": { "description": "How to pass product pricing parameters", "url": "https://docs.medusajs.com/modules/products/storefront/show-products#product-pricing-parameters" }, "parameters": [ { "in": "query", "name": "ids", "description": "Filter by a comma-separated list of IDs. If supplied, it overrides the `id` parameter.", "schema": { "type": "string" } }, { "in": "query", "name": "id", "style": "form", "explode": false, "description": "Filter by one or more IDs. If `ids` is supplied, it's overrides the value of this parameter.", "schema": { "oneOf": [ { "type": "string", "description": "Filter by an ID." }, { "type": "array", "description": "Filter by IDs.", "items": { "type": "string" } } ] } }, { "in": "query", "name": "sales_channel_id", "description": "\"Filter by sales channel IDs. When provided, only products available in the selected sales channels are retrieved. Alternatively, you can pass a publishable API key in the request header and this will have the same effect.\"", "schema": { "type": "string" } }, { "in": "query", "name": "expand", "description": "Comma-separated relations that should be expanded in the returned product variants.", "schema": { "type": "string" } }, { "in": "query", "name": "fields", "description": "Comma-separated fields that should be included in the returned product variants.", "schema": { "type": "string" } }, { "in": "query", "name": "offset", "description": "The number of products to skip when retrieving the product variants.", "schema": { "type": "number", "default": "0" } }, { "in": "query", "name": "limit", "description": "Limit the number of product variants returned.", "schema": { "type": "number", "default": "100" } }, { "in": "query", "name": "cart_id", "description": "The ID of the cart. This is useful for accurate pricing based on the cart's context.", "schema": { "type": "string" } }, { "in": "query", "name": "region_id", "description": "The ID of the region. This is useful for accurate pricing based on the selected region.", "schema": { "type": "string" } }, { "in": "query", "name": "currency_code", "style": "form", "explode": false, "description": "A 3 character ISO currency code. This is useful for accurate pricing based on the selected currency.", "schema": { "type": "string", "externalDocs": { "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes", "description": "See a list of codes." } } }, { "in": "query", "name": "title", "style": "form", "explode": false, "description": "Filter by title", "schema": { "oneOf": [ { "type": "string", "description": "a single title to filter by" }, { "type": "array", "description": "multiple titles to filter by", "items": { "type": "string" } } ] } }, { "in": "query", "name": "inventory_quantity", "description": "Filter by available inventory quantity", "schema": { "oneOf": [ { "type": "number", "description": "A specific number to filter by." }, { "type": "object", "description": "Filter using less and greater than comparisons.", "properties": { "lt": { "type": "number", "description": "Filter by inventory quantity less than this number" }, "gt": { "type": "number", "description": "Filter by inventory quantity greater than this number" }, "lte": { "type": "number", "description": "Filter by inventory quantity less than or equal to this number" }, "gte": { "type": "number", "description": "Filter by inventory quantity greater than or equal to this number" } } } ] } } ], "x-codegen": { "method": "list", "queryParams": "StoreGetVariantsParams" }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/variants'\n" } ], "tags": [ "Product Variants" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreVariantsListRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } }, "/store/variants/{id}": { "get": { "operationId": "GetVariantsVariant", "summary": "Get a Product Variant", "description": "Retrieve a Product Variant's details. For accurate and correct pricing of the product variant based on the customer's context, it's highly recommended to pass fields such as\n`region_id`, `currency_code`, and `cart_id` when available.\n\nPassing `sales_channel_id` ensures retrieving only variants of products available in the current sales channel.\nYou can alternatively use a publishable API key in the request header instead of passing a `sales_channel_id`.\n", "externalDocs": { "description": "How to pass product pricing parameters", "url": "https://docs.medusajs.com/modules/products/storefront/show-products#product-pricing-parameters" }, "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The ID of the Product Variant.", "schema": { "type": "string" } }, { "in": "query", "name": "sales_channel_id", "description": "The ID of the sales channel the customer is viewing the product variant from.", "schema": { "type": "string" } }, { "in": "query", "name": "cart_id", "description": "The ID of the cart. This is useful for accurate pricing based on the cart's context.", "schema": { "type": "string" } }, { "in": "query", "name": "region_id", "description": "The ID of the region. This is useful for accurate pricing based on the selected region.", "schema": { "type": "string" } }, { "in": "query", "name": "currency_code", "style": "form", "explode": false, "description": "A 3 character ISO currency code. This is useful for accurate pricing based on the selected currency.", "schema": { "type": "string", "externalDocs": { "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes", "description": "See a list of codes." } } } ], "x-codegen": { "method": "retrieve", "queryParams": "StoreGetVariantsVariantParams" }, "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl 'https://medusa-url.com/store/variants/{id}'\n" } ], "tags": [ "Product Variants" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreVariantsRes" } } } }, "400": { "$ref": "#/components/responses/400_error" }, "404": { "$ref": "#/components/responses/not_found_error" }, "409": { "$ref": "#/components/responses/invalid_state_error" }, "422": { "$ref": "#/components/responses/invalid_request_error" }, "500": { "$ref": "#/components/responses/500_error" } } } } }, "components": { "responses": { "default_error": { "description": "Default Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "unknown_error", "message": "An unknown error occurred.", "type": "unknown_error" } } } }, "invalid_state_error": { "description": "Invalid State Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "unknown_error", "message": "The request conflicted with another request. You may retry the request with the provided Idempotency-Key.", "type": "QueryRunnerAlreadyReleasedError" } } } }, "invalid_request_error": { "description": "Invalid Request Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "invalid_request_error", "message": "Discount with code TEST already exists.", "type": "duplicate_error" } } } }, "not_found_error": { "description": "Not Found Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Entity with id 1 was not found", "type": "not_found" } } } }, "400_error": { "description": "Client Error or Multiple Errors", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/MultipleErrors" } ] }, "examples": { "not_allowed": { "$ref": "#/components/examples/not_allowed_error" }, "invalid_data": { "$ref": "#/components/examples/invalid_data_error" }, "MultipleErrors": { "$ref": "#/components/examples/multiple_errors" } } } } }, "500_error": { "description": "Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "database": { "$ref": "#/components/examples/database_error" }, "unexpected_state": { "$ref": "#/components/examples/unexpected_state_error" }, "invalid_argument": { "$ref": "#/components/examples/invalid_argument_error" }, "default_error": { "$ref": "#/components/examples/default_error" } } } } }, "unauthorized": { "description": "User is not authorized. Must log in first", "content": { "text/plain": { "schema": { "type": "string", "default": "Unauthorized", "example": "Unauthorized" } } } }, "incorrect_credentials": { "description": "User does not exist or incorrect credentials", "content": { "text/plain": { "schema": { "type": "string", "default": "Unauthorized", "example": "Unauthorized" } } } } }, "examples": { "not_allowed_error": { "summary": "Not Allowed Error", "value": { "message": "Discount must be set to dynamic", "type": "not_allowed" } }, "invalid_data_error": { "summary": "Invalid Data Error", "value": { "message": "first_name must be a string", "type": "invalid_data" } }, "multiple_errors": { "summary": "Multiple Errors", "value": { "message": "Provided request body contains errors. Please check the data and retry the request", "errors": [ { "message": "first_name must be a string", "type": "invalid_data" }, { "message": "Discount must be set to dynamic", "type": "not_allowed" } ] } }, "database_error": { "summary": "Database Error", "value": { "code": "api_error", "message": "An error occured while hashing password", "type": "database_error" } }, "unexpected_state_error": { "summary": "Unexpected State Error", "value": { "message": "cart.total must be defined", "type": "unexpected_state" } }, "invalid_argument_error": { "summary": "Invalid Argument Error", "value": { "message": "cart.total must be defined", "type": "unexpected_state" } }, "default_error": { "summary": "Default Error", "value": { "code": "unknown_error", "message": "An unknown error occurred.", "type": "unknown_error" } } }, "securitySchemes": { "cookie_auth": { "type": "apiKey", "x-displayName": "Cookie Session ID", "in": "cookie", "name": "connect.sid", "description": "Use a cookie session to send authenticated requests.\n\n### How to Obtain the Cookie Session\n\nIf you're sending requests through a browser, using JS Client, or using tools like Postman, the cookie session should be automatically set when the customer is logged in.\n\nIf you're sending requests using cURL, you must set the Session ID in the cookie manually.\n\nTo do that, send a request to [authenticate the customer](#tag/Auth/operation/PostAuth) and pass the cURL option `-v`:\n\n```bash\ncurl -v --location --request POST 'https://medusa-url.com/store/auth' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"email\": \"user@example.com\",\n \"password\": \"supersecret\"\n}'\n```\n\nThe headers will be logged in the terminal as well as the response. You should find in the headers a Cookie header similar to this:\n\n```bash\nSet-Cookie: connect.sid=s%3A2Bu8BkaP9JUfHu9rG59G16Ma0QZf6Gj1.WT549XqX37PN8n0OecqnMCq798eLjZC5IT7yiDCBHPM;\n```\n\nCopy the value after `connect.sid` (without the `;` at the end) and pass it as a cookie in subsequent requests as the following:\n\n```bash\ncurl --location --request GET 'https://medusa-url.com/store/customers/me/orders' \\\n--header 'Cookie: connect.sid={sid}'\n```\n\nWhere `{sid}` is the value of `connect.sid` that you copied.\n" } }, "schemas": { "Address": { "title": "Address", "description": "An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.", "type": "object", "required": [ "address_1", "address_2", "city", "company", "country_code", "created_at", "customer_id", "deleted_at", "first_name", "id", "last_name", "metadata", "phone", "postal_code", "province", "updated_at" ], "properties": { "id": { "type": "string", "description": "ID of the address", "example": "addr_01G8ZC9VS1XVE149MGH2J7QSSH" }, "customer_id": { "description": "ID of the customer this address belongs to", "nullable": true, "type": "string", "example": "cus_01G2SG30J8C85S4A5CHM2S1NS2" }, "customer": { "description": "Available if the relation `customer` is expanded.", "nullable": true, "$ref": "#/components/schemas/Customer" }, "company": { "description": "Company name", "nullable": true, "type": "string", "example": "Acme" }, "first_name": { "description": "First name", "nullable": true, "type": "string", "example": "Arno" }, "last_name": { "description": "Last name", "nullable": true, "type": "string", "example": "Willms" }, "address_1": { "description": "Address line 1", "nullable": true, "type": "string", "example": "14433 Kemmer Court" }, "address_2": { "description": "Address line 2", "nullable": true, "type": "string", "example": "Suite 369" }, "city": { "description": "City", "nullable": true, "type": "string", "example": "South Geoffreyview" }, "country_code": { "description": "The 2 character ISO code of the country in lower case", "nullable": true, "type": "string", "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.", "x-expandable": "country", "nullable": true, "$ref": "#/components/schemas/Country" }, "province": { "description": "Province", "nullable": true, "type": "string", "example": "Kentucky" }, "postal_code": { "description": "Postal Code", "nullable": true, "type": "string", "example": 72093 }, "phone": { "description": "Phone Number", "nullable": true, "type": "string", "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": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "AddressCreatePayload": { "type": "object", "description": "Address fields used when creating an address.", "required": [ "first_name", "last_name", "address_1", "city", "country_code", "postal_code" ], "properties": { "first_name": { "description": "First name", "type": "string", "example": "Arno" }, "last_name": { "description": "Last name", "type": "string", "example": "Willms" }, "phone": { "type": "string", "description": "Phone Number", "example": 16128234334802 }, "company": { "type": "string" }, "address_1": { "description": "Address line 1", "type": "string", "example": "14433 Kemmer Court" }, "address_2": { "description": "Address line 2", "type": "string", "example": "Suite 369" }, "city": { "description": "City", "type": "string", "example": "South Geoffreyview" }, "country_code": { "description": "The 2 character ISO code of the country in lower case", "type": "string", "externalDocs": { "url": "https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements", "description": "See a list of codes." }, "example": "st" }, "province": { "description": "Province", "type": "string", "example": "Kentucky" }, "postal_code": { "description": "Postal Code", "type": "string", "example": 72093 }, "metadata": { "type": "object", "example": { "car": "white" }, "description": "An optional key-value map with additional details" } } }, "AddressPayload": { "type": "object", "description": "Address fields used when creating/updating an address.", "properties": { "first_name": { "description": "First name", "type": "string", "example": "Arno" }, "last_name": { "description": "Last name", "type": "string", "example": "Willms" }, "phone": { "type": "string", "description": "Phone Number", "example": 16128234334802 }, "company": { "type": "string" }, "address_1": { "description": "Address line 1", "type": "string", "example": "14433 Kemmer Court" }, "address_2": { "description": "Address line 2", "type": "string", "example": "Suite 369" }, "city": { "description": "City", "type": "string", "example": "South Geoffreyview" }, "country_code": { "description": "The 2 character ISO code of the country in lower case", "type": "string", "externalDocs": { "url": "https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements", "description": "See a list of codes." }, "example": "st" }, "province": { "description": "Province", "type": "string", "example": "Kentucky" }, "postal_code": { "description": "Postal Code", "type": "string", "example": 72093 }, "metadata": { "type": "object", "example": { "car": "white" }, "description": "An optional key-value map with additional details" } } }, "BatchJob": { "title": "Batch Job", "description": "A Batch Job indicates an asynchronus task stored in the Medusa backend. Its status determines whether it has been executed or not.", "type": "object", "required": [ "canceled_at", "completed_at", "confirmed_at", "context", "created_at", "created_by", "deleted_at", "dry_run", "failed_at", "id", "pre_processed_at", "processing_at", "result", "status", "type", "updated_at" ], "properties": { "id": { "description": "The unique identifier for the batch job.", "type": "string", "example": "batch_01G8T782965PYFG0751G0Z38B4" }, "type": { "description": "The type of batch job.", "type": "string", "enum": [ "product-import", "product-export" ] }, "status": { "description": "The status of the batch job.", "type": "string", "enum": [ "created", "pre_processed", "confirmed", "processing", "completed", "canceled", "failed" ], "default": "created" }, "created_by": { "description": "The unique identifier of the user that created the batch job.", "nullable": true, "type": "string", "example": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V" }, "created_by_user": { "description": "The details of the user that created the batch job.", "x-expandable": "created_by_user", "nullable": true, "$ref": "#/components/schemas/User" }, "context": { "description": "The context of the batch job, the type of the batch job determines what the context should contain.", "nullable": true, "type": "object", "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": { "description": "Specify if the job must apply the modifications or not.", "type": "boolean", "default": false }, "result": { "description": "The result of the batch job.", "nullable": true, "allOf": [ { "type": "object", "example": {} }, { "type": "object", "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": { "description": "The date from which the job has been pre-processed.", "nullable": true, "type": "string", "format": "date-time" }, "processing_at": { "description": "The date the job is processing at.", "nullable": true, "type": "string", "format": "date-time" }, "confirmed_at": { "description": "The date when the confirmation has been done.", "nullable": true, "type": "string", "format": "date-time" }, "completed_at": { "description": "The date of the completion.", "nullable": true, "type": "string", "format": "date-time" }, "canceled_at": { "description": "The date of the concellation.", "nullable": true, "type": "string", "format": "date-time" }, "failed_at": { "description": "The date when the job failed.", "nullable": true, "type": "string", "format": "date-time" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was last updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" } } }, "Cart": { "title": "Cart", "description": "A cart represents a virtual shopping bag. It can be used to complete an order, a swap, or a claim.", "type": "object", "required": [ "billing_address_id", "completed_at", "context", "created_at", "customer_id", "deleted_at", "email", "id", "idempotency_key", "metadata", "payment_authorized_at", "payment_id", "payment_session", "region_id", "shipping_address_id", "type", "updated_at" ], "properties": { "id": { "description": "The cart's ID", "type": "string", "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63" }, "email": { "description": "The email associated with the cart", "nullable": true, "type": "string", "format": "email" }, "billing_address_id": { "description": "The billing address's ID", "nullable": true, "type": "string", "example": "addr_01G8ZH853YPY9B94857DY91YGW" }, "billing_address": { "description": "The details of the billing address associated with the cart.", "x-expandable": "billing_address", "nullable": true, "$ref": "#/components/schemas/Address" }, "shipping_address_id": { "description": "The shipping address's ID", "nullable": true, "type": "string", "example": "addr_01G8ZH853YPY9B94857DY91YGW" }, "shipping_address": { "description": "The details of the shipping address associated with the cart.", "x-expandable": "shipping_address", "nullable": true, "$ref": "#/components/schemas/Address" }, "items": { "description": "The line items added to the cart.", "type": "array", "x-expandable": "items", "items": { "$ref": "#/components/schemas/LineItem" } }, "region_id": { "description": "The region's ID", "type": "string", "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" }, "region": { "description": "The details of the region associated with the cart.", "x-expandable": "region", "nullable": true, "$ref": "#/components/schemas/Region" }, "discounts": { "description": "An array of details of all discounts applied to the cart.", "type": "array", "x-expandable": "discounts", "items": { "$ref": "#/components/schemas/Discount" } }, "gift_cards": { "description": "An array of details of all gift cards applied to the cart.", "type": "array", "x-expandable": "gift_cards", "items": { "$ref": "#/components/schemas/GiftCard" } }, "customer_id": { "description": "The customer's ID", "nullable": true, "type": "string", "example": "cus_01G2SG30J8C85S4A5CHM2S1NS2" }, "customer": { "description": "The details of the customer the cart belongs to.", "x-expandable": "customer", "nullable": true, "$ref": "#/components/schemas/Customer" }, "payment_session": { "description": "The details of the selected payment session in the cart.", "x-expandable": "payment_session", "nullable": true, "$ref": "#/components/schemas/PaymentSession" }, "payment_sessions": { "description": "The details of all payment sessions created on the cart.", "type": "array", "x-expandable": "payment_sessions", "items": { "$ref": "#/components/schemas/PaymentSession" } }, "payment_id": { "description": "The payment's ID if available", "nullable": true, "type": "string", "example": "pay_01G8ZCC5W42ZNY842124G7P5R9" }, "payment": { "description": "The details of the payment associated with the cart.", "nullable": true, "x-expandable": "payment", "$ref": "#/components/schemas/Payment" }, "shipping_methods": { "description": "The details of the shipping methods added to the cart.", "type": "array", "x-expandable": "shipping_methods", "items": { "$ref": "#/components/schemas/ShippingMethod" } }, "type": { "description": "The cart's type.", "type": "string", "enum": [ "default", "swap", "draft_order", "payment_link", "claim" ], "default": "default" }, "completed_at": { "description": "The date with timezone at which the cart was completed.", "nullable": true, "type": "string", "format": "date-time" }, "payment_authorized_at": { "description": "The date with timezone at which the payment was authorized.", "nullable": true, "type": "string", "format": "date-time" }, "idempotency_key": { "description": "Randomly generated key used to continue the completion of a cart in case of failure.", "nullable": true, "type": "string", "externalDocs": { "url": "https://docs.medusajs.com/development/idempotency-key/overview.md", "description": "Learn more how to use the idempotency key." } }, "context": { "description": "The context of the cart which can include info like IP or user agent.", "nullable": true, "type": "object", "example": { "ip": "::1", "user_agent": "PostmanRuntime/7.29.2" } }, "sales_channel_id": { "description": "The sales channel ID the cart is associated with.", "nullable": true, "type": "string", "example": null }, "sales_channel": { "description": "The details of the sales channel associated with the cart.", "nullable": true, "x-expandable": "sales_channel", "$ref": "#/components/schemas/SalesChannel" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } }, "shipping_total": { "description": "The total of shipping", "type": "integer", "example": 1000 }, "discount_total": { "description": "The total of discount rounded", "type": "integer", "example": 800 }, "raw_discount_total": { "description": "The total of discount", "type": "integer", "example": 800 }, "item_tax_total": { "description": "The total of items with taxes", "type": "integer", "example": 8000 }, "shipping_tax_total": { "description": "The total of shipping with taxes", "type": "integer", "example": 1000 }, "tax_total": { "description": "The total of tax", "type": "integer", "example": 0 }, "refunded_total": { "description": "The total amount refunded if the order associated with this cart is returned.", "type": "integer", "example": 0 }, "total": { "description": "The total amount of the cart", "type": "integer", "example": 8200 }, "subtotal": { "description": "The subtotal of the cart", "type": "integer", "example": 8000 }, "refundable_amount": { "description": "The amount that can be refunded", "type": "integer", "example": 8200 }, "gift_card_total": { "description": "The total of gift cards", "type": "integer", "example": 0 }, "gift_card_tax_total": { "description": "The total of gift cards with taxes", "type": "integer", "example": 0 } } }, "ClaimImage": { "title": "Claim Image", "description": "The details of an image attached to a claim.", "type": "object", "required": [ "claim_item_id", "created_at", "deleted_at", "id", "metadata", "updated_at", "url" ], "properties": { "id": { "description": "The claim image's ID", "type": "string", "example": "cimg_01G8ZH853Y6TFXWPG5EYE81X63" }, "claim_item_id": { "description": "The ID of the claim item associated with the image", "type": "string" }, "claim_item": { "description": "The details of the claim item this image is associated with.", "nullable": true, "x-expandable": "claim_item", "$ref": "#/components/schemas/ClaimItem" }, "url": { "description": "The URL of the image", "type": "string", "format": "uri" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "ClaimItem": { "title": "Claim Item", "description": "A claim item is an item created as part of a claim. It references an item in the order that should be exchanged or refunded.", "type": "object", "required": [ "claim_order_id", "created_at", "deleted_at", "id", "item_id", "metadata", "note", "quantity", "reason", "updated_at", "variant_id" ], "properties": { "id": { "description": "The claim item's ID", "type": "string", "example": "citm_01G8ZH853Y6TFXWPG5EYE81X63" }, "images": { "description": "The claim images that are attached to the claim item.", "type": "array", "x-expandable": "images", "items": { "$ref": "#/components/schemas/ClaimImage" } }, "claim_order_id": { "description": "The ID of the claim this item is associated with.", "type": "string" }, "claim_order": { "description": "The details of the claim this item belongs to.", "x-expandable": "claim_order", "nullable": true, "$ref": "#/components/schemas/ClaimOrder" }, "item_id": { "description": "The ID of the line item that the claim item refers to.", "type": "string", "example": "item_01G8ZM25TN49YV9EQBE2NC27KC" }, "item": { "description": "The details of the line item in the original order that this claim item refers to.", "x-expandable": "item", "nullable": true, "$ref": "#/components/schemas/LineItem" }, "variant_id": { "description": "The ID of the product variant that is claimed.", "type": "string", "example": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6" }, "variant": { "description": "The details of the product variant to potentially replace the item in the original order.", "x-expandable": "variant", "nullable": true, "$ref": "#/components/schemas/ProductVariant" }, "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", "nullable": true, "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.", "type": "array", "x-expandable": "tags", "items": { "$ref": "#/components/schemas/ClaimTag" } }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "ClaimOrder": { "title": "Claim", "description": "A Claim represents a group of faulty or missing items. It consists of claim items that refer to items in the original order that should be replaced or refunded. It also includes details related to shipping and fulfillment.", "type": "object", "required": [ "canceled_at", "created_at", "deleted_at", "fulfillment_status", "id", "idempotency_key", "metadata", "no_notification", "order_id", "payment_status", "refund_amount", "shipping_address_id", "type", "updated_at" ], "properties": { "id": { "description": "The claim's ID", "type": "string", "example": "claim_01G8ZH853Y6TFXWPG5EYE81X63" }, "type": { "description": "The claim's type", "type": "string", "enum": [ "refund", "replace" ] }, "payment_status": { "description": "The status of the claim's payment", "type": "string", "enum": [ "na", "not_refunded", "refunded" ], "default": "na" }, "fulfillment_status": { "description": "The claim's 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 details of the items that should be replaced or refunded.", "type": "array", "x-expandable": "claim_items", "items": { "$ref": "#/components/schemas/ClaimItem" } }, "additional_items": { "description": "The details of the new items to be shipped when the claim's type is `replace`", "type": "array", "x-expandable": "additional_items", "items": { "$ref": "#/components/schemas/LineItem" } }, "order_id": { "description": "The ID of the order that the claim comes from.", "type": "string", "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK" }, "order": { "description": "The details of the order that this claim was created for.", "x-expandable": "order", "nullable": true, "$ref": "#/components/schemas/Order" }, "return_order": { "description": "The details of the return associated with the claim if the claim's type is `replace`.", "x-expandable": "return_order", "nullable": true, "$ref": "#/components/schemas/Return" }, "shipping_address_id": { "description": "The ID of the address that the new items should be shipped to", "nullable": true, "type": "string", "example": "addr_01G8ZH853YPY9B94857DY91YGW" }, "shipping_address": { "description": "The details of the address that new items should be shipped to.", "x-expandable": "shipping_address", "nullable": true, "$ref": "#/components/schemas/Address" }, "shipping_methods": { "description": "The details of the shipping methods that the claim order will be shipped with.", "type": "array", "x-expandable": "shipping_methods", "items": { "$ref": "#/components/schemas/ShippingMethod" } }, "fulfillments": { "description": "The fulfillments of the new items to be shipped", "type": "array", "x-expandable": "fulfillments", "items": { "$ref": "#/components/schemas/Fulfillment" } }, "refund_amount": { "description": "The amount that will be refunded in conjunction with the claim", "nullable": true, "type": "integer", "example": 1000 }, "canceled_at": { "description": "The date with timezone at which the claim was canceled.", "nullable": true, "type": "string", "format": "date-time" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } }, "no_notification": { "description": "Flag for describing whether or not notifications related to this should be send.", "nullable": true, "type": "boolean", "example": false }, "idempotency_key": { "description": "Randomly generated key used to continue the completion of the cart associated with the claim in case of failure.", "nullable": true, "type": "string", "externalDocs": { "url": "https://docs.medusajs.com/development/idempotency-key/overview.md", "description": "Learn more how to use the idempotency key." } } } }, "ClaimTag": { "title": "Claim Tag", "description": "Claim Tags are user defined tags that can be assigned to claim items for easy filtering and grouping.", "type": "object", "required": [ "created_at", "deleted_at", "id", "metadata", "updated_at", "value" ], "properties": { "id": { "description": "The claim tag's ID", "type": "string", "example": "ctag_01G8ZCC5Y63B95V6B5SHBZ91S4" }, "value": { "description": "The value that the claim tag holds", "type": "string", "example": "Damaged" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "Country": { "title": "Country", "description": "Country details", "type": "object", "required": [ "display_name", "id", "iso_2", "iso_3", "name", "num_code", "region_id" ], "properties": { "id": { "description": "The country's ID", "type": "string", "example": 109 }, "iso_2": { "description": "The 2 character ISO code of the country in lower case", "type": "string", "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": { "description": "The 2 character ISO code of the country in lower case", "type": "string", "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": { "description": "The region ID this country is associated with.", "nullable": true, "type": "string", "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" }, "region": { "description": "The details of the region the country is associated with.", "x-expandable": "region", "nullable": true, "$ref": "#/components/schemas/Region" } } }, "CreateStockLocationInput": { "title": "Create Stock Location Input", "description": "Represents the Input to create a Stock Location", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The stock location name" }, "address_id": { "type": "string", "description": "The Stock location address ID" }, "address": { "description": "Stock location address object", "allOf": [ { "$ref": "#/components/schemas/StockLocationAddressInput" }, { "type": "object" } ] }, "metadata": { "type": "object", "description": "An optional key-value map with additional details", "example": { "car": "white" } } } }, "Currency": { "title": "Currency", "description": "Currency", "type": "object", "required": [ "code", "name", "symbol", "symbol_native" ], "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" }, "includes_tax": { "description": "Whether the currency prices include tax", "type": "boolean", "x-featureFlag": "tax_inclusive_pricing", "default": false } } }, "CustomShippingOption": { "title": "Custom Shipping Option", "description": "Custom Shipping Options are overriden Shipping Options. Admins can attach a Custom Shipping Option to a cart in order to set a custom price for a particular Shipping Option.", "type": "object", "required": [ "cart_id", "created_at", "deleted_at", "id", "metadata", "price", "shipping_option_id", "updated_at" ], "properties": { "id": { "description": "The custom shipping option's ID", "type": "string", "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": "The details of the overriden shipping options.", "x-expandable": "shipping_option", "nullable": true, "$ref": "#/components/schemas/ShippingOption" }, "cart_id": { "description": "The ID of the Cart that the custom shipping option is attached to", "nullable": true, "type": "string", "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63" }, "cart": { "description": "The details of the cart this shipping option belongs to.", "x-expandable": "cart", "nullable": true, "$ref": "#/components/schemas/Cart" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "Customer": { "title": "Customer", "description": "A customer can make purchases in your store and manage their profile.", "type": "object", "required": [ "billing_address_id", "created_at", "deleted_at", "email", "first_name", "has_account", "id", "last_name", "metadata", "phone", "updated_at" ], "properties": { "id": { "description": "The customer's ID", "type": "string", "example": "cus_01G2SG30J8C85S4A5CHM2S1NS2" }, "email": { "description": "The customer's email", "type": "string", "format": "email" }, "first_name": { "description": "The customer's first name", "nullable": true, "type": "string", "example": "Arno" }, "last_name": { "description": "The customer's last name", "nullable": true, "type": "string", "example": "Willms" }, "billing_address_id": { "description": "The customer's billing address ID", "nullable": true, "type": "string", "example": "addr_01G8ZH853YPY9B94857DY91YGW" }, "billing_address": { "description": "The details of the billing address associated with the customer.", "x-expandable": "billing_address", "nullable": true, "$ref": "#/components/schemas/Address" }, "shipping_addresses": { "description": "The details of the shipping addresses associated with the customer.", "type": "array", "x-expandable": "shipping_addresses", "items": { "$ref": "#/components/schemas/Address" } }, "phone": { "description": "The customer's phone number", "nullable": true, "type": "string", "example": 16128234334802 }, "has_account": { "description": "Whether the customer has an account or not", "type": "boolean", "default": false }, "orders": { "description": "The details of the orders this customer placed.", "type": "array", "x-expandable": "orders", "items": { "$ref": "#/components/schemas/Order" } }, "groups": { "description": "The customer groups the customer belongs to.", "type": "array", "x-expandable": "groups", "items": { "$ref": "#/components/schemas/CustomerGroup" } }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "CustomerGroup": { "title": "Customer Group", "description": "A customer group that can be used to organize customers into groups of similar traits.", "type": "object", "required": [ "created_at", "deleted_at", "id", "metadata", "name", "updated_at" ], "properties": { "id": { "description": "The customer group's ID", "type": "string", "example": "cgrp_01G8ZH853Y6TFXWPG5EYE81X63" }, "name": { "description": "The name of the customer group", "type": "string", "example": "VIP" }, "customers": { "description": "The details of the customers that belong to the customer group.", "type": "array", "x-expandable": "customers", "items": { "$ref": "#/components/schemas/Customer" } }, "price_lists": { "description": "The price lists that are associated with the customer group.", "type": "array", "x-expandable": "price_lists", "items": { "$ref": "#/components/schemas/PriceList" } }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "Discount": { "title": "Discount", "description": "A discount can be applied to a cart for promotional purposes.", "type": "object", "required": [ "code", "created_at", "deleted_at", "ends_at", "id", "is_disabled", "is_dynamic", "metadata", "parent_discount_id", "rule_id", "starts_at", "updated_at", "usage_count", "usage_limit", "valid_duration" ], "properties": { "id": { "description": "The discount's ID", "type": "string", "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": { "description": "The ID of the discount rule that defines how the discount will be applied to a cart.", "nullable": true, "type": "string", "example": "dru_01F0YESMVK96HVX7N419E3CJ7C" }, "rule": { "description": "The details of the discount rule that defines how the discount will be applied to a cart..", "x-expandable": "rule", "nullable": true, "$ref": "#/components/schemas/DiscountRule" }, "is_disabled": { "description": "Whether the Discount has been disabled. Disabled discounts cannot be applied to carts", "type": "boolean", "example": false }, "parent_discount_id": { "description": "The Discount that the discount was created from. This will always be a dynamic discount", "nullable": true, "type": "string", "example": "disc_01G8ZH853YPY9B94857DY91YGW" }, "parent_discount": { "description": "The details of the parent discount that this discount was created from.", "x-expandable": "parent_discount", "nullable": true, "$ref": "#/components/schemas/Discount" }, "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.", "nullable": true, "type": "string", "format": "date-time" }, "valid_duration": { "description": "Duration the discount runs between", "nullable": true, "type": "string", "example": "P3Y6M4DT12H30M5S" }, "regions": { "description": "The details of the regions in which the Discount can be used.", "type": "array", "x-expandable": "regions", "items": { "$ref": "#/components/schemas/Region" } }, "usage_limit": { "description": "The maximum number of times that a discount can be used.", "nullable": true, "type": "integer", "example": 100 }, "usage_count": { "description": "The number of times a discount has been used.", "type": "integer", "example": 50, "default": 0 }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "DiscountCondition": { "title": "Discount Condition", "description": "Holds rule conditions for when a discount is applicable", "type": "object", "required": [ "created_at", "deleted_at", "discount_rule_id", "id", "metadata", "operator", "type", "updated_at" ], "properties": { "id": { "description": "The discount condition's ID", "type": "string", "example": "discon_01G8X9A7ESKAJXG2H0E6F1MW7A" }, "type": { "description": "The type of the condition. The type affects the available resources associated with the condition. For example, if the type is `products`, that means the `products` relation will hold the products associated with this condition and other relations will be empty.", "type": "string", "enum": [ "products", "product_types", "product_collections", "product_tags", "customer_groups" ] }, "operator": { "description": "The operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that discountable resources are everything but the specified resources.", "type": "string", "enum": [ "in", "not_in" ] }, "discount_rule_id": { "description": "The ID of the discount rule associated with the condition", "type": "string", "example": "dru_01F0YESMVK96HVX7N419E3CJ7C" }, "discount_rule": { "description": "The details of the discount rule associated with the condition.", "x-expandable": "discount_rule", "nullable": true, "$ref": "#/components/schemas/DiscountRule" }, "products": { "description": "products associated with this condition if `type` is `products`.", "type": "array", "x-expandable": "products", "items": { "$ref": "#/components/schemas/Product" } }, "product_types": { "description": "Product types associated with this condition if `type` is `product_types`.", "type": "array", "x-expandable": "product_types", "items": { "$ref": "#/components/schemas/ProductType" } }, "product_tags": { "description": "Product tags associated with this condition if `type` is `product_tags`.", "type": "array", "x-expandable": "product_tags", "items": { "$ref": "#/components/schemas/ProductTag" } }, "product_collections": { "description": "Product collections associated with this condition if `type` is `product_collections`.", "type": "array", "x-expandable": "product_collections", "items": { "$ref": "#/components/schemas/ProductCollection" } }, "customer_groups": { "description": "Customer groups associated with this condition if `type` is `customer_groups`.", "type": "array", "x-expandable": "customer_groups", "items": { "$ref": "#/components/schemas/CustomerGroup" } }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "DiscountConditionCustomerGroup": { "title": "Product Tag Discount Condition", "description": "Associates a discount condition with a customer group", "type": "object", "required": [ "condition_id", "created_at", "customer_group_id", "metadata", "updated_at" ], "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.", "nullable": true, "$ref": "#/components/schemas/CustomerGroup" }, "discount_condition": { "description": "Available if the relation `discount_condition` is expanded.", "nullable": true, "$ref": "#/components/schemas/DiscountCondition" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "DiscountConditionProduct": { "title": "Product Discount Condition", "description": "This represents the association between a discount condition and a product", "type": "object", "required": [ "condition_id", "created_at", "metadata", "product_id", "updated_at" ], "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": "The details of the product.", "x-expandable": "product", "nullable": true, "$ref": "#/components/schemas/Product" }, "discount_condition": { "description": "The details of the discount condition.", "x-expandable": "discount_condition", "nullable": true, "$ref": "#/components/schemas/DiscountCondition" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "DiscountConditionProductCollection": { "title": "Product Collection Discount Condition", "description": "This represents the association between a discount condition and a product collection", "type": "object", "required": [ "condition_id", "created_at", "metadata", "product_collection_id", "updated_at" ], "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": "The details of the product collection.", "x-expandable": "product_collection", "nullable": true, "$ref": "#/components/schemas/ProductCollection" }, "discount_condition": { "description": "The details of the discount condition.", "x-expandable": "discount_condition", "nullable": true, "$ref": "#/components/schemas/DiscountCondition" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "DiscountConditionProductTag": { "title": "Product Tag Discount Condition", "description": "This represents the association between a discount condition and a product tag", "type": "object", "required": [ "condition_id", "created_at", "metadata", "product_tag_id", "updated_at" ], "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": "The details of the product tag.", "x-expandable": "product_tag", "nullable": true, "$ref": "#/components/schemas/ProductTag" }, "discount_condition": { "description": "The details of the discount condition.", "x-expandable": "discount_condition", "nullable": true, "$ref": "#/components/schemas/DiscountCondition" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "DiscountConditionProductType": { "title": "Product Type Discount Condition", "description": "This represents the association between a discount condition and a product type", "type": "object", "required": [ "condition_id", "created_at", "metadata", "product_type_id", "updated_at" ], "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": "The details of the product type.", "x-expandable": "product_type", "nullable": true, "$ref": "#/components/schemas/ProductType" }, "discount_condition": { "description": "The details of the discount condition.", "x-expandable": "discount_condition", "nullable": true, "$ref": "#/components/schemas/DiscountCondition" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "DiscountRule": { "title": "Discount Rule", "description": "A discount rule defines how a Discount is calculated when applied to a Cart.", "type": "object", "required": [ "allocation", "created_at", "deleted_at", "description", "id", "metadata", "type", "updated_at", "value" ], "properties": { "id": { "description": "The discount rule's ID", "type": "string", "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", "nullable": true, "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.", "nullable": true, "type": "string", "enum": [ "total", "item" ], "example": "total" }, "conditions": { "description": "The details of the discount conditions associated with the rule. They can be used to limit when the discount can be used.", "type": "array", "x-expandable": "conditions", "items": { "$ref": "#/components/schemas/DiscountCondition" } }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "DraftOrder": { "title": "DraftOrder", "description": "A draft order is created by an admin without direct involvement of the customer. Once its payment is marked as captured, it is transformed into an order.", "type": "object", "required": [ "canceled_at", "cart_id", "completed_at", "created_at", "display_id", "id", "idempotency_key", "metadata", "no_notification_order", "order_id", "status", "updated_at" ], "properties": { "id": { "description": "The draft order's ID", "type": "string", "example": "dorder_01G8TJFKBG38YYFQ035MSVG03C" }, "status": { "description": "The status of the draft order. It's changed to `completed` when it's transformed to an order.", "type": "string", "enum": [ "open", "completed" ], "default": "open" }, "display_id": { "description": "The draft order's display ID", "type": "string", "example": 2 }, "cart_id": { "description": "The ID of the cart associated with the draft order.", "nullable": true, "type": "string", "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63" }, "cart": { "description": "The details of the cart associated with the draft order.", "x-expandable": "cart", "nullable": true, "$ref": "#/components/schemas/Cart" }, "order_id": { "description": "The ID of the order created from the draft order when its payment is captured.", "nullable": true, "type": "string", "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK" }, "order": { "description": "The details of the order created from the draft order when its payment is captured.", "x-expandable": "order", "nullable": true, "$ref": "#/components/schemas/Order" }, "canceled_at": { "description": "The date the draft order was canceled at.", "nullable": true, "type": "string", "format": "date-time" }, "completed_at": { "description": "The date the draft order was completed at.", "nullable": true, "type": "string", "format": "date-time" }, "no_notification_order": { "description": "Whether to send the customer notifications regarding order updates.", "nullable": true, "type": "boolean", "example": false }, "idempotency_key": { "description": "Randomly generated key used to continue the completion of the cart associated with the draft order in case of failure.", "nullable": true, "type": "string", "externalDocs": { "url": "https://docs.medusajs.com/development/idempotency-key/overview.md", "description": "Learn more how to use the idempotency key." } }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "Error": { "title": "Response Error", "type": "object", "properties": { "code": { "type": "string", "description": "A slug code to indicate the type of the error." }, "message": { "type": "string", "description": "Description of the error that occurred." }, "type": { "type": "string", "description": "A slug indicating the type of the error." } } }, "ExtendedStoreDTO": { "allOf": [ { "$ref": "#/components/schemas/Store" }, { "type": "object", "required": [ "payment_providers", "fulfillment_providers", "feature_flags", "modules" ], "properties": { "payment_providers": { "$ref": "#/components/schemas/PaymentProvider" }, "fulfillment_providers": { "$ref": "#/components/schemas/FulfillmentProvider" }, "feature_flags": { "$ref": "#/components/schemas/FeatureFlagsResponse" }, "modules": { "$ref": "#/components/schemas/ModulesResponse" } } } ] }, "FeatureFlagsResponse": { "type": "array", "items": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "description": "The key of the feature flag.", "type": "string" }, "value": { "description": "The value of the feature flag.", "type": "boolean" } } } }, "Fulfillment": { "title": "Fulfillment", "description": "A Fulfillment is created once an admin can prepare the purchased goods. Fulfillments will eventually be shipped and hold information about how to track shipments. Fulfillments are created through a fulfillment provider, which typically integrates a third-party shipping service. Fulfillments can be associated with orders, claims, swaps, and returns.", "type": "object", "required": [ "canceled_at", "claim_order_id", "created_at", "data", "id", "idempotency_key", "location_id", "metadata", "no_notification", "order_id", "provider_id", "shipped_at", "swap_id", "tracking_numbers", "updated_at" ], "properties": { "id": { "description": "The fulfillment's ID", "type": "string", "example": "ful_01G8ZRTMQCA76TXNAT81KPJZRF" }, "claim_order_id": { "description": "The ID of the Claim that the Fulfillment belongs to.", "nullable": true, "type": "string", "example": null }, "claim_order": { "description": "The details of the claim that the fulfillment may belong to.", "x-expandable": "claim_order", "nullable": true, "$ref": "#/components/schemas/ClaimOrder" }, "swap_id": { "description": "The ID of the Swap that the Fulfillment belongs to.", "nullable": true, "type": "string", "example": null }, "swap": { "description": "The details of the swap that the fulfillment may belong to.", "x-expandable": "swap", "nullable": true, "$ref": "#/components/schemas/Swap" }, "order_id": { "description": "The ID of the Order that the Fulfillment belongs to.", "nullable": true, "type": "string", "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK" }, "order": { "description": "The details of the order that the fulfillment may belong to.", "x-expandable": "order", "nullable": true, "$ref": "#/components/schemas/Order" }, "provider_id": { "description": "The ID of the Fulfillment Provider responsible for handling the fulfillment.", "type": "string", "example": "manual" }, "provider": { "description": "The details of the fulfillment provider responsible for handling the fulfillment.", "x-expandable": "provider", "nullable": true, "$ref": "#/components/schemas/FulfillmentProvider" }, "location_id": { "description": "The ID of the stock location the fulfillment will be shipped from", "nullable": true, "type": "string", "example": "sloc_01G8TJSYT9M6AVS5N4EMNFS1EK" }, "items": { "description": "The Fulfillment Items in the Fulfillment. These hold information about how many of each Line Item has been fulfilled.", "type": "array", "x-expandable": "items", "items": { "$ref": "#/components/schemas/FulfillmentItem" } }, "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.", "type": "array", "x-expandable": "tracking_links", "items": { "$ref": "#/components/schemas/TrackingLink" } }, "tracking_numbers": { "description": "The tracking numbers that can be used to track the status of the fulfillment.", "deprecated": true, "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.", "nullable": true, "type": "string", "format": "date-time" }, "no_notification": { "description": "Flag for describing whether or not notifications related to this should be sent.", "nullable": true, "type": "boolean", "example": false }, "canceled_at": { "description": "The date with timezone at which the Fulfillment was canceled.", "nullable": true, "type": "string", "format": "date-time" }, "idempotency_key": { "description": "Randomly generated key used to continue the completion of the fulfillment in case of failure.", "nullable": true, "type": "string", "externalDocs": { "url": "https://docs.medusajs.com/development/idempotency-key/overview.md", "description": "Learn more how to use the idempotency key." } }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "FulfillmentItem": { "title": "Fulfillment Item", "description": "This represents the association between a Line Item and a Fulfillment.", "type": "object", "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": "The details of the fulfillment.", "x-expandable": "fulfillment", "nullable": true, "$ref": "#/components/schemas/Fulfillment" }, "item": { "description": "The details of the line item.", "x-expandable": "item", "nullable": true, "$ref": "#/components/schemas/LineItem" }, "quantity": { "description": "The quantity of the Line Item that is included in the Fulfillment.", "type": "integer", "example": 1 } } }, "FulfillmentProvider": { "title": "Fulfillment Provider", "description": "A fulfillment provider represents a fulfillment service installed in the Medusa backend, either through a plugin or backend customizations. It holds the fulfillment service's installation status.", "type": "object", "required": [ "id", "is_installed" ], "properties": { "id": { "description": "The ID of the fulfillment provider as given by the fulfillment service.", "type": "string", "example": "manual" }, "is_installed": { "description": "Whether the fulfillment service is installed in the current version. If a fulfillment service is no longer installed, the `is_installed` attribute is set to `false`.", "type": "boolean", "default": true } } }, "GiftCard": { "title": "Gift Card", "description": "Gift Cards are redeemable and represent a value that can be used towards the payment of an Order.", "type": "object", "required": [ "balance", "code", "created_at", "deleted_at", "ends_at", "id", "is_disabled", "metadata", "order_id", "region_id", "tax_rate", "updated_at", "value" ], "properties": { "id": { "description": "The gift card's ID", "type": "string", "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": { "description": "The ID of the region this gift card is available in.", "type": "string", "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" }, "region": { "description": "The details of the region this gift card is available in.", "x-expandable": "region", "nullable": true, "$ref": "#/components/schemas/Region" }, "order_id": { "description": "The ID of the order that the gift card was purchased in.", "nullable": true, "type": "string", "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK" }, "order": { "description": "The details of the order that the gift card was purchased in.", "x-expandable": "region", "nullable": true, "$ref": "#/components/schemas/Order" }, "is_disabled": { "description": "Whether the Gift Card has been disabled. Disabled Gift Cards cannot be applied to carts.", "type": "boolean", "default": false }, "ends_at": { "description": "The time at which the Gift Card can no longer be used.", "nullable": true, "type": "string", "format": "date-time" }, "tax_rate": { "description": "The gift card's tax rate that will be applied on calculating totals", "nullable": true, "type": "number", "example": 0 }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "GiftCardTransaction": { "title": "Gift Card Transaction", "description": "Gift Card Transactions are created once a Customer uses a Gift Card to pay for their Order.", "type": "object", "required": [ "amount", "created_at", "gift_card_id", "id", "is_taxable", "order_id", "tax_rate" ], "properties": { "id": { "description": "The gift card transaction's ID", "type": "string", "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": "The details of the gift card associated used in this transaction.", "x-expandable": "gift_card", "nullable": true, "$ref": "#/components/schemas/GiftCard" }, "order_id": { "description": "The ID of the order that the gift card was used for payment.", "type": "string", "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK" }, "order": { "description": "The details of the order that the gift card was used for payment.", "x-expandable": "order", "nullable": true, "$ref": "#/components/schemas/Order" }, "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.", "nullable": true, "type": "boolean", "example": false }, "tax_rate": { "description": "The tax rate of the transaction", "nullable": true, "type": "number", "example": 0 } } }, "IdempotencyKey": { "title": "Idempotency Key", "description": "Idempotency Key is used to continue a process in case of any failure that might occur.", "type": "object", "required": [ "created_at", "id", "idempotency_key", "locked_at", "recovery_point", "response_code", "response_body", "request_method", "request_params", "request_path" ], "properties": { "id": { "description": "The idempotency key's ID", "type": "string", "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/development/idempotency-key/overview.md", "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.", "nullable": true, "type": "string", "format": "date-time" }, "request_method": { "description": "The method of the request", "nullable": true, "type": "string", "example": "POST" }, "request_params": { "description": "The parameters passed to the request", "nullable": true, "type": "object", "example": { "id": "cart_01G8ZH853Y6TFXWPG5EYE81X63" } }, "request_path": { "description": "The request's path", "nullable": true, "type": "string", "example": "/store/carts/cart_01G8ZH853Y6TFXWPG5EYE81X63/complete" }, "response_code": { "description": "The response's code.", "nullable": true, "type": "string", "example": 200 }, "response_body": { "description": "The response's body", "nullable": true, "type": "object", "example": { "id": "cart_01G8ZH853Y6TFXWPG5EYE81X63" } }, "recovery_point": { "description": "Where to continue from.", "type": "string", "default": "started" } } }, "Image": { "title": "Image", "description": "An Image is used to store details about uploaded images. Images are uploaded by the File Service, and the URL is provided by the File Service.", "type": "object", "required": [ "created_at", "deleted_at", "id", "metadata", "updated_at", "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": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "InventoryItemDTO": { "type": "object", "required": [ "sku" ], "properties": { "sku": { "description": "The Stock Keeping Unit (SKU) code of the Inventory Item.", "type": "string" }, "hs_code": { "description": "The Harmonized System code of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.", "type": "string" }, "origin_country": { "description": "The country in which the Inventory Item was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.", "type": "string" }, "mid_code": { "description": "The Manufacturers Identification code that identifies the manufacturer of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.", "type": "string" }, "title": { "description": "Title of the inventory item", "type": "string" }, "description": { "description": "Description of the inventory item", "type": "string" }, "thumbnail": { "description": "Thumbnail for the inventory item", "type": "string" }, "material": { "description": "The material and composition that the Inventory Item is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.", "type": "string" }, "weight": { "description": "The weight of the Inventory Item. May be used in shipping rate calculations.", "type": "number" }, "height": { "description": "The height of the Inventory Item. May be used in shipping rate calculations.", "type": "number" }, "width": { "description": "The width of the Inventory Item. May be used in shipping rate calculations.", "type": "number" }, "length": { "description": "The length of the Inventory Item. May be used in shipping rate calculations.", "type": "number" }, "requires_shipping": { "description": "Whether the item requires shipping.", "type": "boolean" }, "metadata": { "type": "object", "description": "An optional key-value map with additional details", "example": { "car": "white" } }, "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" } } }, "InventoryLevelDTO": { "type": "object", "required": [ "inventory_item_id", "location_id", "stocked_quantity", "reserved_quantity", "incoming_quantity" ], "properties": { "location_id": { "description": "the item location ID", "type": "string" }, "stocked_quantity": { "description": "the total stock quantity of an inventory item at the given location ID", "type": "number" }, "reserved_quantity": { "description": "the reserved stock quantity of an inventory item at the given location ID", "type": "number" }, "incoming_quantity": { "description": "the incoming stock quantity of an inventory item at the given location ID", "type": "number" }, "metadata": { "type": "object", "description": "An optional key-value map with additional details", "example": { "car": "white" } }, "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" } } }, "Invite": { "title": "Invite", "description": "An invite is created when an admin user invites a new user to join the store's team. Once the invite is accepted, it's deleted.", "type": "object", "required": [ "accepted", "created_at", "deleted_at", "expires_at", "id", "metadata", "role", "token", "updated_at", "user_email" ], "properties": { "id": { "type": "string", "description": "The invite's ID", "example": "invite_01G8TKE4XYCTHSCK2GDEP47RE1" }, "user_email": { "description": "The email of the user being invited.", "type": "string", "format": "email" }, "role": { "description": "The user's role. These roles don't change the privileges of the user.", "nullable": true, "type": "string", "enum": [ "admin", "member", "developer" ], "default": "member" }, "accepted": { "description": "Whether the invite was accepted or not.", "type": "boolean", "default": false }, "token": { "description": "The token used to accept the invite.", "type": "string" }, "expires_at": { "description": "The date the invite expires at.", "type": "string", "format": "date-time" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "LineItem": { "title": "Line Item", "description": "Line Items are created when a product is added to a Cart. When Line Items are purchased they will get copied to the resulting order, swap, or claim, and can eventually be referenced in Fulfillments and Returns. Line items may also be used for order edits.", "type": "object", "required": [ "allow_discounts", "cart_id", "claim_order_id", "created_at", "description", "fulfilled_quantity", "has_shipping", "id", "is_giftcard", "is_return", "metadata", "order_edit_id", "order_id", "original_item_id", "quantity", "returned_quantity", "shipped_quantity", "should_merge", "swap_id", "thumbnail", "title", "unit_price", "updated_at", "variant_id" ], "properties": { "id": { "description": "The line item's ID", "type": "string", "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN" }, "cart_id": { "description": "The ID of the cart that the line item may belongs to.", "nullable": true, "type": "string", "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63" }, "cart": { "description": "The details of the cart that the line item may belongs to.", "x-expandable": "cart", "nullable": true, "$ref": "#/components/schemas/Cart" }, "order_id": { "description": "The ID of the order that the line item may belongs to.", "nullable": true, "type": "string", "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK" }, "order": { "description": "The details of the order that the line item may belongs to.", "x-expandable": "order", "nullable": true, "$ref": "#/components/schemas/Order" }, "swap_id": { "description": "The ID of the swap that the line item may belong to.", "nullable": true, "type": "string", "example": null }, "swap": { "description": "The details of the swap that the line item may belong to.", "x-expandable": "swap", "nullable": true, "$ref": "#/components/schemas/Swap" }, "claim_order_id": { "description": "The ID of the claim that the line item may belong to.", "nullable": true, "type": "string", "example": null }, "claim_order": { "description": "The details of the claim that the line item may belong to.", "x-expandable": "claim_order", "nullable": true, "$ref": "#/components/schemas/ClaimOrder" }, "tax_lines": { "description": "The details of the item's tax lines.", "x-expandable": "tax_lines", "type": "array", "items": { "$ref": "#/components/schemas/LineItemTaxLine" } }, "adjustments": { "description": "The details of the item's adjustments, which are available when a discount is applied on the item.", "x-expandable": "adjustments", "type": "array", "items": { "$ref": "#/components/schemas/LineItemAdjustment" } }, "original_item_id": { "description": "The ID of the original line item. This is useful if the line item belongs to a resource that references an order, such as a return or an order edit.", "nullable": true, "type": "string" }, "order_edit_id": { "description": "The ID of the order edit that the item may belong to.", "nullable": true, "type": "string" }, "order_edit": { "description": "The details of the order edit.", "x-expandable": "order_edit", "nullable": true, "$ref": "#/components/schemas/OrderEdit" }, "title": { "description": "The title of the Line Item.", "type": "string", "example": "Medusa Coffee Mug" }, "description": { "description": "A more detailed description of the contents of the Line Item.", "nullable": true, "type": "string", "example": "One Size" }, "thumbnail": { "description": "A URL string to a small image of the contents of the Line Item.", "nullable": true, "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", "default": false }, "is_giftcard": { "description": "Flag to indicate if the Line Item is a Gift Card.", "type": "boolean", "default": 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", "default": true }, "allow_discounts": { "description": "Flag to indicate if the Line Item should be included when doing discount calculations.", "type": "boolean", "default": true }, "has_shipping": { "description": "Flag to indicate if the Line Item has fulfillment associated with it.", "nullable": true, "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": "integer", "example": 8000 }, "variant_id": { "description": "The id of the Product Variant contained in the Line Item.", "nullable": true, "type": "string", "example": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6" }, "variant": { "description": "The details of the product variant that this item was created from.", "x-expandable": "variant", "nullable": true, "$ref": "#/components/schemas/ProductVariant" }, "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.", "nullable": true, "type": "integer", "example": 0 }, "returned_quantity": { "description": "The quantity of the Line Item that has been returned.", "nullable": true, "type": "integer", "example": 0 }, "shipped_quantity": { "description": "The quantity of the Line Item that has been shipped.", "nullable": true, "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": { "description": "The subtotal of the line item", "type": "integer", "example": 8000 }, "tax_total": { "description": "The total of tax of the line item", "type": "integer", "example": 0 }, "total": { "description": "The total amount of the line item", "type": "integer", "example": 8000 }, "original_total": { "description": "The original total amount of the line item", "type": "integer", "example": 8000 }, "original_tax_total": { "description": "The original tax total amount of the line item", "type": "integer", "example": 0 }, "discount_total": { "description": "The total of discount of the line item rounded", "type": "integer", "example": 0 }, "raw_discount_total": { "description": "The total of discount of the line item", "type": "integer", "example": 0 }, "gift_card_total": { "description": "The total of the gift card of the line item", "type": "integer", "example": 0 }, "includes_tax": { "description": "Indicates if the line item unit_price include tax", "x-featureFlag": "tax_inclusive_pricing", "type": "boolean", "default": false }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "LineItemAdjustment": { "title": "Line Item Adjustment", "description": "A Line Item Adjustment includes details on discounts applied on a line item.", "type": "object", "required": [ "amount", "description", "discount_id", "id", "item_id", "metadata" ], "properties": { "id": { "description": "The Line Item Adjustment's ID", "type": "string", "example": "lia_01G8TKE4XYCTHSCK2GDEP47RE1" }, "item_id": { "description": "The ID of the line item", "type": "string", "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN" }, "item": { "description": "The details of the line item.", "x-expandable": "item", "nullable": true, "$ref": "#/components/schemas/LineItem" }, "description": { "description": "The line item's adjustment description", "type": "string", "example": "Adjusted item's price." }, "discount_id": { "description": "The ID of the discount associated with the adjustment", "nullable": true, "type": "string", "example": "disc_01F0YESMW10MGHWJKZSDDMN0VN" }, "discount": { "description": "The details of the discount associated with the adjustment.", "x-expandable": "discount", "nullable": true, "$ref": "#/components/schemas/Discount" }, "amount": { "description": "The adjustment amount", "type": "number", "example": 1000 }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "LineItemTaxLine": { "title": "Line Item Tax Line", "description": "A Line Item Tax Line represents the taxes applied on a line item.", "type": "object", "required": [ "code", "created_at", "id", "item_id", "metadata", "name", "rate", "updated_at" ], "properties": { "id": { "description": "The line item tax line's ID", "type": "string", "example": "litl_01G1G5V2DRX1SK6NQQ8VVX4HQ8" }, "code": { "description": "A code to identify the tax type by", "nullable": true, "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 }, "item_id": { "description": "The ID of the line item", "type": "string", "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN" }, "item": { "description": "The details of the line item.", "x-expandable": "item", "nullable": true, "$ref": "#/components/schemas/LineItem" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "ModulesResponse": { "type": "array", "items": { "type": "object", "required": [ "module", "resolution" ], "properties": { "module": { "description": "The key of the module.", "type": "string" }, "resolution": { "description": "The resolution path of the module or false if module is not installed.", "type": "string" } } } }, "MoneyAmount": { "title": "Money Amount", "description": "A Money Amount represent a price amount, for example, a product variant's price or a price in a price list. 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 Region.", "type": "object", "required": [ "amount", "created_at", "currency_code", "deleted_at", "id", "max_quantity", "min_quantity", "price_list_id", "region_id", "updated_at", "variant_id" ], "properties": { "id": { "description": "The money amount's ID", "type": "string", "example": "ma_01F0YESHRFQNH5S8Q0PK84YYZN" }, "currency_code": { "description": "The 3 character currency code that the money amount may belong to.", "type": "string", "example": "usd", "externalDocs": { "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes", "description": "See a list of codes." } }, "currency": { "description": "The details of the currency that the money amount may belong to.", "x-expandable": "currency", "nullable": true, "$ref": "#/components/schemas/Currency" }, "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.", "nullable": true, "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.", "nullable": true, "type": "integer", "example": 1 }, "price_list_id": { "description": "The ID of the price list that the money amount may belong to.", "nullable": true, "type": "string", "example": "pl_01G8X3CKJXCG5VXVZ87H9KC09W" }, "price_list": { "description": "The details of the price list that the money amount may belong to.", "x-expandable": "price_list", "nullable": true, "$ref": "#/components/schemas/PriceList" }, "variant_id": { "description": "The ID of the Product Variant contained in the Line Item.", "nullable": true, "type": "string", "example": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6" }, "variant": { "description": "The details of the product variant that the money amount may belong to.", "x-expandable": "variant", "nullable": true, "$ref": "#/components/schemas/ProductVariant" }, "region_id": { "description": "The region's ID", "nullable": true, "type": "string", "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" }, "region": { "description": "The details of the region that the money amount may belong to.", "x-expandable": "region", "nullable": true, "$ref": "#/components/schemas/Region" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" } } }, "MultipleErrors": { "title": "Multiple Errors", "type": "object", "properties": { "errors": { "type": "array", "description": "Array of errors", "items": { "$ref": "#/components/schemas/Error" } }, "message": { "type": "string", "default": "Provided request body contains errors. Please check the data and retry the request" } } }, "Note": { "title": "Note", "description": "A Note is an element that can be used in association with different resources to allow admin users to describe additional information. For example, they can be used to add additional information about orders.", "type": "object", "required": [ "author_id", "created_at", "deleted_at", "id", "metadata", "resource_id", "resource_type", "updated_at", "value" ], "properties": { "id": { "description": "The note's ID", "type": "string", "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": { "description": "The ID of the user that created the note.", "nullable": true, "type": "string", "example": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V" }, "author": { "description": "The details of the user that created the note.", "x-expandable": "author", "nullable": true, "$ref": "#/components/schemas/User" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" } } } }, "Notification": { "title": "Notification", "description": "A notification is an alert sent, typically to customers, using the installed Notification Provider as a reaction to internal events such as `order.placed`. Notifications can be resent.", "type": "object", "required": [ "created_at", "customer_id", "data", "event_name", "id", "parent_id", "provider_id", "resource_type", "resource_id", "to", "updated_at" ], "properties": { "id": { "description": "The notification's ID", "type": "string", "example": "noti_01G53V9Y6CKMCGBM1P0X7C28RX" }, "event_name": { "description": "The name of the event that the notification was sent for.", "nullable": true, "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 this notification was sent to.", "nullable": true, "type": "string", "example": "cus_01G2SG30J8C85S4A5CHM2S1NS2" }, "customer": { "description": "The details of the customer that this notification was sent to.", "x-expandable": "customer", "nullable": true, "$ref": "#/components/schemas/Customer" }, "to": { "description": "The address that the Notification was sent to. This will usually be an email address, but can 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 notification's parent ID", "nullable": true, "type": "string", "example": "noti_01G53V9Y6CKMCGBM1P0X7C28RX" }, "parent_notification": { "description": "The details of the parent notification.", "x-expandable": "parent_notification", "nullable": true, "$ref": "#/components/schemas/Notification" }, "resends": { "description": "The details of all resends of the notification.", "type": "array", "x-expandable": "resends", "items": { "$ref": "#/components/schemas/Notification" } }, "provider_id": { "description": "The ID of the notification provider used to send the notification.", "nullable": true, "type": "string", "example": "sengrid" }, "provider": { "description": "The notification provider used to send the notification.", "x-expandable": "provider", "nullable": true, "$ref": "#/components/schemas/NotificationProvider" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" } } }, "NotificationProvider": { "title": "Notification Provider", "description": "A notification provider represents a notification service installed in the Medusa backend, either through a plugin or backend customizations. It holds the notification service's installation status.", "type": "object", "required": [ "id", "is_installed" ], "properties": { "id": { "description": "The ID of the notification provider as given by the notification service.", "type": "string", "example": "sendgrid" }, "is_installed": { "description": "Whether the notification service is installed in the current version. If a notification service is no longer installed, the `is_installed` attribute is set to `false`.", "type": "boolean", "default": true } } }, "OAuth": { "title": "OAuth", "description": "An Oauth app is typically created by a plugin to handle authentication to third-party services.", "type": "object", "required": [ "application_name", "data", "display_name", "id", "install_url", "uninstall_url" ], "properties": { "id": { "description": "The app's ID", "type": "string", "example": "example_app" }, "display_name": { "description": "The app's display name", "type": "string", "example": "Example app" }, "application_name": { "description": "The app's name", "type": "string", "example": "example" }, "install_url": { "description": "The URL to install the app", "nullable": true, "type": "string", "format": "uri" }, "uninstall_url": { "description": "The URL to uninstall the app", "nullable": true, "type": "string", "format": "uri" }, "data": { "description": "Any data necessary to the app.", "nullable": true, "type": "object", "example": {} } } }, "Order": { "title": "Order", "description": "An order is a purchase made by a customer. It holds details about payment and fulfillment of the order. An order may also be created from a draft order, which is created by an admin user.", "type": "object", "required": [ "billing_address_id", "canceled_at", "cart_id", "created_at", "currency_code", "customer_id", "draft_order_id", "display_id", "email", "external_id", "fulfillment_status", "id", "idempotency_key", "metadata", "no_notification", "object", "payment_status", "region_id", "shipping_address_id", "status", "tax_rate", "updated_at" ], "properties": { "id": { "description": "The order's ID", "type": "string", "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK" }, "status": { "description": "The order's status", "type": "string", "enum": [ "pending", "completed", "archived", "canceled", "requires_action" ], "default": "pending" }, "fulfillment_status": { "description": "The order's fulfillment status", "type": "string", "enum": [ "not_fulfilled", "partially_fulfilled", "fulfilled", "partially_shipped", "shipped", "partially_returned", "returned", "canceled", "requires_action" ], "default": "not_fulfilled" }, "payment_status": { "description": "The order's payment status", "type": "string", "enum": [ "not_paid", "awaiting", "captured", "partially_refunded", "refunded", "canceled", "requires_action" ], "default": "not_paid" }, "display_id": { "description": "The order's display ID", "type": "integer", "example": 2 }, "cart_id": { "description": "The ID of the cart associated with the order", "nullable": true, "type": "string", "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63" }, "cart": { "description": "The details of the cart associated with the order.", "x-expandable": "cart", "nullable": true, "$ref": "#/components/schemas/Cart" }, "customer_id": { "description": "The ID of the customer associated with the order", "type": "string", "example": "cus_01G2SG30J8C85S4A5CHM2S1NS2" }, "customer": { "description": "The details of the customer associated with the order.", "x-expandable": "customer", "nullable": true, "$ref": "#/components/schemas/Customer" }, "email": { "description": "The email associated with the order", "type": "string", "format": "email" }, "billing_address_id": { "description": "The ID of the billing address associated with the order", "nullable": true, "type": "string", "example": "addr_01G8ZH853YPY9B94857DY91YGW" }, "billing_address": { "description": "The details of the billing address associated with the order.", "x-expandable": "billing_address", "nullable": true, "$ref": "#/components/schemas/Address" }, "shipping_address_id": { "description": "The ID of the shipping address associated with the order", "nullable": true, "type": "string", "example": "addr_01G8ZH853YPY9B94857DY91YGW" }, "shipping_address": { "description": "The details of the shipping address associated with the order.", "x-expandable": "shipping_address", "nullable": true, "$ref": "#/components/schemas/Address" }, "region_id": { "description": "The ID of the region this order was created in.", "type": "string", "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" }, "region": { "description": "The details of the region this order was created in.", "x-expandable": "region", "nullable": true, "$ref": "#/components/schemas/Region" }, "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": "The details of the currency used in the order.", "x-expandable": "currency", "nullable": true, "$ref": "#/components/schemas/Currency" }, "tax_rate": { "description": "The order's tax rate", "nullable": true, "type": "number", "example": 0 }, "discounts": { "description": "The details of the discounts applied on the order.", "type": "array", "x-expandable": "discounts", "items": { "$ref": "#/components/schemas/Discount" } }, "gift_cards": { "description": "The details of the gift card used in the order.", "type": "array", "x-expandable": "gift_cards", "items": { "$ref": "#/components/schemas/GiftCard" } }, "shipping_methods": { "description": "The details of the shipping methods used in the order.", "type": "array", "x-expandable": "shipping_methods", "items": { "$ref": "#/components/schemas/ShippingMethod" } }, "payments": { "description": "The details of the payments used in the order.", "type": "array", "x-expandable": "payments", "items": { "$ref": "#/components/schemas/Payment" } }, "fulfillments": { "description": "The details of the fulfillments created for the order.", "type": "array", "x-expandable": "fulfillments", "items": { "$ref": "#/components/schemas/Fulfillment" } }, "returns": { "description": "The details of the returns created for the order.", "type": "array", "x-expandable": "returns", "items": { "$ref": "#/components/schemas/Return" } }, "claims": { "description": "The details of the claims created for the order.", "type": "array", "x-expandable": "claims", "items": { "$ref": "#/components/schemas/ClaimOrder" } }, "refunds": { "description": "The details of the refunds created for the order.", "type": "array", "x-expandable": "refunds", "items": { "$ref": "#/components/schemas/Refund" } }, "swaps": { "description": "The details of the swaps created for the order.", "type": "array", "x-expandable": "swaps", "items": { "$ref": "#/components/schemas/Swap" } }, "draft_order_id": { "description": "The ID of the draft order this order was created from.", "nullable": true, "type": "string", "example": null }, "draft_order": { "description": "The details of the draft order this order was created from.", "x-expandable": "draft_order", "nullable": true, "$ref": "#/components/schemas/DraftOrder" }, "items": { "description": "The details of the line items that belong to the order.", "x-expandable": "items", "type": "array", "items": { "$ref": "#/components/schemas/LineItem" } }, "edits": { "description": "The details of the order edits done on the order.", "type": "array", "x-expandable": "edits", "items": { "$ref": "#/components/schemas/OrderEdit" } }, "gift_card_transactions": { "description": "The gift card transactions made in the order.", "type": "array", "x-expandable": "gift_card_transactions", "items": { "$ref": "#/components/schemas/GiftCardTransaction" } }, "canceled_at": { "description": "The date the order was canceled on.", "nullable": true, "type": "string", "format": "date-time" }, "no_notification": { "description": "Flag for describing whether or not notifications related to this should be send.", "nullable": true, "type": "boolean", "example": false }, "idempotency_key": { "description": "Randomly generated key used to continue the processing of the order in case of failure.", "nullable": true, "type": "string", "externalDocs": { "url": "https://docs.medusajs.com/development/idempotency-key/overview.md", "description": "Learn more how to use the idempotency key." } }, "external_id": { "description": "The ID of an external order.", "nullable": true, "type": "string", "example": null }, "sales_channel_id": { "description": "The ID of the sales channel this order belongs to.", "nullable": true, "type": "string", "example": null }, "sales_channel": { "description": "The details of the sales channel this order belongs to.", "x-expandable": "sales_channel", "nullable": true, "$ref": "#/components/schemas/SalesChannel" }, "shipping_total": { "type": "integer", "description": "The total of shipping", "example": 1000 }, "raw_discount_total": { "description": "The total of discount", "type": "integer", "example": 800 }, "discount_total": { "description": "The total of discount rounded", "type": "integer", "example": 800 }, "tax_total": { "description": "The total of tax", "type": "integer", "example": 0 }, "refunded_total": { "description": "The total amount refunded if the order is returned.", "type": "integer", "example": 0 }, "total": { "description": "The total amount of the order", "type": "integer", "example": 8200 }, "subtotal": { "description": "The subtotal of the order", "type": "integer", "example": 8000 }, "paid_total": { "description": "The total amount paid", "type": "integer", "example": 8000 }, "refundable_amount": { "description": "The amount that can be refunded", "type": "integer", "example": 8200 }, "gift_card_total": { "description": "The total of gift cards", "type": "integer", "example": 0 }, "gift_card_tax_total": { "description": "The total of gift cards with taxes", "type": "integer", "example": 0 }, "returnable_items": { "description": "The details of the line items that are returnable as part of the order, swaps, or claims", "type": "array", "x-expandable": "returnable_items", "items": { "$ref": "#/components/schemas/LineItem" } }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "OrderEdit": { "title": "Order Edit", "description": "Order edit allows modifying items in an order, such as adding, updating, or deleting items from the original order. Once the order edit is confirmed, the changes are reflected on the original order.", "type": "object", "required": [ "canceled_at", "canceled_by", "confirmed_by", "confirmed_at", "created_at", "created_by", "declined_at", "declined_by", "declined_reason", "id", "internal_note", "order_id", "payment_collection_id", "requested_at", "requested_by", "status", "updated_at" ], "properties": { "id": { "description": "The order edit's ID", "type": "string", "example": "oe_01G8TJSYT9M6AVS5N4EMNFS1EK" }, "order_id": { "description": "The ID of the order that is edited", "type": "string", "example": "order_01G2SG30J8C85S4A5CHM2S1NS2" }, "order": { "description": "The details of the order that this order edit was created for.", "x-expandable": "order", "nullable": true, "$ref": "#/components/schemas/Order" }, "changes": { "description": "The details of all the changes on the original order's line items.", "x-expandable": "changes", "type": "array", "items": { "$ref": "#/components/schemas/OrderItemChange" } }, "internal_note": { "description": "An optional note with additional details about the order edit.", "nullable": true, "type": "string", "example": "Included two more items B to the order." }, "created_by": { "description": "The unique identifier of the user or customer who created the order edit.", "type": "string" }, "requested_by": { "description": "The unique identifier of the user or customer who requested the order edit.", "nullable": true, "type": "string" }, "requested_at": { "description": "The date with timezone at which the edit was requested.", "nullable": true, "type": "string", "format": "date-time" }, "confirmed_by": { "description": "The unique identifier of the user or customer who confirmed the order edit.", "nullable": true, "type": "string" }, "confirmed_at": { "description": "The date with timezone at which the edit was confirmed.", "nullable": true, "type": "string", "format": "date-time" }, "declined_by": { "description": "The unique identifier of the user or customer who declined the order edit.", "nullable": true, "type": "string" }, "declined_at": { "description": "The date with timezone at which the edit was declined.", "nullable": true, "type": "string", "format": "date-time" }, "declined_reason": { "description": "An optional note why the order edit is declined.", "nullable": true, "type": "string" }, "canceled_by": { "description": "The unique identifier of the user or customer who cancelled the order edit.", "nullable": true, "type": "string" }, "canceled_at": { "description": "The date with timezone at which the edit was cancelled.", "nullable": true, "type": "string", "format": "date-time" }, "subtotal": { "description": "The total of subtotal", "type": "integer", "example": 8000 }, "discount_total": { "description": "The total of discount", "type": "integer", "example": 800 }, "shipping_total": { "description": "The total of the shipping amount", "type": "integer", "example": 800 }, "gift_card_total": { "description": "The total of the gift card amount", "type": "integer", "example": 800 }, "gift_card_tax_total": { "description": "The total of the gift card tax amount", "type": "integer", "example": 800 }, "tax_total": { "description": "The total of tax", "type": "integer", "example": 0 }, "total": { "description": "The total amount of the edited order.", "type": "integer", "example": 8200 }, "difference_due": { "description": "The difference between the total amount of the order and total amount of edited order.", "type": "integer", "example": 8200 }, "status": { "description": "The status of the order edit.", "type": "string", "enum": [ "confirmed", "declined", "requested", "created", "canceled" ] }, "items": { "description": "The details of the cloned items from the original order with the new changes. Once the order edit is confirmed, these line items are associated with the original order.", "type": "array", "x-expandable": "items", "items": { "$ref": "#/components/schemas/LineItem" } }, "payment_collection_id": { "description": "The ID of the payment collection", "nullable": true, "type": "string", "example": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK" }, "payment_collection": { "description": "The details of the payment collection used to authorize additional payment if necessary.", "x-expandable": "payment_collection", "nullable": true, "$ref": "#/components/schemas/PaymentCollection" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" } } }, "OrderItemChange": { "title": "Order Item Change", "description": "An order item change is a change made within an order edit to an order's items. These changes are not reflected on the original order until the order edit is confirmed.", "type": "object", "required": [ "created_at", "deleted_at", "id", "line_item_id", "order_edit_id", "original_line_item_id", "type", "updated_at" ], "properties": { "id": { "description": "The order item change's ID", "type": "string", "example": "oic_01G8TJSYT9M6AVS5N4EMNFS1EK" }, "type": { "description": "The order item change's status", "type": "string", "enum": [ "item_add", "item_remove", "item_update" ] }, "order_edit_id": { "description": "The ID of the order edit", "type": "string", "example": "oe_01G2SG30J8C85S4A5CHM2S1NS2" }, "order_edit": { "description": "The details of the order edit the item change is associated with.", "x-expandable": "order_edit", "nullable": true, "$ref": "#/components/schemas/OrderEdit" }, "original_line_item_id": { "description": "The ID of the original line item in the order", "nullable": true, "type": "string", "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN" }, "original_line_item": { "description": "The details of the original line item this item change references. This is used if the item change updates or deletes the original item.", "x-expandable": "original_line_item", "nullable": true, "$ref": "#/components/schemas/LineItem" }, "line_item_id": { "description": "The ID of the cloned line item.", "nullable": true, "type": "string", "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN" }, "line_item": { "description": "The details of the resulting line item after the item change. This line item is then used in the original order once the order edit is confirmed.", "x-expandable": "line_item", "nullable": true, "$ref": "#/components/schemas/LineItem" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" } } }, "Payment": { "title": "Payment", "description": "A payment is originally created from a payment session. Once a payment session is authorized, the payment is created to represent the authorized amount with a given payment method. Payments can be captured, canceled or refunded. Payments can be made towards orders, swaps, order edits, or other resources.", "type": "object", "required": [ "amount", "amount_refunded", "canceled_at", "captured_at", "cart_id", "created_at", "currency_code", "data", "id", "idempotency_key", "metadata", "order_id", "provider_id", "swap_id", "updated_at" ], "properties": { "id": { "description": "The payment's ID", "type": "string", "example": "pay_01G2SJNT6DEEWDFNAJ4XWDTHKE" }, "swap_id": { "description": "The ID of the swap that this payment was potentially created for.", "nullable": true, "type": "string", "example": null }, "swap": { "description": "The details of the swap that this payment was potentially created for.", "x-expandable": "swap", "nullable": true, "$ref": "#/components/schemas/Swap" }, "cart_id": { "description": "The ID of the cart that the payment session was potentially created for.", "nullable": true, "type": "string" }, "cart": { "description": "The details of the cart that the payment session was potentially created for.", "x-expandable": "cart", "nullable": true, "$ref": "#/components/schemas/Cart" }, "order_id": { "description": "The ID of the order that the payment session was potentially created for.", "nullable": true, "type": "string", "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK" }, "order": { "description": "The details of the order that the payment session was potentially created for.", "x-expandable": "order", "nullable": true, "$ref": "#/components/schemas/Order" }, "amount": { "description": "The amount that the Payment has been authorized for.", "type": "integer", "example": 100 }, "currency_code": { "description": "The 3 character ISO currency code of the payment.", "type": "string", "example": "usd", "externalDocs": { "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes", "description": "See a list of codes." } }, "currency": { "description": "The details of the currency of the payment.", "x-expandable": "currency", "nullable": true, "$ref": "#/components/schemas/Currency" }, "amount_refunded": { "description": "The amount of the original Payment amount that has been refunded back to the Customer.", "type": "integer", "default": 0, "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.", "nullable": true, "type": "string", "format": "date-time" }, "canceled_at": { "description": "The date with timezone at which the Payment was canceled.", "nullable": true, "type": "string", "format": "date-time" }, "idempotency_key": { "description": "Randomly generated key used to continue the completion of a payment in case of failure.", "nullable": true, "type": "string", "externalDocs": { "url": "https://docs.medusajs.com/development/idempotency-key/overview.md", "description": "Learn more how to use the idempotency key." } }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "PaymentCollection": { "title": "Payment Collection", "description": "A payment collection allows grouping and managing a list of payments at one. This can be helpful when making additional payment for order edits or integrating installment payments.", "type": "object", "required": [ "amount", "authorized_amount", "created_at", "created_by", "currency_code", "deleted_at", "description", "id", "metadata", "region_id", "status", "type", "updated_at" ], "properties": { "id": { "description": "The payment collection's ID", "type": "string", "example": "paycol_01G8TJSYT9M6AVS5N4EMNFS1EK" }, "type": { "description": "The type of the payment collection", "type": "string", "enum": [ "order_edit" ] }, "status": { "description": "The type of the payment collection", "type": "string", "enum": [ "not_paid", "awaiting", "authorized", "partially_authorized", "canceled" ] }, "description": { "description": "Description of the payment collection", "nullable": true, "type": "string" }, "amount": { "description": "Amount of the payment collection.", "type": "integer" }, "authorized_amount": { "description": "Authorized amount of the payment collection.", "nullable": true, "type": "integer" }, "region_id": { "description": "The ID of the region this payment collection is associated with.", "type": "string", "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" }, "region": { "description": "The details of the region this payment collection is associated with.", "x-expandable": "region", "nullable": true, "$ref": "#/components/schemas/Region" }, "currency_code": { "description": "The 3 character ISO code for the currency this payment collection is associated with.", "type": "string", "example": "usd", "externalDocs": { "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes", "description": "See a list of codes." } }, "currency": { "description": "The details of the currency this payment collection is associated with.", "x-expandable": "currency", "nullable": true, "$ref": "#/components/schemas/Currency" }, "payment_sessions": { "description": "The details of the payment sessions created as part of the payment collection.", "type": "array", "x-expandable": "payment_sessions", "items": { "$ref": "#/components/schemas/PaymentSession" } }, "payments": { "description": "The details of the payments created as part of the payment collection.", "type": "array", "x-expandable": "payments", "items": { "$ref": "#/components/schemas/Payment" } }, "created_by": { "description": "The ID of the user that created the payment collection.", "type": "string" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "PaymentProvider": { "title": "Payment Provider", "description": "A payment provider represents a payment service installed in the Medusa backend, either through a plugin or backend customizations. It holds the payment service's installation status.", "type": "object", "required": [ "id", "is_installed" ], "properties": { "id": { "description": "The ID of the payment provider as given by the payment service.", "type": "string", "example": "manual" }, "is_installed": { "description": "Whether the payment service is installed in the current version. If a payment service is no longer installed, the `is_installed` attribute is set to `false`.", "type": "boolean", "default": true } } }, "PaymentSession": { "title": "Payment Session", "description": "A Payment Session is 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, which 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 payment processing such as capture or refund. Payment sessions can also be used as part of payment collections.", "type": "object", "required": [ "amount", "cart_id", "created_at", "data", "id", "is_initiated", "is_selected", "idempotency_key", "payment_authorized_at", "provider_id", "status", "updated_at" ], "properties": { "id": { "description": "The payment session's ID", "type": "string", "example": "ps_01G901XNSRM2YS3ASN9H5KG3FZ" }, "cart_id": { "description": "The ID of the cart that the payment session was created for.", "nullable": true, "type": "string", "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63" }, "cart": { "description": "The details of the cart that the payment session was created for.", "x-expandable": "cart", "nullable": true, "$ref": "#/components/schemas/Cart" }, "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.", "nullable": true, "type": "boolean", "example": true }, "is_initiated": { "description": "A flag to indicate if a communication with the third party provider has been initiated.", "type": "boolean", "default": false, "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": { "description": "Randomly generated key used to continue the completion of a cart in case of failure.", "nullable": true, "type": "string", "externalDocs": { "url": "https://docs.medusajs.com/development/idempotency-key/overview.md", "description": "Learn more how to use the idempotency key." } }, "amount": { "description": "The amount that the Payment Session has been authorized for.", "nullable": true, "type": "integer", "example": 100 }, "payment_authorized_at": { "description": "The date with timezone at which the Payment Session was authorized.", "nullable": true, "type": "string", "format": "date-time" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" } } }, "PriceList": { "title": "Price List", "description": "A Price List represents a set of prices that override the default price for one or more product variants.", "type": "object", "required": [ "created_at", "deleted_at", "description", "ends_at", "id", "name", "starts_at", "status", "type", "updated_at" ], "properties": { "id": { "description": "The price list's ID", "type": "string", "example": "pl_01G8X3CKJXCG5VXVZ87H9KC09W" }, "name": { "description": "The price list's name", "type": "string", "example": "VIP Prices" }, "description": { "description": "The price list's description", "type": "string", "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.", "nullable": true, "type": "string", "format": "date-time" }, "ends_at": { "description": "The date with timezone that the Price List stops being valid.", "nullable": true, "type": "string", "format": "date-time" }, "customer_groups": { "description": "The details of the customer groups that the Price List can apply to.", "type": "array", "x-expandable": "customer_groups", "items": { "$ref": "#/components/schemas/CustomerGroup" } }, "prices": { "description": "The prices that belong to the price list, represented as a Money Amount.", "type": "array", "x-expandable": "prices", "items": { "$ref": "#/components/schemas/MoneyAmount" } }, "includes_tax": { "description": "Whether the price list prices include tax", "type": "boolean", "x-featureFlag": "tax_inclusive_pricing", "default": false }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" } } }, "PricedProduct": { "title": "Priced Product", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Product" }, { "type": "object", "properties": { "variants": { "type": "array", "items": { "$ref": "#/components/schemas/PricedVariant" } } } } ] }, "PricedShippingOption": { "title": "Priced Shipping Option", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ShippingOption" }, { "type": "object", "properties": { "price_incl_tax": { "type": "number", "description": "Price including taxes" }, "tax_rates": { "type": "array", "description": "An array of applied tax rates", "items": { "type": "object", "properties": { "rate": { "type": "number", "description": "The tax rate value" }, "name": { "type": "string", "description": "The name of the tax rate" }, "code": { "type": "string", "description": "The code of the tax rate" } } } }, "tax_amount": { "type": "number", "description": "The taxes applied." } } } ] }, "PricedVariant": { "title": "Priced Product Variant", "type": "object", "allOf": [ { "$ref": "#/components/schemas/ProductVariant" }, { "type": "object", "properties": { "original_price": { "type": "number", "description": "The original price of the variant without any discounted prices applied." }, "calculated_price": { "type": "number", "description": "The calculated price of the variant. Can be a discounted price." }, "original_price_incl_tax": { "type": "number", "description": "The original price of the variant including taxes." }, "calculated_price_incl_tax": { "type": "number", "description": "The calculated price of the variant including taxes." }, "original_tax": { "type": "number", "description": "The taxes applied on the original price." }, "calculated_tax": { "type": "number", "description": "The taxes applied on the calculated price." }, "tax_rates": { "type": "array", "description": "An array of applied tax rates", "items": { "type": "object", "properties": { "rate": { "type": "number", "description": "The tax rate value" }, "name": { "type": "string", "description": "The name of the tax rate" }, "code": { "type": "string", "description": "The code of the tax rate" } } } } } } ] }, "Product": { "title": "Product", "description": "A product is a saleable item that holds general information such as name or description. It must include at least one Product Variant, where each product variant defines different options to purchase the product with (for example, different sizes or colors). The prices and inventory of the product are defined on the variant level.", "type": "object", "required": [ "collection_id", "created_at", "deleted_at", "description", "discountable", "external_id", "handle", "height", "hs_code", "id", "is_giftcard", "length", "material", "metadata", "mid_code", "origin_country", "profile_id", "status", "subtitle", "type_id", "thumbnail", "title", "updated_at", "weight", "width" ], "properties": { "id": { "description": "The product's ID", "type": "string", "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.", "nullable": true, "type": "string" }, "description": { "description": "A short description of the Product.", "nullable": true, "type": "string", "example": "Every programmer's best friend." }, "handle": { "description": "A unique identifier for the Product (e.g. for slug structure).", "nullable": true, "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": "The details of the product's images.", "type": "array", "x-expandable": "images", "items": { "$ref": "#/components/schemas/Image" } }, "thumbnail": { "description": "A URL to an image file that can be used to identify the Product.", "nullable": true, "type": "string", "format": "uri" }, "options": { "description": "The details of the Product Options that are defined for the Product. The product's variants will have a unique combination of values of the product's options.", "type": "array", "x-expandable": "options", "items": { "$ref": "#/components/schemas/ProductOption" } }, "variants": { "description": "The details of the Product Variants that belong to the Product. Each will have a unique combination of values of the product's options.", "type": "array", "x-expandable": "variants", "items": { "$ref": "#/components/schemas/ProductVariant" } }, "categories": { "description": "The details of the product categories that this product belongs to.", "type": "array", "x-expandable": "categories", "x-featureFlag": "product_categories", "items": { "$ref": "#/components/schemas/ProductCategory" } }, "profile_id": { "description": "The ID of the shipping profile that the product belongs to. The shipping profile has a set of defined shipping options that can be used to fulfill the product.", "type": "string", "example": "sp_01G1G5V239ENSZ5MV4JAR737BM" }, "profile": { "description": "The details of the shipping profile that the product belongs to. The shipping profile has a set of defined shipping options that can be used to fulfill the product.", "x-expandable": "profile", "nullable": true, "$ref": "#/components/schemas/ShippingProfile" }, "profiles": { "description": "Available if the relation `profiles` is expanded.", "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/ShippingProfile" } }, "weight": { "description": "The weight of the Product Variant. May be used in shipping rate calculations.", "nullable": true, "type": "number", "example": null }, "length": { "description": "The length of the Product Variant. May be used in shipping rate calculations.", "nullable": true, "type": "number", "example": null }, "height": { "description": "The height of the Product Variant. May be used in shipping rate calculations.", "nullable": true, "type": "number", "example": null }, "width": { "description": "The width of the Product Variant. May be used in shipping rate calculations.", "nullable": true, "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.", "nullable": true, "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.", "nullable": true, "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.", "nullable": true, "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.", "nullable": true, "type": "string", "example": null }, "collection_id": { "description": "The ID of the product collection that the product belongs to.", "nullable": true, "type": "string", "example": "pcol_01F0YESBFAZ0DV6V831JXWH0BG" }, "collection": { "description": "The details of the product collection that the product belongs to.", "x-expandable": "collection", "nullable": true, "$ref": "#/components/schemas/ProductCollection" }, "type_id": { "description": "The ID of the product type that the product belongs to.", "nullable": true, "type": "string", "example": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A" }, "type": { "description": "The details of the product type that the product belongs to.", "x-expandable": "type", "nullable": true, "$ref": "#/components/schemas/ProductType" }, "tags": { "description": "The details of the product tags used in this product.", "type": "array", "x-expandable": "type", "items": { "$ref": "#/components/schemas/ProductTag" } }, "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", "nullable": true, "type": "string", "example": null }, "sales_channels": { "description": "The details of the sales channels this product is available in.", "type": "array", "x-expandable": "sales_channels", "items": { "$ref": "#/components/schemas/SalesChannel" } }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "ProductCategory": { "title": "Product Category", "description": "A product category can be used to categorize products into a hierarchy of categories.", "x-resourceId": "ProductCategory", "x-featureFlag": "product_categories", "type": "object", "required": [ "category_children", "created_at", "handle", "id", "is_active", "is_internal", "mpath", "name", "parent_category_id", "updated_at" ], "properties": { "id": { "description": "The product category's ID", "type": "string", "example": "pcat_01G2SG30J8C85S4A5CHM2S1NS2" }, "name": { "description": "The product category's name", "type": "string", "example": "Regular Fit" }, "handle": { "description": "A unique string that identifies the Product Category - can for example be used in slug structures.", "type": "string", "example": "regular-fit" }, "mpath": { "description": "A string for Materialized Paths - used for finding ancestors and descendents", "nullable": true, "type": "string", "example": "pcat_id1.pcat_id2.pcat_id3" }, "is_internal": { "type": "boolean", "description": "A flag to make product category an internal category for admins", "default": false }, "is_active": { "type": "boolean", "description": "A flag to make product category visible/hidden in the store front", "default": false }, "rank": { "type": "integer", "description": "An integer that depicts the rank of category in a tree node", "default": 0 }, "category_children": { "description": "The details of the category's children.", "type": "array", "x-expandable": "category_children", "items": { "$ref": "#/components/schemas/ProductCategory" } }, "parent_category_id": { "description": "The ID of the parent category.", "nullable": true, "type": "string", "default": null }, "parent_category": { "description": "The details of the parent of this category.", "x-expandable": "parent_category", "nullable": true, "$ref": "#/components/schemas/ProductCategory" }, "products": { "description": "The details of the products that belong to this category.", "type": "array", "x-expandable": "products", "items": { "$ref": "#/components/schemas/Product" } }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" } } }, "ProductCollection": { "title": "Product Collection", "description": "A Product Collection allows grouping together products for promotional purposes. For example, an admin can create a Summer collection, add products to it, and showcase it on the storefront.", "type": "object", "required": [ "created_at", "deleted_at", "handle", "id", "metadata", "title", "updated_at" ], "properties": { "id": { "description": "The product collection's ID", "type": "string", "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.", "nullable": true, "type": "string", "example": "summer-collection" }, "products": { "description": "The details of the products that belong to this product collection.", "type": "array", "x-expandable": "products", "items": { "$ref": "#/components/schemas/Product" } }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "ProductOption": { "title": "Product Option", "description": "A Product Option defines properties that may vary between different variants of a Product. Common Product Options are \"Size\" and \"Color\". Admins are free to create any product options.", "type": "object", "required": [ "created_at", "deleted_at", "id", "metadata", "product_id", "title", "updated_at" ], "properties": { "id": { "description": "The product option's ID", "type": "string", "example": "opt_01F0YESHQBZVKCEXJ24BS6PCX3" }, "title": { "description": "The title that the Product Option is defined by (e.g. `Size`).", "type": "string", "example": "Size" }, "values": { "description": "The details of the values of the product option.", "type": "array", "x-expandable": "values", "items": { "$ref": "#/components/schemas/ProductOptionValue" } }, "product_id": { "description": "The ID of the product that this product option belongs to.", "type": "string", "example": "prod_01G1G5V2MBA328390B5AXJ610F" }, "product": { "description": "The details of the product that this product option belongs to.", "x-expandable": "product", "nullable": true, "$ref": "#/components/schemas/Product" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "ProductOptionValue": { "title": "Product Option Value", "description": "An option value is one of the possible values of a Product Option. Product Variants specify a unique combination of product option values.", "type": "object", "required": [ "created_at", "deleted_at", "id", "metadata", "option_id", "updated_at", "value", "variant_id" ], "properties": { "id": { "description": "The product option value's ID", "type": "string", "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 belongs to.", "type": "string", "example": "opt_01F0YESHQBZVKCEXJ24BS6PCX3" }, "option": { "description": "The details of the product option that the Product Option Value belongs to.", "x-expandable": "option", "nullable": true, "$ref": "#/components/schemas/ProductOption" }, "variant_id": { "description": "The ID of the product variant that uses this product option value.", "type": "string", "example": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6" }, "variant": { "description": "The details of the product variant that uses this product option value.", "x-expandable": "variant", "nullable": true, "$ref": "#/components/schemas/ProductVariant" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "ProductTag": { "title": "Product Tag", "description": "A Product Tag can be added to Products for easy filtering and grouping.", "type": "object", "required": [ "created_at", "deleted_at", "id", "metadata", "updated_at", "value" ], "properties": { "id": { "description": "The product tag's ID", "type": "string", "example": "ptag_01G8K2MTMG9168F2B70S1TAVK3" }, "value": { "description": "The value that the Product Tag represents", "type": "string", "example": "Pants" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "ProductTaxRate": { "title": "Product Tax Rate", "description": "This represents the association between a tax rate and a product to indicate that the product is taxed in a way different than the default.", "type": "object", "required": [ "created_at", "metadata", "product_id", "rate_id", "updated_at" ], "properties": { "product_id": { "description": "The ID of the Product", "type": "string", "example": "prod_01G1G5V2MBA328390B5AXJ610F" }, "product": { "description": "The details of the product.", "x-expandable": "product", "nullable": true, "$ref": "#/components/schemas/Product" }, "rate_id": { "description": "The ID of the Tax Rate", "type": "string", "example": "txr_01G8XDBAWKBHHJRKH0AV02KXBR" }, "tax_rate": { "description": "The details of the tax rate.", "x-expandable": "tax_rate", "nullable": true, "$ref": "#/components/schemas/TaxRate" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "ProductType": { "title": "Product Type", "description": "A Product Type can be added to Products for filtering and reporting purposes.", "type": "object", "required": [ "created_at", "deleted_at", "id", "metadata", "updated_at", "value" ], "properties": { "id": { "description": "The product type's ID", "type": "string", "example": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A" }, "value": { "description": "The value that the Product Type represents.", "type": "string", "example": "Clothing" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "ProductTypeTaxRate": { "title": "Product Type Tax Rate", "description": "This represents the association between a tax rate and a product type to indicate that the product type is taxed in a different way than the default.", "type": "object", "required": [ "created_at", "metadata", "product_type_id", "rate_id", "updated_at" ], "properties": { "product_type_id": { "description": "The ID of the Product type", "type": "string", "example": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A" }, "product_type": { "description": "The details of the product type.", "x-expandable": "product_type", "nullable": true, "$ref": "#/components/schemas/ProductType" }, "rate_id": { "description": "The id of the Tax Rate", "type": "string", "example": "txr_01G8XDBAWKBHHJRKH0AV02KXBR" }, "tax_rate": { "description": "The details of the tax rate.", "x-expandable": "tax_rate", "nullable": true, "$ref": "#/components/schemas/TaxRate" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "ProductVariant": { "title": "Product Variant", "description": "A Product Variant represents 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. A product must at least have one product variant.", "type": "object", "required": [ "allow_backorder", "barcode", "created_at", "deleted_at", "ean", "height", "hs_code", "id", "inventory_quantity", "length", "manage_inventory", "material", "metadata", "mid_code", "origin_country", "product_id", "sku", "title", "upc", "updated_at", "weight", "width" ], "properties": { "id": { "description": "The product variant's ID", "type": "string", "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": "The details of the product that the product variant belongs to.", "x-expandable": "product", "nullable": true, "$ref": "#/components/schemas/Product" }, "prices": { "description": "The details of the prices of the Product Variant, each represented as a Money Amount. Each Money Amount represents a price in a given currency or a specific Region.", "type": "array", "x-expandable": "prices", "items": { "$ref": "#/components/schemas/MoneyAmount" } }, "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.", "nullable": true, "type": "string", "example": "shirt-123" }, "barcode": { "description": "A generic field for a GTIN number that can be used to identify the Product Variant.", "nullable": true, "type": "string", "example": null }, "ean": { "description": "An EAN barcode number that can be used to identify the Product Variant.", "nullable": true, "type": "string", "example": null }, "upc": { "description": "A UPC barcode number that can be used to identify the Product Variant.", "nullable": true, "type": "string", "example": null }, "variant_rank": { "description": "The ranking of this variant", "nullable": true, "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.", "nullable": true, "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.", "nullable": true, "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.", "nullable": true, "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.", "nullable": true, "type": "string", "example": null }, "weight": { "description": "The weight of the Product Variant. May be used in shipping rate calculations.", "nullable": true, "type": "number", "example": null }, "length": { "description": "The length of the Product Variant. May be used in shipping rate calculations.", "nullable": true, "type": "number", "example": null }, "height": { "description": "The height of the Product Variant. May be used in shipping rate calculations.", "nullable": true, "type": "number", "example": null }, "width": { "description": "The width of the Product Variant. May be used in shipping rate calculations.", "nullable": true, "type": "number", "example": null }, "options": { "description": "The details of the product options that this product variant defines values for.", "type": "array", "x-expandable": "options", "items": { "$ref": "#/components/schemas/ProductOptionValue" } }, "inventory_items": { "description": "The details inventory items of the product variant.", "type": "array", "x-expandable": "inventory_items", "items": { "$ref": "#/components/schemas/ProductVariantInventoryItem" } }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } }, "purchasable": { "description": "Only used with the inventory modules.\nA boolean value indicating whether the Product Variant is purchasable.\nA variant is purchasable if:\n - inventory is not managed\n - it has no inventory items\n - it is in stock\n - it is backorderable.\n", "type": "boolean" } } }, "ProductVariantInventoryItem": { "title": "Product Variant Inventory Item", "description": "A Product Variant Inventory Item links variants with inventory items and denotes the required quantity of the variant.", "type": "object", "required": [ "created_at", "deleted_at", "id", "inventory_item_id", "required_quantity", "updated_at", "variant_id" ], "properties": { "id": { "description": "The product variant inventory item's ID", "type": "string", "example": "pvitem_01G8X9A7ESKAJXG2H0E6F1MW7A" }, "inventory_item_id": { "description": "The id of the inventory item", "type": "string" }, "variant_id": { "description": "The id of the variant.", "type": "string" }, "variant": { "description": "The details of the product variant.", "x-expandable": "variant", "nullable": true, "$ref": "#/components/schemas/ProductVariant" }, "required_quantity": { "description": "The quantity of an inventory item required for the variant.", "type": "integer", "default": 1 }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" } } }, "PublishableApiKey": { "title": "Publishable API key", "description": "A Publishable API key defines scopes that resources are available in. Then, it can be used in request to infer the resources without having to directly pass them. For example, a publishable API key can be associated with one or more sales channels. Then, when the publishable API key is passed in the header of a request, it is inferred what sales channel is being used without having to pass the sales channel as a query or body parameter of the request. Publishable API keys can only be used with sales channels, at the moment.", "type": "object", "required": [ "created_at", "created_by", "id", "revoked_by", "revoked_at", "title", "updated_at" ], "properties": { "id": { "description": "The key's ID", "type": "string", "example": "pk_01G1G5V27GYX4QXNARRQCW1N8T" }, "created_by": { "description": "The unique identifier of the user that created the key.", "nullable": true, "type": "string", "example": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V" }, "revoked_by": { "description": "The unique identifier of the user that revoked the key.", "nullable": true, "type": "string", "example": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V" }, "revoked_at": { "description": "The date with timezone at which the key was revoked.", "nullable": true, "type": "string", "format": "date-time" }, "title": { "description": "The key's title.", "type": "string" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" } } }, "PublishableApiKeySalesChannel": { "title": "Publishable API Key Sales Channel", "description": "This represents the association between the Publishable API keys and Sales Channels", "type": "object", "required": [ "publishable_key_id", "sales_channel_id" ], "properties": { "sales_channel_id": { "description": "The sales channel's ID", "type": "string", "example": "sc_01G1G5V21KADXNGH29BJMAJ4B4" }, "publishable_key_id": { "description": "The publishable API key's ID", "type": "string", "example": "pak_01G1G5V21KADXNGH29BJMAJ4B4" } } }, "Refund": { "title": "Refund", "description": "A refund represents 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 an admin for an order.", "type": "object", "required": [ "amount", "created_at", "id", "idempotency_key", "metadata", "note", "order_id", "payment_id", "reason", "updated_at" ], "properties": { "id": { "description": "The refund's ID", "type": "string", "example": "ref_01G1G5V27GYX4QXNARRQCW1N8T" }, "order_id": { "description": "The ID of the order this refund was created for.", "nullable": true, "type": "string", "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK" }, "order": { "description": "The details of the order this refund was created for.", "x-expandable": "order", "nullable": true, "$ref": "#/components/schemas/Order" }, "payment_id": { "description": "The payment's ID, if available.", "nullable": true, "type": "string", "example": "pay_01G8ZCC5W42ZNY842124G7P5R9" }, "payment": { "description": "The details of the payment associated with the refund.", "x-expandable": "payment", "nullable": true, "$ref": "#/components/schemas/Payment" }, "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.", "nullable": true, "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": { "description": "Randomly generated key used to continue the completion of the refund in case of failure.", "nullable": true, "type": "string", "externalDocs": { "url": "https://docs.medusajs.com/development/idempotency-key/overview.md", "description": "Learn more how to use the idempotency key." } }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "Region": { "title": "Region", "description": "A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.", "type": "object", "required": [ "automatic_taxes", "created_at", "currency_code", "deleted_at", "gift_cards_taxable", "id", "metadata", "name", "tax_code", "tax_provider_id", "tax_rate", "updated_at" ], "properties": { "id": { "description": "The region's ID", "type": "string", "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 used in the region.", "type": "string", "example": "usd", "externalDocs": { "url": "https://en.wikipedia.org/wiki/ISO_4217#Active_codes", "description": "See a list of codes." } }, "currency": { "description": "The details of the currency used in the region.", "x-expandable": "currency", "nullable": true, "$ref": "#/components/schemas/Currency" }, "tax_rate": { "description": "The tax rate that should be charged on purchases in the Region.", "type": "number", "example": 0 }, "tax_rates": { "description": "The details of the tax rates used in the region, aside from the default rate.", "type": "array", "x-expandable": "tax_rates", "items": { "$ref": "#/components/schemas/TaxRate" } }, "tax_code": { "description": "The tax code used on purchases in the Region. This may be used by other systems for accounting purposes.", "nullable": true, "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 details of the countries included in this region.", "type": "array", "x-expandable": "countries", "items": { "$ref": "#/components/schemas/Country" } }, "tax_provider_id": { "description": "The ID of the tax provider used in this region", "nullable": true, "type": "string", "example": null }, "tax_provider": { "description": "The details of the tax provider used in the region.", "x-expandable": "tax_provider", "nullable": true, "$ref": "#/components/schemas/TaxProvider" }, "payment_providers": { "description": "The details of the payment providers that can be used to process payments in the region.", "type": "array", "x-expandable": "payment_providers", "items": { "$ref": "#/components/schemas/PaymentProvider" } }, "fulfillment_providers": { "description": "The details of the fulfillment providers that can be used to fulfill items of orders and similar resources in the region.", "type": "array", "x-expandable": "fulfillment_providers", "items": { "$ref": "#/components/schemas/FulfillmentProvider" } }, "includes_tax": { "description": "Whether the prices for the region include tax", "type": "boolean", "x-featureFlag": "tax_inclusive_pricing", "default": false }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "ReservationItemDTO": { "title": "Reservation item", "description": "Represents a reservation of an inventory item at a stock location", "type": "object", "required": [ "id", "location_id", "inventory_item_id", "quantity" ], "properties": { "id": { "description": "The id of the reservation item", "type": "string" }, "location_id": { "description": "The id of the location of the reservation", "type": "string" }, "inventory_item_id": { "description": "The id of the inventory item the reservation relates to", "type": "string" }, "description": { "description": "Description of the reservation item", "type": "string" }, "created_by": { "description": "UserId of user who created the reservation item", "type": "string" }, "quantity": { "description": "The id of the reservation item", "type": "number" }, "metadata": { "type": "object", "description": "An optional key-value map with additional details", "example": { "car": "white" } }, "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" } } }, "Return": { "title": "Return", "description": "A Return holds information about Line Items that a Customer wishes to send back, along with how the items will be returned. Returns can also be used as part of a Swap or a Claim.", "type": "object", "required": [ "claim_order_id", "created_at", "id", "idempotency_key", "location_id", "metadata", "no_notification", "order_id", "received_at", "refund_amount", "shipping_data", "status", "swap_id", "updated_at" ], "properties": { "id": { "description": "The return's ID", "type": "string", "example": "ret_01F0YET7XPCMF8RZ0Y151NZV2V" }, "status": { "description": "Status of the Return.", "type": "string", "enum": [ "requested", "received", "requires_action", "canceled" ], "default": "requested" }, "items": { "description": "The details of the items that the customer is returning.", "type": "array", "x-expandable": "items", "items": { "$ref": "#/components/schemas/ReturnItem" } }, "swap_id": { "description": "The ID of the swap that the return may belong to.", "nullable": true, "type": "string", "example": null }, "swap": { "description": "The details of the swap that the return may belong to.", "x-expandable": "swap", "nullable": true, "$ref": "#/components/schemas/Swap" }, "claim_order_id": { "description": "The ID of the claim that the return may belong to.", "nullable": true, "type": "string", "example": null }, "claim_order": { "description": "The details of the claim that the return may belong to.", "x-expandable": "claim_order", "nullable": true, "$ref": "#/components/schemas/ClaimOrder" }, "order_id": { "description": "The ID of the order that the return was created for.", "nullable": true, "type": "string", "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK" }, "order": { "description": "The details of the order that the return was created for.", "x-expandable": "order", "nullable": true, "$ref": "#/components/schemas/Order" }, "shipping_method": { "description": "The details of the Shipping Method that will be used to send the Return back. Can be null if the Customer will handle the return shipment themselves.", "x-expandable": "shipping_method", "nullable": true, "$ref": "#/components/schemas/ShippingMethod" }, "shipping_data": { "description": "Data about the return shipment as provided by the Fulfilment Provider that handles the return shipment.", "nullable": true, "type": "object", "example": {} }, "location_id": { "description": "The ID of the stock location the return will be added back.", "nullable": true, "type": "string", "example": "sloc_01G8TJSYT9M6AVS5N4EMNFS1EK" }, "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.", "nullable": true, "type": "boolean", "example": false }, "idempotency_key": { "description": "Randomly generated key used to continue the completion of the return in case of failure.", "nullable": true, "type": "string", "externalDocs": { "url": "https://docs.medusajs.com/development/idempotency-key/overview.md", "description": "Learn more how to use the idempotency key." } }, "received_at": { "description": "The date with timezone at which the return was received.", "nullable": true, "type": "string", "format": "date-time" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "ReturnItem": { "title": "Return Item", "description": "A return item represents a line item in an order that is to be returned. It includes details related to the return and the reason behind it.", "type": "object", "required": [ "is_requested", "item_id", "metadata", "note", "quantity", "reason_id", "received_quantity", "requested_quantity", "return_id" ], "properties": { "return_id": { "description": "The ID of the Return that the Return Item belongs to.", "type": "string", "example": "ret_01F0YET7XPCMF8RZ0Y151NZV2V" }, "item_id": { "description": "The ID of the Line Item that the Return Item references.", "type": "string", "example": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN" }, "return_order": { "description": "Details of the Return that the Return Item belongs to.", "x-expandable": "return_order", "nullable": true, "$ref": "#/components/schemas/Return" }, "item": { "description": "The details of the line item in the original order to be returned.", "x-expandable": "item", "nullable": true, "$ref": "#/components/schemas/LineItem" }, "quantity": { "description": "The quantity of the Line Item to be returned.", "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.", "nullable": true, "type": "integer", "example": 1 }, "received_quantity": { "description": "The quantity that was received in the warehouse.", "nullable": true, "type": "integer", "example": 1 }, "reason_id": { "description": "The ID of the reason for returning the item.", "nullable": true, "type": "string", "example": "rr_01G8X82GCCV2KSQHDBHSSAH5TQ" }, "reason": { "description": "The details of the reason for returning the item.", "x-expandable": "reason", "nullable": true, "$ref": "#/components/schemas/ReturnReason" }, "note": { "description": "An optional note with additional details about the Return.", "nullable": true, "type": "string", "example": "I didn't like it." }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "ReturnReason": { "title": "Return Reason", "description": "A Return Reason is a value defined by an admin. It can be used on Return Items in order to indicate why a Line Item was returned.", "type": "object", "required": [ "created_at", "deleted_at", "description", "id", "label", "metadata", "parent_return_reason_id", "updated_at", "value" ], "properties": { "id": { "description": "The return reason's ID", "type": "string", "example": "rr_01G8X82GCCV2KSQHDBHSSAH5TQ" }, "value": { "description": "The value to identify the reason by.", "type": "string", "example": "damaged" }, "label": { "description": "A text that can be displayed to the Customer as a reason.", "type": "string", "example": "Damaged goods" }, "description": { "description": "A description of the Reason.", "nullable": true, "type": "string", "example": "Items that are damaged" }, "parent_return_reason_id": { "description": "The ID of the parent reason.", "nullable": true, "type": "string", "example": null }, "parent_return_reason": { "description": "The details of the parent reason.", "x-expandable": "parent_return_reason", "nullable": true, "$ref": "#/components/schemas/ReturnReason" }, "return_reason_children": { "description": "The details of the child reasons.", "x-expandable": "return_reason_children", "$ref": "#/components/schemas/ReturnReason" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "SalesChannel": { "title": "Sales Channel", "description": "A Sales Channel is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.", "type": "object", "required": [ "created_at", "deleted_at", "description", "id", "is_disabled", "name", "updated_at" ], "properties": { "id": { "description": "The sales channel's ID", "type": "string", "example": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A" }, "name": { "description": "The name of the sales channel.", "type": "string", "example": "Market" }, "description": { "description": "The description of the sales channel.", "nullable": true, "type": "string", "example": "Multi-vendor market" }, "is_disabled": { "description": "Specify if the sales channel is enabled or disabled.", "type": "boolean", "default": false }, "locations": { "description": "The details of the stock locations related to the sales channel.", "type": "array", "x-expandable": "locations", "items": { "$ref": "#/components/schemas/SalesChannelLocation" } }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "SalesChannelLocation": { "title": "Sales Channel Stock Location", "description": "This represents the association between a sales channel and a stock locations.", "type": "object", "required": [ "created_at", "deleted_at", "id", "location_id", "sales_channel_id", "updated_at" ], "properties": { "id": { "description": "The Sales Channel Stock Location's ID", "type": "string", "example": "scloc_01G8X9A7ESKAJXG2H0E6F1MW7A" }, "sales_channel_id": { "description": "The ID of the Sales Channel", "type": "string", "example": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A" }, "location_id": { "description": "The ID of the Location Stock.", "type": "string" }, "sales_channel": { "description": "The details of the sales channel the location is associated with.", "x-expandable": "sales_channel", "nullable": true, "$ref": "#/components/schemas/SalesChannel" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" } } }, "ShippingMethod": { "title": "Shipping Method", "description": "A Shipping Method represents a way in which an Order or Return can be shipped. Shipping Methods are created from a Shipping Option, but may contain additional details that can be necessary for the Fulfillment Provider to handle the shipment. If the shipping method is created for a return, it may be associated with a claim or a swap that the return is part of.", "type": "object", "required": [ "cart_id", "claim_order_id", "data", "id", "order_id", "price", "return_id", "shipping_option_id", "swap_id" ], "properties": { "id": { "description": "The shipping method's ID", "type": "string", "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" }, "order_id": { "description": "The ID of the order that the shipping method is used in.", "nullable": true, "type": "string", "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK" }, "order": { "description": "The details of the order that the shipping method is used in.", "x-expandable": "order", "nullable": true, "$ref": "#/components/schemas/Order" }, "claim_order_id": { "description": "The ID of the claim that the shipping method is used in.", "nullable": true, "type": "string", "example": null }, "claim_order": { "description": "The details of the claim that the shipping method is used in.", "x-expandable": "claim_order", "nullable": true, "$ref": "#/components/schemas/ClaimOrder" }, "cart_id": { "description": "The ID of the cart that the shipping method is used in.", "nullable": true, "type": "string", "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63" }, "cart": { "description": "The details of the cart that the shipping method is used in.", "x-expandable": "cart", "nullable": true, "$ref": "#/components/schemas/Cart" }, "swap_id": { "description": "The ID of the swap that the shipping method is used in.", "nullable": true, "type": "string", "example": null }, "swap": { "description": "The details of the swap that the shipping method is used in.", "x-expandable": "swap", "nullable": true, "$ref": "#/components/schemas/Swap" }, "return_id": { "description": "The ID of the return that the shipping method is used in.", "nullable": true, "type": "string", "example": null }, "return_order": { "description": "The details of the return that the shipping method is used in.", "x-expandable": "return_order", "nullable": true, "$ref": "#/components/schemas/Return" }, "shipping_option": { "description": "The details of the shipping option the method was created from.", "x-expandable": "shipping_option", "nullable": true, "$ref": "#/components/schemas/ShippingOption" }, "tax_lines": { "description": "The details of the tax lines applied on the shipping method.", "type": "array", "x-expandable": "tax_lines", "items": { "$ref": "#/components/schemas/ShippingMethodTaxLine" } }, "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": {} }, "includes_tax": { "description": "Whether the shipping method price include tax", "type": "boolean", "x-featureFlag": "tax_inclusive_pricing", "default": false }, "subtotal": { "description": "The subtotal of the shipping", "type": "integer", "example": 8000 }, "total": { "description": "The total amount of the shipping", "type": "integer", "example": 8200 }, "tax_total": { "description": "The total of tax", "type": "integer", "example": 0 } } }, "ShippingMethodTaxLine": { "title": "Shipping Method Tax Line", "description": "A Shipping Method Tax Line represents the taxes applied on a shipping method in a cart.", "type": "object", "required": [ "code", "created_at", "id", "shipping_method_id", "metadata", "name", "rate", "updated_at" ], "properties": { "id": { "description": "The line item tax line's ID", "type": "string", "example": "smtl_01G1G5V2DRX1SK6NQQ8VVX4HQ8" }, "code": { "description": "A code to identify the tax type by", "nullable": true, "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 }, "shipping_method_id": { "description": "The ID of the line item", "type": "string", "example": "sm_01F0YET7DR2E7CYVSDHM593QG2" }, "shipping_method": { "description": "The details of the associated shipping method.", "x-expandable": "shipping_method", "nullable": true, "$ref": "#/components/schemas/ShippingMethod" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "ShippingOption": { "title": "Shipping Option", "description": "A Shipping Option represents 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.", "type": "object", "required": [ "admin_only", "amount", "created_at", "data", "deleted_at", "id", "is_return", "metadata", "name", "price_type", "profile_id", "provider_id", "region_id", "updated_at" ], "properties": { "id": { "description": "The shipping option's ID", "type": "string", "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": { "description": "The ID of the region this shipping option can be used in.", "type": "string", "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" }, "region": { "description": "The details of the region this shipping option can be used in.", "x-expandable": "region", "nullable": true, "$ref": "#/components/schemas/Region" }, "profile_id": { "description": "The ID of the Shipping Profile that the shipping option belongs to.", "type": "string", "example": "sp_01G1G5V239ENSZ5MV4JAR737BM" }, "profile": { "description": "The details of the shipping profile that the shipping option belongs to.", "x-expandable": "profile", "nullable": true, "$ref": "#/components/schemas/ShippingProfile" }, "provider_id": { "description": "The ID of the fulfillment provider that will be used to later to process the shipping method created from this shipping option and its fulfillments.", "type": "string", "example": "manual" }, "provider": { "description": "The details of the fulfillment provider that will be used to later to process the shipping method created from this shipping option and its fulfillments.", "x-expandable": "provider", "nullable": true, "$ref": "#/components/schemas/FulfillmentProvider" }, "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`.", "nullable": true, "type": "integer", "example": 200 }, "is_return": { "description": "Flag to indicate if the Shipping Option can be used for Return shipments.", "type": "boolean", "default": false }, "admin_only": { "description": "Flag to indicate if the Shipping Option usage is restricted to admin users.", "type": "boolean", "default": false }, "requirements": { "description": "The details of the requirements that must be satisfied for the Shipping Option to be available for usage in a Cart.", "type": "array", "x-expandable": "requirements", "items": { "$ref": "#/components/schemas/ShippingOptionRequirement" } }, "data": { "description": "The data needed for the Fulfillment Provider to identify the Shipping Option.", "type": "object", "example": {} }, "includes_tax": { "description": "Whether the shipping option price include tax", "type": "boolean", "x-featureFlag": "tax_inclusive_pricing", "default": false }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "ShippingOptionRequirement": { "title": "Shipping Option Requirement", "description": "A shipping option requirement defines conditions that a Cart must satisfy for the Shipping Option to be available for usage in the Cart.", "type": "object", "required": [ "amount", "deleted_at", "id", "shipping_option_id", "type" ], "properties": { "id": { "description": "The shipping option requirement's ID", "type": "string", "example": "sor_01G1G5V29AB4CTNDRFSRWSRKWD" }, "shipping_option_id": { "description": "The ID of the shipping option that the requirements belong to.", "type": "string", "example": "so_01G1G5V27GYX4QXNARRQCW1N8T" }, "shipping_option": { "description": "The details of the shipping option that the requirements belong to.", "x-expandable": "shipping_option", "nullable": true, "$ref": "#/components/schemas/ShippingOption" }, "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": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" } } }, "ShippingProfile": { "title": "Shipping Profile", "description": "A Shipping Profile has a set of defined Shipping Options that can be used to fulfill a given set of Products. For example, gift cards are shipped differently than physical products, so a shipping profile with the type `gift_card` groups together the shipping options that can only be used for gift cards.", "type": "object", "required": [ "created_at", "deleted_at", "id", "metadata", "name", "type", "updated_at" ], "properties": { "id": { "description": "The shipping profile's ID", "type": "string", "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 details of the products that the Shipping Profile defines Shipping Options for. Available if the relation `products` is expanded.", "type": "array", "x-expandable": "products", "items": { "$ref": "#/components/schemas/Product" } }, "shipping_options": { "description": "The details of the shipping options that can be used to create shipping methods for the Products in the Shipping Profile.", "type": "array", "x-expandable": "shipping_options", "items": { "$ref": "#/components/schemas/ShippingOption" } }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "ShippingTaxRate": { "title": "Shipping Tax Rate", "description": "This represents the tax rates applied on a shipping option.", "type": "object", "required": [ "created_at", "metadata", "rate_id", "shipping_option_id", "updated_at" ], "properties": { "shipping_option_id": { "description": "The ID of the shipping option.", "type": "string", "example": "so_01G1G5V27GYX4QXNARRQCW1N8T" }, "shipping_option": { "description": "The details of the shipping option.", "x-expandable": "shipping_option", "nullable": true, "$ref": "#/components/schemas/ShippingOption" }, "rate_id": { "description": "The ID of the associated tax rate.", "type": "string", "example": "txr_01G8XDBAWKBHHJRKH0AV02KXBR" }, "tax_rate": { "description": "The details of the associated tax rate.", "x-expandable": "tax_rate", "nullable": true, "$ref": "#/components/schemas/TaxRate" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "StagedJob": { "title": "Staged Job", "description": "A staged job resource", "type": "object", "required": [ "data", "event_name", "id", "options" ], "properties": { "id": { "description": "The staged job's ID", "type": "string", "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": {} }, "option": { "description": "The staged job's option", "type": "object", "example": {} } } }, "StockLocationAddressDTO": { "title": "Stock Location Address", "description": "Represents a Stock Location Address", "type": "object", "required": [ "address_1", "country_code", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "The stock location address' ID", "example": "laddr_51G4ZW853Y6TFXWPG5ENJ81X42" }, "address_1": { "type": "string", "description": "Stock location address", "example": "35, Jhon Doe Ave" }, "address_2": { "type": "string", "description": "Stock location address' complement", "example": "apartment 4432" }, "company": { "type": "string", "description": "Stock location company' name", "example": "Medusa" }, "city": { "type": "string", "description": "Stock location address' city", "example": "Mexico city" }, "country_code": { "type": "string", "description": "Stock location address' country", "example": "MX" }, "phone": { "type": "string", "description": "Stock location address' phone number", "example": "+1 555 61646" }, "postal_code": { "type": "string", "description": "Stock location address' postal code", "example": "HD3-1G8" }, "province": { "type": "string", "description": "Stock location address' province", "example": "Sinaloa" }, "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" } } } }, "StockLocationAddressInput": { "title": "Stock Location Address Input", "description": "Represents a Stock Location Address Input", "type": "object", "required": [ "address_1", "country_code" ], "properties": { "address_1": { "type": "string", "description": "Stock location address", "example": "35, Jhon Doe Ave" }, "address_2": { "type": "string", "description": "Stock location address' complement", "example": "apartment 4432" }, "city": { "type": "string", "description": "Stock location address' city", "example": "Mexico city" }, "country_code": { "type": "string", "description": "Stock location address' country", "example": "MX" }, "phone": { "type": "string", "description": "Stock location address' phone number", "example": "+1 555 61646" }, "postal_code": { "type": "string", "description": "Stock location address' postal code", "example": "HD3-1G8" }, "province": { "type": "string", "description": "Stock location address' province", "example": "Sinaloa" }, "metadata": { "type": "object", "description": "An optional key-value map with additional details", "example": { "car": "white" } } } }, "StockLocationDTO": { "title": "Stock Location", "description": "Represents a Stock Location", "type": "object", "required": [ "id", "name", "address_id", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "The stock location's ID", "example": "sloc_51G4ZW853Y6TFXWPG5ENJ81X42" }, "address_id": { "type": "string", "description": "Stock location address' ID", "example": "laddr_05B2ZE853Y6FTXWPW85NJ81A44" }, "name": { "type": "string", "description": "The name of the stock location", "example": "Main Warehouse" }, "address": { "description": "The Address of the Stock Location", "allOf": [ { "$ref": "#/components/schemas/StockLocationAddressDTO" }, { "type": "object" } ] }, "metadata": { "type": "object", "description": "An optional key-value map with additional details", "example": { "car": "white" } }, "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" } } }, "StockLocationExpandedDTO": { "allOf": [ { "$ref": "#/components/schemas/StockLocationDTO" }, { "type": "object", "properties": { "sales_channels": { "$ref": "#/components/schemas/SalesChannel" } } } ] }, "Store": { "title": "Store", "description": "A store holds the main settings of the commerce shop. By default, only one store is created and used within the Medusa backend. It holds settings related to the name of the store, available currencies, and more.", "type": "object", "required": [ "created_at", "default_currency_code", "default_location_id", "id", "invite_link_template", "metadata", "name", "payment_link_template", "swap_link_template", "updated_at" ], "properties": { "id": { "description": "The store's ID", "type": "string", "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": "The details of the store's default currency.", "x-expandable": "default_currency", "nullable": true, "$ref": "#/components/schemas/Currency" }, "currencies": { "description": "The details of the enabled currencies in the store.", "type": "array", "x-expandable": "currencies", "items": { "$ref": "#/components/schemas/Currency" } }, "swap_link_template": { "description": "A template to generate Swap links from. Use {{cart_id}} to include the Swap's `cart_id` in the link.", "nullable": true, "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.", "nullable": true, "type": "string", "example": null }, "invite_link_template": { "description": "A template to generate Invite links from", "nullable": true, "type": "string", "example": null }, "default_location_id": { "description": "The location ID the store is associated with.", "nullable": true, "type": "string", "example": null }, "default_sales_channel_id": { "description": "The ID of the store's default sales channel.", "nullable": true, "type": "string", "example": null }, "default_sales_channel": { "description": "The details of the store's default sales channel.", "x-expandable": "default_sales_channel", "nullable": true, "$ref": "#/components/schemas/SalesChannel" }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "StoreAuthRes": { "type": "object", "x-expanded-relations": { "field": "customer", "relations": [ "orders", "orders.items", "shipping_addresses" ] }, "required": [ "customer" ], "properties": { "customer": { "description": "Customer's details.", "$ref": "#/components/schemas/Customer" } } }, "StoreCartShippingOptionsListRes": { "type": "object", "x-expanded-relations": { "field": "shipping_options", "implicit": [ "profile", "requirements" ] }, "required": [ "shipping_options" ], "properties": { "shipping_options": { "type": "array", "description": "An array of shipping options details.", "items": { "$ref": "#/components/schemas/PricedShippingOption" } } } }, "StoreCartsRes": { "type": "object", "x-expanded-relations": { "field": "cart", "relations": [ "billing_address", "discounts", "discounts.rule", "gift_cards", "items", "items.adjustments", "items.variant", "payment", "payment_sessions", "region", "region.countries", "region.payment_providers", "shipping_address", "shipping_methods" ], "eager": [ "region.fulfillment_providers", "region.payment_providers", "shipping_methods.shipping_option" ], "implicit": [ "items", "items.variant", "items.variant.product", "items.variant.product.profiles", "items.tax_lines", "items.adjustments", "gift_cards", "discounts", "discounts.rule", "shipping_methods", "shipping_methods.tax_lines", "shipping_address", "region", "region.tax_rates" ], "totals": [ "discount_total", "gift_card_tax_total", "gift_card_total", "item_tax_total", "refundable_amount", "refunded_total", "shipping_tax_total", "shipping_total", "subtotal", "tax_total", "total", "items.discount_total", "items.gift_card_total", "items.original_tax_total", "items.original_total", "items.refundable", "items.subtotal", "items.tax_total", "items.total" ] }, "required": [ "cart" ], "properties": { "cart": { "description": "Cart details.", "$ref": "#/components/schemas/Cart" } } }, "StoreCollectionsListRes": { "type": "object", "required": [ "collections", "count", "offset", "limit" ], "properties": { "collections": { "type": "array", "description": "An array of product collections details", "items": { "$ref": "#/components/schemas/ProductCollection" } }, "count": { "type": "integer", "description": "The total number of items available" }, "offset": { "type": "integer", "description": "The number of product collections skipped when retrieving the product collections." }, "limit": { "type": "integer", "description": "The number of items per page" } } }, "StoreCollectionsRes": { "type": "object", "required": [ "collection" ], "properties": { "collection": { "description": "Product collection details.", "$ref": "#/components/schemas/ProductCollection" } } }, "StoreCompleteCartRes": { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "description": "The type of the data property. If the cart completion fails, type will be `cart` and the data object will be the cart's details. If the cart completion is successful and the cart is used for checkout, type will be `order` and the data object will be the order's details. If the cart completion is successful and the cart is used for swap creation, type will be `swap` and the data object will be the swap's details.", "enum": [ "order", "cart", "swap" ] }, "data": { "type": "object", "description": "The data of the result object. Its type depends on the type field.", "oneOf": [ { "type": "object", "allOf": [ { "description": "Cart was successfully authorized and order was placed successfully." }, { "$ref": "#/components/schemas/Order" } ] }, { "type": "object", "allOf": [ { "description": "Cart was successfully authorized but requires further actions." }, { "$ref": "#/components/schemas/Cart" } ] }, { "type": "object", "allOf": [ { "description": "Cart was used for a swap and it has been completed successfully." }, { "$ref": "#/components/schemas/Swap" } ] } ] } } }, "StoreCustomersListOrdersRes": { "type": "object", "x-expanded-relations": { "field": "orders", "relations": [ "customer", "discounts", "discounts.rule", "fulfillments", "fulfillments.tracking_links", "items", "items.variant", "payments", "region", "shipping_address", "shipping_methods" ], "eager": [ "region.fulfillment_providers", "region.payment_providers", "shipping_methods.shipping_option" ], "implicit": [ "claims", "claims.additional_items", "claims.additional_items.adjustments", "claims.additional_items.refundable", "claims.additional_items.tax_lines", "customer", "discounts", "discounts.rule", "gift_card_transactions", "gift_card_transactions.gift_card", "gift_cards", "items", "items.adjustments", "items.refundable", "items.tax_lines", "items.variant", "items.variant.product", "items.variant.product.profiles", "refunds", "region", "shipping_address", "shipping_methods", "shipping_methods.tax_lines", "swaps", "swaps.additional_items", "swaps.additional_items.adjustments", "swaps.additional_items.refundable", "swaps.additional_items.tax_lines" ], "totals": [ "discount_total", "gift_card_tax_total", "gift_card_total", "paid_total", "refundable_amount", "refunded_total", "shipping_total", "subtotal", "tax_total", "total", "claims.additional_items.discount_total", "claims.additional_items.gift_card_total", "claims.additional_items.original_tax_total", "claims.additional_items.original_total", "claims.additional_items.refundable", "claims.additional_items.subtotal", "claims.additional_items.tax_total", "claims.additional_items.total", "items.discount_total", "items.gift_card_total", "items.original_tax_total", "items.original_total", "items.refundable", "items.subtotal", "items.tax_total", "items.total", "swaps.additional_items.discount_total", "swaps.additional_items.gift_card_total", "swaps.additional_items.original_tax_total", "swaps.additional_items.original_total", "swaps.additional_items.refundable", "swaps.additional_items.subtotal", "swaps.additional_items.tax_total", "swaps.additional_items.total" ] }, "required": [ "orders", "count", "offset", "limit" ], "properties": { "orders": { "type": "array", "description": "An array of orders details.", "items": { "$ref": "#/components/schemas/Order" } }, "count": { "description": "The total number of items available", "type": "integer" }, "offset": { "description": "The number of orders skipped when retrieving the orders.", "type": "integer" }, "limit": { "description": "The number of items per page", "type": "integer" } } }, "StoreCustomersListPaymentMethodsRes": { "type": "object", "required": [ "payment_methods" ], "properties": { "payment_methods": { "type": "array", "description": "An array of saved payment method details.", "items": { "type": "object", "required": [ "provider_id", "data" ], "properties": { "provider_id": { "description": "The ID of the Payment Provider where the payment method is saved.", "type": "string" }, "data": { "description": "The data needed for the Payment Provider to use the saved payment method.", "type": "object" } } } } } }, "StoreCustomersRes": { "type": "object", "x-expanded-relations": { "field": "customer", "relations": [ "billing_address", "shipping_addresses" ] }, "required": [ "customer" ], "properties": { "customer": { "description": "Customer details.", "$ref": "#/components/schemas/Customer" } } }, "StoreCustomersResetPasswordRes": { "type": "object", "required": [ "customer" ], "properties": { "customer": { "description": "Customer details.", "$ref": "#/components/schemas/Customer" } } }, "StoreGetAuthEmailRes": { "type": "object", "required": [ "exists" ], "properties": { "exists": { "description": "Whether email exists or not.", "type": "boolean" } } }, "StoreGetProductCategoriesCategoryRes": { "type": "object", "x-expanded-relations": { "field": "product_category", "relations": [ "category_children", "parent_category" ] }, "required": [ "product_category" ], "properties": { "product_category": { "description": "Product category details.", "$ref": "#/components/schemas/ProductCategory" } } }, "StoreGetProductCategoriesRes": { "type": "object", "x-expanded-relations": { "field": "product_categories", "relations": [ "category_children", "parent_category" ] }, "required": [ "product_categories", "count", "offset", "limit" ], "properties": { "product_categories": { "type": "array", "description": "An array of product categories details.", "items": { "$ref": "#/components/schemas/ProductCategory" } }, "count": { "type": "integer", "description": "The total number of items available" }, "offset": { "type": "integer", "description": "The number of product categories skipped when retrieving the product categories." }, "limit": { "type": "integer", "description": "The number of items per page" } } }, "StoreGiftCardsRes": { "type": "object", "required": [ "gift_card" ], "properties": { "gift_card": { "description": "Gift card details.", "$ref": "#/components/schemas/GiftCard" } } }, "StoreOrderEditsRes": { "type": "object", "x-expanded-relations": { "field": "order_edit", "relations": [ "changes", "changes.line_item", "changes.line_item.variant", "changes.original_line_item", "changes.original_line_item.variant", "items", "items.adjustments", "items.tax_lines", "items.variant", "payment_collection" ], "implicit": [ "items", "items.tax_lines", "items.adjustments", "items.variant" ], "totals": [ "difference_due", "discount_total", "gift_card_tax_total", "gift_card_total", "shipping_total", "subtotal", "tax_total", "total", "items.discount_total", "items.gift_card_total", "items.original_tax_total", "items.original_total", "items.refundable", "items.subtotal", "items.tax_total", "items.total" ] }, "required": [ "order_edit" ], "properties": { "order_edit": { "description": "Order edit details.", "$ref": "#/components/schemas/OrderEdit" } } }, "StoreOrdersRes": { "type": "object", "required": [ "order" ], "x-expanded-relations": { "field": "order", "relations": [ "customer", "discounts", "discounts.rule", "fulfillments", "fulfillments.tracking_links", "items", "items.variant", "payments", "region", "shipping_address", "shipping_methods" ], "eager": [ "fulfillments.items", "region.fulfillment_providers", "region.payment_providers", "shipping_methods.shipping_option" ], "implicit": [ "claims", "claims.additional_items", "claims.additional_items.adjustments", "claims.additional_items.refundable", "claims.additional_items.tax_lines", "discounts", "discounts.rule", "gift_card_transactions", "gift_card_transactions.gift_card", "gift_cards", "items", "items.adjustments", "items.refundable", "items.tax_lines", "items.variant", "items.variant.product", "items.variant.product.profiles", "refunds", "region", "shipping_methods", "shipping_methods.tax_lines", "swaps", "swaps.additional_items", "swaps.additional_items.adjustments", "swaps.additional_items.refundable", "swaps.additional_items.tax_lines" ], "totals": [ "discount_total", "gift_card_tax_total", "gift_card_total", "paid_total", "refundable_amount", "refunded_total", "shipping_total", "subtotal", "tax_total", "total", "claims.additional_items.discount_total", "claims.additional_items.gift_card_total", "claims.additional_items.original_tax_total", "claims.additional_items.original_total", "claims.additional_items.refundable", "claims.additional_items.subtotal", "claims.additional_items.tax_total", "claims.additional_items.total", "items.discount_total", "items.gift_card_total", "items.original_tax_total", "items.original_total", "items.refundable", "items.subtotal", "items.tax_total", "items.total", "swaps.additional_items.discount_total", "swaps.additional_items.gift_card_total", "swaps.additional_items.original_tax_total", "swaps.additional_items.original_total", "swaps.additional_items.refundable", "swaps.additional_items.subtotal", "swaps.additional_items.tax_total", "swaps.additional_items.total" ] }, "properties": { "order": { "description": "Order details.", "$ref": "#/components/schemas/Order" } } }, "StorePaymentCollectionSessionsReq": { "type": "object", "required": [ "provider_id" ], "properties": { "provider_id": { "type": "string", "description": "The ID of the Payment Provider." } } }, "StorePaymentCollectionsRes": { "type": "object", "x-expanded-relations": { "field": "payment_collection", "relations": [ "payment_sessions", "region" ], "eager": [ "region.fulfillment_providers", "region.payment_providers" ] }, "required": [ "payment_collection" ], "properties": { "payment_collection": { "description": "Payment collection's details.", "$ref": "#/components/schemas/PaymentCollection" } } }, "StorePaymentCollectionsSessionRes": { "type": "object", "required": [ "payment_session" ], "properties": { "payment_session": { "description": "Payment session's details.", "$ref": "#/components/schemas/PaymentSession" } } }, "StorePostAuthReq": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "description": "The Customer's email." }, "password": { "type": "string", "description": "The Customer's password." } } }, "StorePostCartReq": { "type": "object", "properties": { "region_id": { "type": "string", "description": "The ID of the Region to create the Cart in. Setting the cart's region can affect the pricing of the items in the cart as well as the used currency. If this parameter is not provided, the first region in the store is used by default." }, "sales_channel_id": { "type": "string", "description": "The ID of the Sales channel to create the Cart in. The cart's sales channel affects which products can be added to the cart. If a product does not exist in the cart's sales channel, it cannot be added to the cart. If you add a publishable API key in the header of this request and specify a sales channel ID, the specified sales channel must be within the scope of the publishable API key's resources. If you add a publishable API key in the header of this request, you don't specify a sales channel ID, and the publishable API key is associated with one sales channel, that sales channel will be attached to the cart. If no sales channel is passed and no publishable API key header is passed or the publishable API key isn't associated with any sales channel, the cart will not be associated with any sales channel." }, "country_code": { "type": "string", "description": "The 2 character ISO country code to create the Cart in. Setting this parameter will set the country code of the shipping address.", "externalDocs": { "url": "https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements", "description": "See a list of codes." } }, "items": { "description": "An array of product variants to generate line items from.", "type": "array", "items": { "type": "object", "required": [ "variant_id", "quantity" ], "properties": { "variant_id": { "description": "The ID of the Product Variant.", "type": "string" }, "quantity": { "description": "The quantity to add into the cart.", "type": "integer" } } } }, "context": { "description": "An object to provide context to the Cart. The `context` field is automatically populated with `ip` and `user_agent`", "type": "object", "example": { "ip": "::1", "user_agent": "Chrome" } } } }, "StorePostCartsCartLineItemsItemReq": { "type": "object", "required": [ "quantity" ], "properties": { "quantity": { "type": "number", "description": "The quantity of the line item in the cart." }, "metadata": { "type": "object", "description": "An optional key-value map with additional details about the Line Item. If omitted, the metadata will remain unchanged.\"", "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "StorePostCartsCartLineItemsReq": { "type": "object", "required": [ "variant_id", "quantity" ], "properties": { "variant_id": { "type": "string", "description": "The id of the Product Variant to generate the Line Item from." }, "quantity": { "type": "number", "description": "The quantity of the Product Variant to add to the Line Item." }, "metadata": { "type": "object", "description": "An optional key-value map with additional details about the Line Item.", "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "StorePostCartsCartPaymentSessionReq": { "type": "object", "required": [ "provider_id" ], "properties": { "provider_id": { "type": "string", "description": "The ID of the Payment Provider." } } }, "StorePostCartsCartPaymentSessionUpdateReq": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "The data to update the payment session with." } } }, "StorePostCartsCartReq": { "type": "object", "properties": { "region_id": { "type": "string", "description": "The ID of the Region to create the Cart in. Setting the cart's region can affect the pricing of the items in the cart as well as the used currency." }, "country_code": { "type": "string", "description": "The 2 character ISO country code to create the Cart in. Setting this parameter will set the country code of the shipping address.", "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 Cart.", "format": "email" }, "sales_channel_id": { "type": "string", "description": "The ID of the Sales channel to create the Cart in. The cart's sales channel affects which products can be added to the cart. If a product does not exist in the cart's sales channel, it cannot be added to the cart. If you add a publishable API key in the header of this request and specify a sales channel ID, the specified sales channel must be within the scope of the publishable API key's resources." }, "billing_address": { "description": "The Address to be used for billing purposes.", "anyOf": [ { "$ref": "#/components/schemas/AddressPayload", "description": "A full billing address object." }, { "type": "string", "description": "The billing address ID" } ] }, "shipping_address": { "description": "The Address to be used for shipping purposes.", "anyOf": [ { "$ref": "#/components/schemas/AddressPayload", "description": "A full shipping address object." }, { "type": "string", "description": "The shipping address ID" } ] }, "gift_cards": { "description": "An array of Gift Card codes to add to the Cart.", "type": "array", "items": { "type": "object", "required": [ "code" ], "properties": { "code": { "description": "The code of a gift card.", "type": "string" } } } }, "discounts": { "description": "An array of Discount codes to add to the Cart.", "type": "array", "items": { "type": "object", "required": [ "code" ], "properties": { "code": { "description": "The code of the discount.", "type": "string" } } } }, "customer_id": { "description": "The ID of the Customer to associate the Cart with.", "type": "string" }, "context": { "description": "An object to provide context to the Cart. The `context` field is automatically populated with `ip` and `user_agent`", "type": "object", "example": { "ip": "::1", "user_agent": "Chrome" } } } }, "StorePostCartsCartShippingMethodReq": { "type": "object", "required": [ "option_id" ], "properties": { "option_id": { "type": "string", "description": "ID of the shipping option to create the method from." }, "data": { "type": "object", "description": "Used to hold any data that the shipping method may need to process the fulfillment of the order. This depends on the fulfillment provider you're using." } } }, "StorePostCustomersCustomerAcceptClaimReq": { "type": "object", "required": [ "token" ], "properties": { "token": { "description": "The claim token generated by previous request to the Claim Order endpoint.", "type": "string" } } }, "StorePostCustomersCustomerAddressesAddressReq": { "anyOf": [ { "$ref": "#/components/schemas/AddressPayload" } ] }, "StorePostCustomersCustomerAddressesReq": { "type": "object", "required": [ "address" ], "properties": { "address": { "description": "The Address to add to the Customer's saved addresses.", "$ref": "#/components/schemas/AddressCreatePayload" } } }, "StorePostCustomersCustomerOrderClaimReq": { "type": "object", "required": [ "order_ids" ], "properties": { "order_ids": { "description": "The ID of the orders to claim", "type": "array", "items": { "type": "string" } } } }, "StorePostCustomersCustomerPasswordTokenReq": { "type": "object", "required": [ "email" ], "properties": { "email": { "description": "The customer's email.", "type": "string", "format": "email" } } }, "StorePostCustomersCustomerReq": { "type": "object", "properties": { "first_name": { "description": "The customer's first name.", "type": "string" }, "last_name": { "description": "The customer's last name.", "type": "string" }, "billing_address": { "description": "The address to be used for billing purposes.", "anyOf": [ { "$ref": "#/components/schemas/AddressPayload", "description": "The full billing address object" }, { "type": "string", "description": "The ID of an existing billing address" } ] }, "password": { "description": "The customer's password.", "type": "string" }, "phone": { "description": "The customer's phone number.", "type": "string" }, "email": { "description": "The customer's email.", "type": "string" }, "metadata": { "description": "Additional custom data about the customer.", "type": "object", "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "StorePostCustomersReq": { "type": "object", "required": [ "first_name", "last_name", "email", "password" ], "properties": { "first_name": { "description": "The customer's first name.", "type": "string" }, "last_name": { "description": "The customer's last name.", "type": "string" }, "email": { "description": "The customer's email.", "type": "string", "format": "email" }, "password": { "description": "The customer's password.", "type": "string", "format": "password" }, "phone": { "description": "The customer's phone number.", "type": "string" } } }, "StorePostCustomersResetPasswordReq": { "type": "object", "required": [ "email", "password", "token" ], "properties": { "email": { "description": "The customer's email.", "type": "string", "format": "email" }, "password": { "description": "The customer's password.", "type": "string", "format": "password" }, "token": { "description": "The reset password token", "type": "string" } } }, "StorePostOrderEditsOrderEditDecline": { "type": "object", "properties": { "declined_reason": { "type": "string", "description": "The reason for declining the Order Edit." } } }, "StorePostPaymentCollectionsBatchSessionsAuthorizeReq": { "type": "object", "required": [ "session_ids" ], "properties": { "session_ids": { "description": "List of Payment Session IDs to authorize.", "type": "array", "items": { "type": "string" } } } }, "StorePostPaymentCollectionsBatchSessionsReq": { "type": "object", "required": [ "sessions" ], "properties": { "sessions": { "description": "An array of payment sessions related to the Payment Collection. Existing sessions that are not added in this array will be deleted.", "type": "array", "items": { "type": "object", "required": [ "provider_id", "amount" ], "properties": { "provider_id": { "type": "string", "description": "The ID of the Payment Provider." }, "amount": { "type": "integer", "description": "The payment amount" }, "session_id": { "type": "string", "description": "The ID of the Payment Session to be updated. If no ID is provided, a new payment session is created." } } } } } }, "StorePostReturnsReq": { "type": "object", "required": [ "order_id", "items" ], "properties": { "order_id": { "type": "string", "description": "The ID of the Order to create the return for." }, "items": { "description": "The items to include in the return.", "type": "array", "items": { "type": "object", "required": [ "item_id", "quantity" ], "properties": { "item_id": { "description": "The ID of the line item to return.", "type": "string" }, "quantity": { "description": "The quantity to return.", "type": "integer" }, "reason_id": { "description": "The ID of the return reason. Return reasons can be retrieved from the List Return Reasons endpoint.", "type": "string" }, "note": { "description": "A note to add to the item returned.", "type": "string" } } } }, "return_shipping": { "description": "The return shipping method used to return the items. If provided, a fulfillment is automatically created for the return.", "type": "object", "required": [ "option_id" ], "properties": { "option_id": { "type": "string", "description": "The ID of the Shipping Option to create the Shipping Method from." } } } } }, "StorePostSearchReq": { "type": "object", "properties": { "q": { "type": "string", "description": "The search query." }, "offset": { "type": "number", "description": "The number of products to skip when retrieving the products." }, "limit": { "type": "number", "description": "Limit the number of products returned." }, "filter": { "description": "Pass filters based on the search service." } } }, "StorePostSearchRes": { "allOf": [ { "type": "object", "required": [ "hits" ], "properties": { "hits": { "description": "Array of search results. The format of the items depends on the search engine installed on the Medusa backend.", "type": "array" } } }, { "type": "object" } ] }, "StorePostSwapsReq": { "type": "object", "required": [ "order_id", "return_items", "additional_items" ], "properties": { "order_id": { "type": "string", "description": "The ID of the Order to create the Swap for." }, "return_items": { "description": "The items to include in the Return.", "type": "array", "items": { "type": "object", "required": [ "item_id", "quantity" ], "properties": { "item_id": { "description": "The ID of the order's line item to return.", "type": "string" }, "quantity": { "description": "The quantity to return.", "type": "integer" }, "reason_id": { "description": "The ID of the reason of this return. Return reasons can be retrieved from the List Return Reasons endpoint.", "type": "string" }, "note": { "description": "The note to add to the item being swapped.", "type": "string" } } } }, "return_shipping_option": { "type": "string", "description": "The ID of the Shipping Option to create the Shipping Method from." }, "additional_items": { "description": "The items to exchange the returned items with.", "type": "array", "items": { "type": "object", "required": [ "variant_id", "quantity" ], "properties": { "variant_id": { "description": "The ID of the Product Variant.", "type": "string" }, "quantity": { "description": "The quantity of the variant.", "type": "integer" } } } } } }, "StoreProductTagsListRes": { "type": "object", "required": [ "product_tags", "count", "offset", "limit" ], "properties": { "product_tags": { "type": "array", "description": "An array of product tags details.", "items": { "$ref": "#/components/schemas/ProductTag" } }, "count": { "type": "integer", "description": "The total number of items available" }, "offset": { "type": "integer", "description": "The number of product tags skipped when retrieving the product tags." }, "limit": { "type": "integer", "description": "The number of items per page" } } }, "StoreProductTypesListRes": { "type": "object", "required": [ "product_types", "count", "offset", "limit" ], "properties": { "product_types": { "type": "array", "description": "An array of product types details.", "items": { "$ref": "#/components/schemas/ProductType" } }, "count": { "type": "integer", "description": "The total number of items available" }, "offset": { "type": "integer", "description": "The number of product types skipped when retrieving the product types." }, "limit": { "type": "integer", "description": "The number of items per page" } } }, "StoreProductsListRes": { "type": "object", "x-expanded-relations": { "field": "products", "relations": [ "collection", "images", "options", "options.values", "tags", "type", "variants", "variants.options", "variants.prices" ], "totals": [ "variants.purchasable" ] }, "required": [ "products", "count", "offset", "limit" ], "properties": { "products": { "type": "array", "description": "An array of products details.", "items": { "$ref": "#/components/schemas/PricedProduct" } }, "count": { "type": "integer", "description": "The total number of items available" }, "offset": { "type": "integer", "description": "The number of products skipped when retrieving the products." }, "limit": { "type": "integer", "description": "The number of items per page" } } }, "StoreProductsRes": { "type": "object", "x-expanded-relations": { "field": "product", "relations": [ "collection", "images", "options", "options.values", "tags", "type", "variants", "variants.options", "variants.prices" ], "totals": [ "variants.purchasable" ] }, "required": [ "product" ], "properties": { "product": { "description": "Product details.", "$ref": "#/components/schemas/PricedProduct" } } }, "StoreRegionsListRes": { "type": "object", "x-expanded-relations": { "field": "regions", "relations": [ "countries", "payment_providers", "fulfillment_providers" ], "eager": [ "payment_providers", "fulfillment_providers" ] }, "required": [ "regions" ], "properties": { "regions": { "type": "array", "description": "An array of regions details.", "items": { "$ref": "#/components/schemas/Region" } }, "count": { "type": "integer", "description": "The total number of items available" }, "offset": { "type": "integer", "description": "The number of regions skipped when retrieving the regions." }, "limit": { "type": "integer", "description": "The number of items per page" } } }, "StoreRegionsRes": { "type": "object", "x-expanded-relations": { "field": "region", "relations": [ "countries", "payment_providers", "fulfillment_providers" ], "eager": [ "payment_providers", "fulfillment_providers" ] }, "required": [ "region" ], "properties": { "region": { "description": "Region details.", "$ref": "#/components/schemas/Region" } } }, "StoreReturnReasonsListRes": { "type": "object", "x-expanded-relations": { "field": "return_reasons", "relations": [ "parent_return_reason", "return_reason_children" ] }, "required": [ "return_reasons" ], "properties": { "return_reasons": { "type": "array", "description": "An array of return reasons details.", "items": { "$ref": "#/components/schemas/ReturnReason" } } } }, "StoreReturnReasonsRes": { "type": "object", "x-expanded-relations": { "field": "return_reason", "relations": [ "parent_return_reason", "return_reason_children" ] }, "required": [ "return_reason" ], "properties": { "return_reason": { "description": "Return reason details.", "$ref": "#/components/schemas/ReturnReason" } } }, "StoreReturnsRes": { "type": "object", "x-expanded-relations": { "field": "return", "relations": [ "items", "items.reason" ], "eager": [ "items" ] }, "required": [ "return" ], "properties": { "return": { "description": "Return details.", "$ref": "#/components/schemas/Return" } } }, "StoreShippingOptionsListRes": { "type": "object", "x-expanded-relations": { "field": "shipping_options", "relations": [ "requirements" ] }, "required": [ "shipping_options" ], "properties": { "shipping_options": { "type": "array", "description": "An array of shipping options details.", "items": { "$ref": "#/components/schemas/PricedShippingOption" } } } }, "StoreSwapsRes": { "type": "object", "x-expanded-relations": { "field": "swap", "relations": [ "additional_items", "additional_items.variant", "cart", "fulfillments", "order", "payment", "return_order", "return_order.shipping_method", "shipping_address", "shipping_methods" ], "eager": [ "fulfillments.items" ] }, "required": [ "swap" ], "properties": { "swap": { "description": "Swap details.", "$ref": "#/components/schemas/Swap" } } }, "StoreVariantsListRes": { "type": "object", "x-expanded-relations": { "field": "variants", "relations": [ "prices", "options", "product" ], "totals": [ "purchasable" ] }, "required": [ "variants" ], "properties": { "variants": { "type": "array", "description": "An array of product variant descriptions.", "items": { "$ref": "#/components/schemas/PricedVariant" } } } }, "StoreVariantsRes": { "type": "object", "x-expanded-relations": { "field": "variant", "relations": [ "prices", "options", "product" ], "totals": [ "purchasable" ] }, "required": [ "variant" ], "properties": { "variant": { "description": "Product variant description.", "$ref": "#/components/schemas/PricedVariant" } } }, "Swap": { "title": "Swap", "description": "A swap can be created when a Customer wishes to exchange Products that they have purchased with different Products. It consists of a Return of previously purchased Products and a Fulfillment of new Products. It also includes information on any additional payment or refund required based on the difference between the exchanged products.", "type": "object", "required": [ "allow_backorder", "canceled_at", "cart_id", "confirmed_at", "created_at", "deleted_at", "difference_due", "fulfillment_status", "id", "idempotency_key", "metadata", "no_notification", "order_id", "payment_status", "shipping_address_id", "updated_at" ], "properties": { "id": { "description": "The swap's ID", "type": "string", "example": "swap_01F0YET86Y9G92D3YDR9Y6V676" }, "fulfillment_status": { "description": "The status of the Fulfillment of the Swap.", "type": "string", "enum": [ "not_fulfilled", "fulfilled", "shipped", "partially_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 that the swap belongs to.", "type": "string", "example": "order_01G8TJSYT9M6AVS5N4EMNFS1EK" }, "order": { "description": "The details of the order that the swap belongs to.", "x-expandable": "order", "nullable": true, "$ref": "#/components/schemas/Order" }, "additional_items": { "description": "The details of the new products to send to the customer, represented as line items.", "type": "array", "x-expandable": "additional_items", "items": { "$ref": "#/components/schemas/LineItem" } }, "return_order": { "description": "The details of the return that belongs to the swap, which holds the details on the items being returned.", "x-expandable": "return_order", "nullable": true, "$ref": "#/components/schemas/Return" }, "fulfillments": { "description": "The details of the fulfillments that are used to send the new items to the customer.", "x-expandable": "fulfillments", "type": "array", "items": { "$ref": "#/components/schemas/Fulfillment" } }, "payment": { "description": "The details of the additional payment authorized by the customer when `difference_due` is positive.", "x-expandable": "payment", "nullable": true, "$ref": "#/components/schemas/Payment" }, "difference_due": { "description": "The difference amount between the order’s original total and the new total imposed by the swap. If its value is negative, a refund must be issues to the customer. If it's positive, additional payment must be authorized by the customer. Otherwise, no payment processing is required.", "nullable": true, "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.", "nullable": true, "type": "string", "example": "addr_01G8ZH853YPY9B94857DY91YGW" }, "shipping_address": { "description": "The details of the shipping address that the new items should be sent to.", "x-expandable": "shipping_address", "nullable": true, "$ref": "#/components/schemas/Address" }, "shipping_methods": { "description": "The details of the shipping methods used to fulfill the additional items purchased.", "type": "array", "x-expandable": "shipping_methods", "items": { "$ref": "#/components/schemas/ShippingMethod" } }, "cart_id": { "description": "The ID of the cart that the customer uses to complete the swap.", "nullable": true, "type": "string", "example": "cart_01G8ZH853Y6TFXWPG5EYE81X63" }, "cart": { "description": "The details of the cart that the customer uses to complete the swap.", "x-expandable": "cart", "nullable": true, "$ref": "#/components/schemas/Cart" }, "confirmed_at": { "description": "The date with timezone at which the Swap was confirmed by the Customer.", "nullable": true, "type": "string", "format": "date-time" }, "canceled_at": { "description": "The date with timezone at which the Swap was canceled.", "nullable": true, "type": "string", "format": "date-time" }, "no_notification": { "description": "If set to true, no notification will be sent related to this swap", "nullable": true, "type": "boolean", "example": false }, "allow_backorder": { "description": "If true, swaps can be completed with items out of stock", "type": "boolean", "default": false }, "idempotency_key": { "description": "Randomly generated key used to continue the completion of the swap in case of failure.", "nullable": true, "type": "string", "externalDocs": { "url": "https://docs.medusajs.com/development/idempotency-key/overview.md", "description": "Learn more how to use the idempotency key." } }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "TaxLine": { "title": "Tax Line", "description": "A tax line represents the taxes amount applied to a line item.", "type": "object", "required": [ "code", "created_at", "id", "metadata", "name", "rate", "updated_at" ], "properties": { "id": { "description": "The tax line's ID", "type": "string", "example": "tl_01G1G5V2DRX1SK6NQQ8VVX4HQ8" }, "code": { "description": "A code to identify the tax type by", "nullable": true, "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": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "TaxProvider": { "title": "Tax Provider", "description": "A tax provider represents a tax service installed in the Medusa backend, either through a plugin or backend customizations. It holds the tax service's installation status.", "type": "object", "required": [ "id", "is_installed" ], "properties": { "id": { "description": "The ID of the tax provider as given by the tax service.", "type": "string", "example": "manual" }, "is_installed": { "description": "Whether the tax service is installed in the current version. If a tax service is no longer installed, the `is_installed` attribute is set to `false`.", "type": "boolean", "default": true } } }, "TaxRate": { "title": "Tax Rate", "description": "A Tax Rate can be used to define a custom rate to charge on specified products, product types, and shipping options within a given region.", "type": "object", "required": [ "code", "created_at", "id", "metadata", "name", "rate", "region_id", "updated_at" ], "properties": { "id": { "description": "The tax rate's ID", "type": "string", "example": "txr_01G8XDBAWKBHHJRKH0AV02KXBR" }, "rate": { "description": "The numeric rate to charge", "nullable": true, "type": "number", "example": 10 }, "code": { "description": "A code to identify the tax type by", "nullable": true, "type": "string", "example": "tax01" }, "name": { "description": "A human friendly name for the tax", "type": "string", "example": "Tax Example" }, "region_id": { "description": "The ID of the region that the rate belongs to.", "type": "string", "example": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G" }, "region": { "description": "The details of the region that the rate belongs to.", "x-expandable": "region", "nullable": true, "$ref": "#/components/schemas/Region" }, "products": { "description": "The details of the products that belong to this tax rate.", "type": "array", "x-expandable": "products", "items": { "$ref": "#/components/schemas/Product" } }, "product_types": { "description": "The details of the product types that belong to this tax rate.", "type": "array", "x-expandable": "product_types", "items": { "$ref": "#/components/schemas/ProductType" } }, "shipping_options": { "description": "The details of the shipping options that belong to this tax rate.", "type": "array", "x-expandable": "shipping_options", "items": { "$ref": "#/components/schemas/ShippingOption" } }, "product_count": { "description": "The count of products", "type": "integer", "example": 10 }, "product_type_count": { "description": "The count of product types", "type": "integer", "example": 2 }, "shipping_option_count": { "description": "The count of shipping options", "type": "integer", "example": 1 }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "TrackingLink": { "title": "Tracking Link", "description": "A 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. Typically, the tracking link is provided from the third-party service integrated through the used fulfillment provider.", "type": "object", "required": [ "created_at", "deleted_at", "fulfillment_id", "id", "idempotency_key", "metadata", "tracking_number", "updated_at", "url" ], "properties": { "id": { "description": "The tracking link's ID", "type": "string", "example": "tlink_01G8ZH853Y6TFXWPG5EYE81X63" }, "url": { "description": "The URL at which the status of the shipment can be tracked.", "nullable": true, "type": "string", "format": "uri" }, "tracking_number": { "description": "The tracking number given by the shipping carrier.", "type": "string", "format": "RH370168054CN" }, "fulfillment_id": { "description": "The ID of the fulfillment that the tracking link belongs to.", "type": "string", "example": "ful_01G8ZRTMQCA76TXNAT81KPJZRF" }, "fulfillment": { "description": "The details of the fulfillment that the tracking link belongs to.", "x-expandable": "fulfillment", "nullable": true, "$ref": "#/components/schemas/Fulfillment" }, "idempotency_key": { "description": "Randomly generated key used to continue the completion of a process in case of failure.", "nullable": true, "type": "string", "externalDocs": { "url": "https://docs.medusajs.com/development/idempotency-key/overview.md", "description": "Learn more how to use the idempotency key." } }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } }, "UpdateStockLocationInput": { "title": "Update Stock Location Input", "description": "Represents the Input to update a Stock Location", "type": "object", "properties": { "name": { "type": "string", "description": "The stock location name" }, "address_id": { "type": "string", "description": "The Stock location address ID" }, "address": { "description": "Stock location address object", "allOf": [ { "$ref": "#/components/schemas/StockLocationAddressInput" }, { "type": "object" } ] }, "metadata": { "type": "object", "description": "An optional key-value map with additional details", "example": { "car": "white" } } } }, "User": { "title": "User", "description": "A User is an administrator who can manage store settings and data.", "type": "object", "required": [ "api_token", "created_at", "deleted_at", "email", "first_name", "id", "last_name", "metadata", "role", "updated_at" ], "properties": { "id": { "description": "The user's ID", "type": "string", "example": "usr_01G1G5V26F5TB3GPAPNJ8X1S3V" }, "role": { "description": "The user's role. These roles don't provide any different privileges.", "type": "string", "enum": [ "admin", "member", "developer" ], "default": "member" }, "email": { "description": "The email of the User", "type": "string", "format": "email" }, "first_name": { "description": "The first name of the User", "nullable": true, "type": "string", "example": "Levi" }, "last_name": { "description": "The last name of the User", "nullable": true, "type": "string", "example": "Bogan" }, "api_token": { "description": "An API token associated with the user.", "nullable": true, "type": "string", "example": null }, "created_at": { "description": "The date with timezone at which the resource was created.", "type": "string", "format": "date-time" }, "updated_at": { "description": "The date with timezone at which the resource was updated.", "type": "string", "format": "date-time" }, "deleted_at": { "description": "The date with timezone at which the resource was deleted.", "nullable": true, "type": "string", "format": "date-time" }, "metadata": { "description": "An optional key-value map with additional details", "nullable": true, "type": "object", "example": { "car": "white" }, "externalDocs": { "description": "Learn about the metadata attribute, and how to delete and update it.", "url": "https://docs.medusajs.com/development/entities/overview#metadata-attribute" } } } } } } }