medusa-product-availability-plugin v0.0.18

Table of Contents

• Table of Contents
• Usage
  • Installation
  • Admin Panel
  • Store API References
    • Retrieve list of availabilities
      • Query parameters
      • Responses
    • Get Availability By ID
      • Responses
    • Check if a product is available on an availability
      • Route parameters
      • Query parameters
      • Responses
    • Retrieve product availabilities for an availability
      • Route parameters
      • Responses
    • Set availability on a cart
      • Route parameters
      • Request body
      • Responses
    • Verify if the cart items match the availability
      • Route parameters
      • Responses
  • Types
    • GetAvailabilitiesResponseType
  • GetAvailabilityResponseType
    • CheckProductAvailableOnAvailabilityResult
    • GetAvailabilityProductAvailabilitiesResponseType
    • APIOperationResponseType
    • Availability
    • Cart validation error reference
  • Env variables
• Start the project for contribution
  • Create environment file
  • Setup medusa
    • Run migration
    • Side you database
    • Create user
  • Start medusa

Usage

Installation

• Run the following command to install

yarn add medusa-customizable-product-availability

• Add the plugin in your medusa plugin list to load it Open the medusa-config.js locate the plugins variable and add these lines

const plugins = [
  // ...
  {
    resolve: "medusa-customizable-product-availability",
    options: {
      enableUI: true, // load the admin part of the plugin
    },
  },
];

• Run migrations

npx medusa migrations run

Admin Panel

In the sidebar of the admin area, you'll find a Availabilities menu, which allows you to access the availability management area.

Store API References

Retrieve list of availabilities

Query parameters

name	type	data type	description
page	optional	number	The current page of the list. The default is 0
limit	optional	number	The size of the result
forProduct	optional	string	Allow to filter and only get availabilities related to a product. forProduct must be the id of the product

Responses

http code	content-type	response
200	application/json	GetAvailabilitiesResponseType

Get Availability By ID

Responses

http code	content-type	response
200	application/json	GetAvailabilityResponseType

Check if a product is available on an availability

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
200	application/json	CheckProductAvailableOnAvailabilityResult

Retrieve product availabilities for an availability

Route parameters

• availabilityId the id of the availability

Responses

http code	content-type	response
200	application/json	GetAvailabilityProductAvailabilitiesResponseType

Set availability on a cart

Route parameters

• cartId the cart identifier on which you wish to define availability

Request body

Must be a JSON object. Ensure that the Content-Type header is set application/json

property	description
availabilityId	The id of the availability

Responses

http code	content-type	response
200	application/json	GetAvailabilityProductAvailabilitiesResponseType

Verify if the cart items match the availability

This endpoint allows you to check whether the cart meets the availability conditions defined.

Route parameters

• cartId the cart identifier on which you wish to define availability

Responses

http code	content-type	response
200	application/json	APIOperationResponseType
400	application/json	Reed more on cart validation error reference

Types

GetAvailabilitiesResponseType

export interface GetAvailabilitiesResponseType {
  data: GetAvailabilitiesResponseData;
}

export interface GetAvailabilitiesResponseData {
  availabilities: Omit<Availability, "availabilityProducts">[];
  totalCount: number;
}

GetAvailabilityResponseType

export interface GetAvailabilityResponseType {
  data: Omit<Availability, "availabilityProducts">;
}

CheckProductAvailableOnAvailabilityResult

export interface CheckProductAvailableOnAvailabilityResult {
  data: {
    exists: boolean;
  };
}

GetAvailabilityProductAvailabilitiesResponseType

export interface GetAvailabilityProductAvailabilitiesResponseType {
  data: AvailabilityProduct[];
}

APIOperationResponseType

export interface APIOperationResponseType {
  data: {
    success: boolean;
  };
}

Availability

export 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 422. And the response is in the form of

enum 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 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

• AVAILABILITY_EXPIRED the date defined on the availability is passed
• AVAILABILITY_INACTIVE the availability is disabled by the admin
• AVAILABILITY_NOT_SET_ON_CART you don't define an availability on the cart you are trying to complete. See how here
• 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

type Payload = {
  productTitle: string; // the title of the product
};

• PRODUCT_NO_LONGER_AVAILABLE_ON_AVAILABILITY the availability quantity defined for the product is out of stock. The payload is in same type as PRODUCT_NOT_AVAILABLE_ON_AVAILABILITY error.

• 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

type Payload = {
  availableQuantity: number; // the now available quantity,
  productTitle: string; // the title of the product
};

Env variables

name	value type	description
AVAILABILITY_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

cp .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

docker compose up

Run migration

Run the following command to apply migrations

yarn medusa migrations run

Side you database

yarn seed

Create user

npx medusa user -e some@email.com -p some-password

Start medusa

yarn dev