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 [email protected] -p some-password

Start medusa

yarn dev