Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/aerele/medusa_integration/llms.txt

Use this file to discover all available pages before exploring further.

The Medusa Configuration doctype is the single place in ERPNext where you control the ERPNext Medusa Integration. It holds the connection details for your Medusa backend, the admin credentials used to obtain API tokens, and optional coupon discount rules that are pushed to Medusa.
Only users with the System Manager role can read or write the Medusa Configuration doctype. Ensure the user performing setup has this role assigned before opening the form.

​
Connection settings

​
body.enable
boolean
default:"false"
Enables or disables the entire integration. When unchecked, no data is pushed to or pulled from Medusa, regardless of document events or scheduled tasks. All other connection fields are hidden in the form until this is checked.
​
body.url
string
required
The base URL of your Medusa backend, including the protocol (for example, https://your-medusa-backend.com). All Admin API requests are sent to this URL. This field is only shown when Enable is checked.
​
body.frontend_url
string
The base URL of your Medusa storefront (for example, https://shop.example.com). This URL is used when composing notification emails sent to customers, such as quotation links. It is not required for the core sync to work.

​
Admin credentials

​
body.admin_email
string
required
The email address of an admin user on your Medusa backend. The integration uses this account to authenticate and obtain a Bearer token for all Admin API calls. This field is only shown when Enable is checked.
​
body.admin_password
string
required
The password for the admin account specified in Admin Email. The value is stored as a hashed password field in ERPNext and is never returned in plain text after saving. This field is only shown when Enable is checked.
​
body.access_token
string
The Bearer token used to authorize Admin API requests to Medusa. This field is hidden in the form and is managed automatically by the integration — you do not need to set it manually.The token is fetched by calling the Medusa /admin/auth endpoint with your Admin Email and Admin Password when the integration first connects. If any API call returns a 401 Unauthorized response, the integration calls get_access_token() transparently to refresh the token and retries the request.
If you rotate your Medusa admin password, update Admin Password in Medusa Configuration and save the form. The integration will obtain a fresh token on the next API call.

​
Coupon discount details

This section controls optional coupon discounts that the integration can create and manage in Medusa. Enable this section if you want ERPNext to push coupon discount rules to your storefront.
​
body.allow_coupon_discounts
boolean
default:"false"
Enables coupon discount support. When checked, the fields below become active and the integration pushes the configured discount rules to Medusa.
​
body.cart_value
number
The minimum order subtotal (in your base currency) that a customer’s cart must reach before a coupon discount can be applied. For example, entering 500 means coupons are only valid on orders of 500 or more.Stored as a Currency field with three decimal places of precision.
​
body.discount_amount
number
The flat discount amount (in your base currency) deducted from the order when a valid coupon is applied.Stored as a Currency field.
​
body.coupon_expiry_date
string
The date after which coupons created under these rules are no longer valid. Use the YYYY-MM-DD format, or select a date using the ERPNext date picker.

​
How the access token is managed

The integration follows this flow every time it calls the Medusa Admin API: This means the Access Token field is always kept current without any manual intervention. The only time you need to take action is if the admin credentials themselves change.

​
Example: minimal configuration

The following values represent a minimal working configuration with coupon discounts disabled: 
{
  "enable": true,
  "url": "https://your-medusa-backend.com",
  "admin_email": "[email protected]",
  "admin_password": "••••••••",
  "frontend_url": "https://shop.example.com"
}

Quickstart

Step-by-step installation and first configuration walkthrough.

Sync guides

Learn how each data sync uses these configuration values at runtime.

Build docs developers (and LLMs) love

Get started for freeTalk to us