From a58955bdbad86f89f1c6aa4a132595f45163ee0d Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Wed, 28 Sep 2022 17:06:21 +0300 Subject: [PATCH] docs: added how-to documentation for the PriceList API (#2260) * docs: added price list how-to * added links to price list conceptual docs * added link to the how-to guide * fixed typo in file extension --- .../advanced/admin/import-products.mdx | 12 - .../advanced/backend/price-lists/index.md | 1 + .../advanced/backend/price-lists/use-api.mdx | 472 ++++++++++++++++++ www/docs/sidebars.js | 4 + 4 files changed, 477 insertions(+), 12 deletions(-) create mode 100644 docs/content/advanced/backend/price-lists/use-api.mdx diff --git a/docs/content/advanced/admin/import-products.mdx b/docs/content/advanced/admin/import-products.mdx index ec0290904f..10be36b145 100644 --- a/docs/content/advanced/admin/import-products.mdx +++ b/docs/content/advanced/admin/import-products.mdx @@ -58,7 +58,6 @@ You can do that by sending the following request to the [Upload Files](https://d ```jsx -// using JS Client medusa.admin.uploads.create(file) //file is an instance of File .then(({ uploads }) => { const key = uploads[0].key; @@ -69,7 +68,6 @@ medusa.admin.uploads.create(file) //file is an instance of File ```jsx -// using Fetch API const formData = new FormData(); formData.append('files', file); //file is an instance of File @@ -90,7 +88,6 @@ fetch(`/admin/uploads`, { ```bash -# using cURL curl --location --request POST '/admin/uploads' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: text/csv' \ @@ -112,7 +109,6 @@ You can do that by sending the following request to the [Create a Batch Job](htt ```jsx -// using JS Client medusa.admin.batchJobs.create({ type: 'product-import', context: { @@ -129,7 +125,6 @@ medusa.admin.batchJobs.create({ ```jsx -// using Fetch API fetch(`/admin/batch-jobs`, { method: 'POST', headers: { @@ -153,7 +148,6 @@ fetch(`/admin/batch-jobs`, { ```bash -# using cURL curl --location --request POST '/admin/batch-jobs' \ --header 'Authorization: Bearer {api_token}' \ --header 'Content-Type: application/json' \ @@ -194,7 +188,6 @@ You can retrieve all the details of the batch job, including its status and the ```jsx -// using JS Client medusa.admin.batchJobs.retrieve(batchJobId) .then(( batch_job ) => { console.log(batch_job.status, batch_job.result); @@ -205,7 +198,6 @@ medusa.admin.batchJobs.retrieve(batchJobId) ```jsx -// using Fetch API fetch(`/admin/batch-jobs/${batchJobId}`) .then((response) => response.json()) .then(({ batch_job }) => { @@ -217,7 +209,6 @@ fetch(`/admin/batch-jobs/${batchJobId}`) ```bash -# using cURL curl --location --request GET '/admin/batch-jobs/' \ --header 'Authorization: Bearer {api_token}' # is the ID of the batch job @@ -256,7 +247,6 @@ To confirm a batch job send the following request: ```jsx -// using JS Client medusa.admin.batchJobs.confirm(batchJobId) .then(( batch_job ) => { console.log(batch_job.status); @@ -267,7 +257,6 @@ medusa.admin.batchJobs.confirm(batchJobId) ```jsx -// using Fetch API fetch(`/admin/batch-jobs/${batchJobId}/confirm`, { method: 'POST' }) @@ -281,7 +270,6 @@ fetch(`/admin/batch-jobs/${batchJobId}/confirm`, { ```bash -# using cURL curl --location --request POST '/admin/batch-jobs//confirm' \ --header 'Authorization: Bearer {api_token}' # is the ID of the batch job diff --git a/docs/content/advanced/backend/price-lists/index.md b/docs/content/advanced/backend/price-lists/index.md index ad84d67ee1..c07b2a496e 100644 --- a/docs/content/advanced/backend/price-lists/index.md +++ b/docs/content/advanced/backend/price-lists/index.md @@ -84,3 +84,4 @@ Since the line item belongs to a cart, there’s no need to pass the `region_id` ## What’s Next 🚀 - Learn more about [price selection strategies](../price-selection-strategy/index.md). +- Learn [how to use the PriceList Admin APIs](./use-api.mdx). diff --git a/docs/content/advanced/backend/price-lists/use-api.mdx b/docs/content/advanced/backend/price-lists/use-api.mdx new file mode 100644 index 0000000000..5f4fe353a1 --- /dev/null +++ b/docs/content/advanced/backend/price-lists/use-api.mdx @@ -0,0 +1,472 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Use PriceList API + +In this document, you’ll learn how to use the PriceList Admin APIs to create, update, and manage prices in a price list. + +:::note + +This document doesn't cover what price lists are and their basics. If you’re interested to learn about that, check out [this documentation](./index.md) instead. + +::: + +## Prerequisites + +### Medusa Components + +It is assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../../quickstart/quick-start.md) to get started. + +### JS Client + +This guide includes code snippets to send requests to your Medusa server using Medusa’s JS Client, JavaScript’s Fetch API, or cURL. + +If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and [have created an instance of the client](../../../js-client/overview.md#configuration). + +### Authenticated Admin User + +You must be an authenticated admin user before following along with the steps in the tutorial. + +You can learn more about [authenticating as an admin user in the API reference](https://docs.medusajs.com/api/admin/#section/Authentication). + +--- + +## Create Price List + +When you create a price list, you can specify different conditions to control when the price list can be applied. + +In the body of your request, aside from the required fields, you can send the following fields to apply different conditions: + +```js +{ + prices: [ + { + region_id, + currency_code, + min_quantity, + max_quantity + } + ], + customer_groups: [ + { + id + } + ] +} +``` + +:::info + +You can learn more about what the conditions you can apply on a price list and its prices in this documentation. + +::: + +For example, sending the following request creates a price list with two prices: one that is applied when the maximum quantity of the product variant in the cart is 3; another is applied when the minimum quantity of the same variant in the cart is 4: + + + + +```jsx +import { PriceListType } from "@medusajs/medusa" + +medusa.admin.priceLists.create({ + name: 'New Price List', + description: 'A new price list', + type: PriceListType.SALE, + status: 'active', + prices: [ + { + amount: 1000, + variant_id, + currency_code: 'eur', + max_quantity: 3 + }, + { + amount: 1500, + variant_id, + currency_code: 'eur', + min_quantity: 4 + } + ] +}) +.then(({ price_list }) => { + console.log(price_list.id); +}); +``` + + + + +```jsx +fetch(`/admin/price-lists`, { + method: 'POST', + headers: { + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ + name: 'New Price List', + description: 'A new price list', + type: 'sale', + status: 'active', + prices: [ + { + amount: 1000, + variant_id, + currency_code: 'eur', + max_quantity: 3 + }, + { + amount: 1500, + variant_id, + currency_code: 'eur', + min_quantity: 4 + } + ] + }) +}) +.then((response) => response.json()) +.then(({ price_list }) => { + console.log(price_list.id) +}) +``` + + + + +```bash +curl --location --request POST '/admin/price-lists' \ +--header 'Authorization: Bearer {api_token}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "name": "New Price List", + "description": "A new price list", + "type": "sale", + "status": "active", + "prices": [ + { + "amount": 1500, + "variant_id": "", + "max_quantity": 3, + "currency_code": "eur" + }, + { + "amount": 1000, + "variant_id": "", + "currency_code": "eur", + "min_quantity": 4 + } + ] +}' +``` + + + + +This request returns the created price list. + +You can check the full list of request body parameters in the [API reference](https://docs.medusajs.com/api/admin/#tag/Price-List/operation/PostPriceListsPriceList). + +--- + +## Get Price List’s Details + +You can retrieve all of a price list’s details using the Get a Price List endpoint: + + + + +```jsx +medusa.admin.priceLists.retrieve(priceListId) +.then(({ price_list }) => { + console.log(price_list.id); +}); +``` + + + + +```jsx +fetch(`/admin/price-lists/${priceListId}`) +.then((response) => response.json()) +.then(({ price_list }) => { + console.log(price_list.id) +}) +``` + + + + +```jsx +curl --location --request GET '/admin/price-lists/{id}' \ +--header 'Authorization: Bearer {api_token}' +``` + + + + +--- + +## Update a Price List + +After creating a price list, you can update all of its fields including its status, prices, and more using the [Update Price List](https://docs.medusajs.com/api/admin/#tag/Price-List/operation/PostPriceListsPriceListPriceList) endpoint. + +For example, by sending the following request the end date of the price list will be updated: + + + + +```jsx +medusa.admin.priceLists.update(priceListId, { + ends_at: '2022-10-11' +}) +.then(({ price_list }) => { + console.log(price_list.id); +}); +``` + + + + +```jsx +fetch(`/admin/price-lists/${priceListId}`, { + method: 'POST', + headers: { + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ + ends_at: '2022-10-11' + }) +}) +.then((response) => response.json()) +.then(({ price_list }) => { + console.log(price_list.id) +}) +``` + + + + +```bash +curl --location --request POST '/admin/price-lists/' \ +--header 'Authorization: Bearer {api_token}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "ends_at": "2022-10-11" +}' +``` + + + + +This request returns the updated price list. + +For a full list of request body parameters, check out the [API reference](https://docs.medusajs.com/api/admin/#tag/Price-List/operation/PostPriceListsPriceListPriceList). + +--- + +## Manage Prices + +### Add Prices + +You can add prices to your price list after creating it using the [Update Prices](https://docs.medusajs.com/api/admin/#tag/Price-List/operation/PostPriceListsPriceListPricesBatch) endpoint. + +You can also set the `override` request body parameter to `true` to replace the existing prices in the price list. + +For example, sending the following request adds a new price to the price list: + + + + +```jsx +medusa.admin.priceLists.addPrices(priceListId, { + prices: [ + { + amount: 1200, + variant_id, + currency_code: 'eur' + } + ] +}) +.then(({ price_list }) => { + console.log(price_list.id); +}); +``` + + + + +```jsx +fetch(`/admin/price-lists/${priceListId}/prices/batch`, { + method: 'POST', + headers: { + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ + prices: [ + { + amount: 1200, + variant_id, + currency_code: 'eur' + } + ] + }) +}) +.then((response) => response.json()) +.then(({ price_list }) => { + console.log(price_list.id) +}) +``` + + + + +```bash +curl --location --request POST '/admin/price-lists/' \ +--header 'Authorization: Bearer {api_token}' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "prices": [ + { + "amount": 1200, + "variant_id": "", + "currency_code": "eur" + } + ] +}' +``` + + + + +This request returns the price list with the updated prices. + +For a full list of request body parameters, check out the [API reference](https://docs.medusajs.com/api/admin/#tag/Price-List/operation/PostPriceListsPriceListPricesBatch). + +### Delete a Product’s Prices + +You can delete all the prices of a product’s variants using the [Delete Product Prices](https://docs.medusajs.com/api/admin/#tag/Price-List/operation/DeletePriceListsPriceListProductsProductPrices) endpoint: + + + + +```jsx +medusa.admin.priceLists.deleteProductPrices(priceListId, productId) +.then(({ ids, object, deleted }) => { + console.log(ids.length); +}); +``` + + + + +```jsx +fetch(`/admin/price-lists/${priceListId}/products/${productId}/prices`, { + method: 'DELETE' +}) +.then((response) => response.json()) +.then(({ ids, object, deleted }) => { + console.log(ids.length) +}) +``` + + + + +```bash +curl --location --request DELETE '/admin/price-lists//products//prices' \ +--header 'Authorization: Bearer {api_token}' +``` + + + + +This request returns the IDs of the deleted prices. + +### Delete a Variant’s Prices + +You can delete all the prices of a variant using the [Delete Variant Prices](https://docs.medusajs.com/api/admin/#tag/Price-List/operation/DeletePriceListsPriceListVariantsVariantPrices) endpoint: + + + + +```jsx +medusa.admin.priceLists.deleteVariantPrices(priceListId, variantId) +.then(({ ids, object, deleted }) => { + console.log(ids); +}); +``` + + + + +```jsx +fetch(`/admin/price-lists/${priceListId}/variants/${variantId}/prices`, { + method: 'DELETE' +}) +.then((response) => response.json()) +.then(({ ids, object, deleted }) => { + console.log(ids.length) +}) +``` + + + + +```jsx +curl --location --request DELETE '/admin/price-lists//variants//prices' \ +--header 'Authorization: Bearer {api_token}' +``` + + + + +This request returns the IDs of the deleted prices. + +--- + +## Delete Price List + +You can delete a price list, and subsequently all prices defined in it, using the [Delete Price List](https://docs.medusajs.com/api/admin/#tag/Price-List/operation/DeletePriceListsPriceList) endpoint: + + + + +```jsx +medusa.admin.priceLists.delete(priceListId) +.then(({ id, object, deleted }) => { + console.log(id); +}); +``` + + + + +```jsx +fetch(`/admin/price-lists/${priceListId}`, { + method: 'DELETE' +}) +.then((response) => response.json()) +.then(({ id, object, deleted }) => { + console.log(id) +}) +``` + + + + +```jsx +curl --location --request DELETE '/admin/price-lists/' \ +--header 'Authorization: Bearer {api_token}' +``` + + + + +This request returns the ID of the deleted price list. + +--- + +## What’s Next 🚀 + +- Learn more about [price lists](./index.md). +- Learn how the [price selection strategy works](../price-selection-strategy/index.md). \ No newline at end of file diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js index 2b1fafd43d..6087159e06 100644 --- a/www/docs/sidebars.js +++ b/www/docs/sidebars.js @@ -220,6 +220,10 @@ module.exports = { id: "advanced/backend/taxes/manual-calculation", label: "Calculate Taxes Manually" }, + { + type: "doc", + id: "advanced/backend/price-lists/use-api" + }, ] }, {