Plugin to manage product availability in medusa
Table of Contents
- Table of Contents
- Usage
- Installation
- Admin Panel
- Store API References
- Types
- GetAvailabilityResponseType
- Env variables
- Start the project for contribution
Usage
Installation
- Run the following command to install
1yarn add medusa-customizable-product-availability
- Add the plugin in your medusa plugin list to load it
Open the Copy to clipboard
medusa-config.js
locate the Copy to clipboardplugins
variable and add these lines
123456789const plugins = [// ...{resolve: "medusa-customizable-product-availability",options: {enableUI: true, // load the admin part of the plugin},},];
- Run migrations
1npx medusa migrations run
Admin Panel
In the sidebar of the admin area, you'll find a Copy to clipboard
Availabilities
menu, which allows you to access the availability management area.Store API References
Retrieve list of availabilities
Copy to clipboardGET
store/availabilities
Query parameters
name type data type description page optional number The current page of the list. The default is Copy to clipboard 0
limit optional number The size of the result | forProduct | optional | string | Allow to filter and only get availabilities related to a product. Copy to clipboardforProduct
must be the id of the product |
Responses
| http code | content-type | response |
Get Availability By ID
Copy to clipboardGET
store/availabilities/{availabilityId}
Responses
| http code | content-type | response |
Check if a product is available on an availability
Copy to clipboardGET
products/{productId}/is-available-on
Route parameters
| name | type | data type | description || productId | require | string | The ID of the product whose availability you wish to check |
Query parameters
| name | type | data type | description || availabilityId | required | string | The ID of the availability to be checked. |
Responses
| http code | content-type | response || Copy to clipboard200
| Copy to clipboardapplication/json
| CheckProductAvailableOnAvailabilityResult |
Retrieve product availabilities for an availability
Copy to clipboardGET
store/availabilities/{availabilityId}/products-availabilities
Route parameters
- Copy to clipboard
availabilityId
the id of the availability
Responses
| http code | content-type | response || Copy to clipboard200
| Copy to clipboardapplication/json
| GetAvailabilityProductAvailabilitiesResponseType |
Set availability on a cart
Copy to clipboardPOST
store/carts/{cartId}/set-availability
Route parameters
- Copy to clipboard
cartId
the cart identifier on which you wish to define availability
Request body
Must be a JSON object. Ensure that the Copy to clipboardContent-Type
header is set Copy to clipboardapplication/json
| property | description || availabilityId | The id of the availability |
Responses
| http code | content-type | response || Copy to clipboard200
| Copy to clipboardapplication/json
| GetAvailabilityProductAvailabilitiesResponseType |
Verify if the cart items match the availability
This endpoint allows you to check whether the cart meets the availability conditions defined.
Copy to clipboardGET
store/carts/{cartId}/verify-if-matches-availability
Route parameters
- Copy to clipboard
cartId
the cart identifier on which you wish to define availability
Responses
http code content-type response Copy to clipboard 200
Copy to clipboard application/json
APIOperationResponseType | Copy to clipboard400
| Copy to clipboardapplication/json
| Reed more on cart validation error reference |
Types
GetAvailabilitiesResponseType
GetAvailabilitiesResponseType
12345678export interface GetAvailabilitiesResponseType {data: GetAvailabilitiesResponseData;}export interface GetAvailabilitiesResponseData {availabilities: Omit<Availability, "availabilityProducts">[];totalCount: number;}
GetAvailabilityResponseType
GetAvailabilityResponseType
123export interface GetAvailabilityResponseType {data: Omit<Availability, "availabilityProducts">;}
CheckProductAvailableOnAvailabilityResult
CheckProductAvailableOnAvailabilityResult
12345export interface CheckProductAvailableOnAvailabilityResult {data: {exists: boolean;};}
GetAvailabilityProductAvailabilitiesResponseType
GetAvailabilityProductAvailabilitiesResponseType
123export interface GetAvailabilityProductAvailabilitiesResponseType {data: AvailabilityProduct[];}
APIOperationResponseType
APIOperationResponseType
12345export interface APIOperationResponseType {data: {success: boolean;};}
Availability
Availability
12345678910111213141516export interface Availability {id: string;created_at: Date;updated_at: Date;status: string;date: Date;availabilityProducts: AvailabilityProduct[];}export interface AvailabilityProduct {id: string;created_at: Date;updated_at: Date;quantity: number;product: Product; // medusa product}
Cart validation error reference
The errors listed here are those related to the validation of the cart in relation to the defined availability.
The validation of the cart is done while completing it.
When a validation error is triggered, the HTTP code of the response is Copy to clipboard
422
.
And the response is in the form of1234567891011121314enum CartValidationErrorCode {AVAILABILITY_EXPIRED = "AVAILABILITY_EXPIRED",AVAILABILITY_INACTIVE = "AVAILABILITY_INACTIVE",AVAILABILITY_NOT_SET_ON_CART = "AVAILABILITY_NOT_SET_ON_CART",PRODUCT_NOT_AVAILABLE_ON_AVAILABILITY = "PRODUCT_NOT_AVAILABLE_ON_AVAILABILITY",PRODUCT_NO_LONGER_AVAILABLE_ON_AVAILABILITY = "PRODUCT_NO_LONGER_AVAILABLE_ON_AVAILABILITY",AVAILABLE_QUANTITY_EXCEEDED = "AVAILABLE_QUANTITY_EXCEEDED",}type ErrorResponse {message: string;code: CartValidationErrorCode;payload?: object;}
The Copy to clipboard
payload
property provides more information about the error, which can be used to provide more edifying information to the user. This property can vary depending on the error.Error codes details
- Copy to clipboard
AVAILABILITY_EXPIRED
the date defined on the availability is passed - Copy to clipboard
AVAILABILITY_INACTIVE
the availability is disabled by the admin - Copy to clipboard
AVAILABILITY_NOT_SET_ON_CART
you don't define an availability on the cart you are trying to complete. See how here - Copy to clipboard
PRODUCT_NOT_AVAILABLE_ON_AVAILABILITY
a product of the cart is not defined as available on the availability defined on the cart In this case the payload is in this form
123type Payload = {productTitle: string; // the title of the product};
- Copy to clipboard
PRODUCT_NO_LONGER_AVAILABLE_ON_AVAILABILITY
the availability quantity defined for the product is out of stock. The payload is in same type as Copy to clipboardPRODUCT_NOT_AVAILABLE_ON_AVAILABILITY
error. - Copy to clipboard
AVAILABLE_QUANTITY_EXCEEDED
the quantity of products requested for purchase is less than the quantity available according to availability. In this case the payload look like this
1234type Payload = {availableQuantity: number; // the now available quantity,productTitle: string; // the title of the product};
Env variables
| name | value type | description || Copy to clipboardAVAILABILITY_VALIDATION_TIMEZONE
| Timezone | The timezone that will be used to validate availability date. |
Start the project for contribution
Create environment file
Run the following command to create the environment from example file
1cp .env.template .env
You can keep the environment variables value if you are going to use the provided docker compose
Setup medusa
Before you start medusa setup ensure that you start the database with the following command
1docker compose up
Run migration
Run the following command to apply migrations
1yarn medusa migrations run
Side you database
1yarn seed
Create user
1npx medusa user -e some@email.com -p some-password
Start medusa
1yarn dev