Book a demo
Start for free Book demo

API Reference

v1.0.0 · REST API + MCP server for subscriptions, pre-orders, and sent notifications

Open the interactive API reference ↗

Introduction

The Notify Me! Public API lets you programmatically manage subscriptions, pre-orders, and the notifications we send to your customers on your behalf. Every endpoint returns JSON and requires a valid API key.

Generate an API key from your Notify Me! admin panel, then include it as the X-Api-Key header on every request.

Try it live ↗ Help center article ↗

Authentication

All API requests require authentication with an API key sent in the X-Api-Key header.

curl -X GET "https://api.notify-me.app/v1/subscriptions/" \
  -H "X-Api-Key: YOUR_API_KEY"

Requests without a valid key return 401 Unauthorized.

Base URL

All endpoint paths in this reference are relative to the base URL below.

Base https://api.notify-me.app/v1

Rate Limits

To ensure fair usage and system stability, all endpoints share the following limit. Exceeding it returns 429 Too Many Requests with a detail field indicating when to retry.

Endpoint typeLimit
Standard endpoints60 requests / minute

Pagination

List endpoints return paginated results using limit and offset query parameters.

ParameterDescriptionDefaultMaximum
limitNumber of results to return15100
offsetStarting position in the result set0—

Example

GET https://api.notify-me.app/v1/subscriptions/?limit=25&offset=50

Response shape

{
  "count": 150,
  "next": "https://api.notify-me.app/v1/subscriptions/?limit=25&offset=75",
  "previous": "https://api.notify-me.app/v1/subscriptions/?limit=25&offset=25",
  "results": [ ... ]
}

Errors

Errors return a JSON body with a detail field describing the failure.

StatusMeaning
200Success.
401Missing or invalid API key.
403API key valid, but the requested action is not permitted.
404The requested object does not exist.
429Rate limit exceeded. Retry after the interval in the response body.
5xxUnexpected server error. Retry with exponential backoff.

MCP Server

In addition to the REST API, Notify Me! offers a remote MCP (Model Context Protocol) server for LLM clients such as Claude and Cursor. It lets you drive Notify Me! from your AI assistant using natural language instead of REST calls — and unlike the read-only REST API, it includes write tools for settings and widget appearance.

MCP https://mcp.notify-me.app/mcp

The server uses the Streamable HTTP transport. Authenticate with the same API key used above, sent as a bearer token. Access requires the mcp entitlement (separate from the Public API entitlement), and the shop is resolved from the API key — a key can only act on its own shop.

Authorization: Bearer YOUR_API_KEY

The server is tools-only in v1 (no MCP resources or prompts). Reads are aggregate and PII-safe; writes inherit the same permissions, validation, and side-effects as the admin panel and return the old → new diff plus the new state.

Read settings

ToolDescription
get_shop_overviewNon-PII shop snapshot: plan, suspension status, currency, locale, trial / migration / customer-accounts state.
get_bis_settingsBack in Stock settings: service active flag and product selection mode.
get_preorder_settingsPre-Order settings: service active, selling-plan group creation, mixed-cart alert.
get_wishlist_settingsWishlist settings: service active, guest mode, share state, enabled share channels.
get_low_stock_settingsLow Stock settings: whether the service is active.

Read analytics (aggregate)

ToolDescription
get_demand_summaryTop unfilled Back in Stock demand by product / variant with request counts and estimated revenue. Accepts period (7 / 30 / 90 / all) and limit (top-N, max 50).
get_bis_performanceAggregate BIS performance: requests, notifications sent, products in demand, recovered revenue, growth rates.
get_preorder_analyticsAggregate Pre-Order analytics: revenue, pre-ordered variant count, notifications sent, growth rates.
get_wishlist_insightsAggregate Wishlist insights: product count, list count, attributed order revenue, growth rates.
get_low_stock_statusLow Stock notification status: alerts enabled, inventory threshold, send policy.

Change settings (provide only the fields you want to change)

ToolEditable fields
update_bis_settingsis_service_active, product_selection_mode
update_preorder_settingsis_service_active, show_mixed_cart_alert
update_wishlist_settingsis_service_active, is_guest_mode_enabled, share_wishlist_enabled, share_wishlist_channels
update_low_stock_settingsis_service_active

Customize widget appearance

Read a widget's current visibility and colors, toggle its visibility on a storefront page, and change its colors. Color tools preserve untouched style keys, and the read tools return values keyed the same way the change tools accept them — so you can read a widget's appearance and pass it straight back.

ReadChange
get_bis_widget_appearanceset_bis_widget_display / update_bis_widget_colors — Back in Stock (product / collection / home)
get_wishlist_widget_appearanceset_wishlist_widget_visibility / update_wishlist_widget_colors — Wishlist (product / collection / landing / access button)
get_low_stock_widget_appearanceset_low_stock_widget_visibility / update_low_stock_widget_colors — Low Stock
get_preorder_widget_appearanceset_preorder_widget_visibility / update_preorder_widget_colors — Pre-Order (product / collection / landing / cart)

A ping tool is also available to verify connectivity. Because MCP is not a REST protocol, these tools do not appear in the endpoint reference below — see the Help Center for setup instructions.

GET /v1/subscriptions/

List subscriptions

Retrieve a paginated list of subscriptions for your shop.

Parameters

NameInTypeDescription
status query array<string> Filter by status: EXPIRED, RESTOCKED, WAITING_UPGRADE, WAITING_RESTOCK, PENDING_GDPR, SCHEDULED, FRAUD_DETECTED_BY_AI, ORDERED.
email query string Filter by email (case-insensitive).
phone_number query string Filter by phone number (case-insensitive).
whatsapp_number query string Filter by WhatsApp number (case-insensitive).
product_id query number Filter by product ID.
variant_id query number Filter by variant ID.
sku query string Filter by SKU (case-insensitive).
is_imported query boolean Filter by import status.
created_at_gte query string (ISO 8601) Created on or after this date.
created_at_lte query string (ISO 8601) Created on or before this date.
subscribe_at_gte query string (ISO 8601) Subscribed on or after this date.
subscribe_at_lte query string (ISO 8601) Subscribed on or before this date.
sent_at_gte query string (ISO 8601) First-alert notification sent on or after this date.
sent_at_lte query string (ISO 8601) First-alert notification sent on or before this date.
sent_at_isnull query boolean true = pending first alert, false = sent.
ordering query string Sort field. Prefix with - for descending. Allowed: created_at, id, sent_at, subscribe_at.

Example request

curl -X GET "https://api.notify-me.app/v1/subscriptions/" \
  -H "X-Api-Key: YOUR_API_KEY"

Example response

{
  "count": 123,
  "next": "https://api.notify-me.app/v1/subscriptions/?offset=100&limit=100",
  "previous": null,
  "results": [
    {
      "id": 12345,
      "status": "PENDING",
      "subscribe_at": "2024-01-15",
      "sent_at": "2024-01-16T10:30:00Z",
      "created_at": "2024-01-15T08:00:00Z",
      "product_id": 98765,
      "variant_id": 11111,
      "sku": "SKU-001",
      "email": "customer@example.com",
      "phone_number": "+15551234567",
      "whatsapp_number": "+15559876543",
      "locale": "en",
      "is_imported": false
    }
  ]
}
GET /v1/subscriptions/{id}/

Get a subscription

Retrieve details of a specific subscription by ID.

Parameters

NameInTypeDescription
id required path integer A unique integer value identifying this subscription.

Example request

curl -X GET "https://api.notify-me.app/v1/subscriptions/{id}/" \
  -H "X-Api-Key: YOUR_API_KEY"

Example response

{
  "id": 12345,
  "status": "PENDING",
  "subscribe_at": "2024-01-15",
  "sent_at": "2024-01-16T10:30:00Z",
  "created_at": "2024-01-15T08:00:00Z",
  "product_id": 98765,
  "variant_id": 11111,
  "sku": "SKU-001",
  "email": "customer@example.com",
  "phone_number": "+15551234567",
  "whatsapp_number": "+15559876543",
  "locale": "en",
  "is_imported": false
}
GET /v1/subscription-notifications/

List sent notifications

Retrieve a paginated list of subscription sent notifications for your shop.

Parameters

NameInTypeDescription
bundle query array<string> Filter by bundle: FIRST_ALERT, GDPR, AFTER_SUBSCRIPTION, REMINDER.
email query string Filter by email (case-insensitive).
email_status query array<string> Filter by email delivery status (comma-separated).
phone_number query string Filter by phone number.
sms_status query array<string> Filter by SMS status (comma-separated).
whatsapp_number query string Filter by WhatsApp number.
whatsapp_status query array<string> Filter by WhatsApp status.
push_status query array<string> Filter by push notification status.
subscription_id query number Filter by subscription ID.
product_id query number Filter by product ID.
variant_id query number Filter by variant ID.
sku query string Filter by SKU (case-insensitive).
sent_at_gte query string (ISO 8601) Sent on or after this date.
sent_at_lte query string (ISO 8601) Sent on or before this date.
ordering query string Sort field. Allowed: id, sent_at. Prefix with - for descending.

Example request

curl -X GET "https://api.notify-me.app/v1/subscription-notifications/" \
  -H "X-Api-Key: YOUR_API_KEY"

Example response

{
  "count": 123,
  "next": "https://api.notify-me.app/v1/subscription-notifications/?offset=100&limit=100",
  "previous": null,
  "results": [
    {
      "id": 12345,
      "bundle": "FIRST_ALERT",
      "sent_at": "2024-01-15T08:00:00Z",
      "subscription_id": 67890,
      "product_id": 98765,
      "variant_id": 11111,
      "sku": "SKU-12345",
      "email": "customer@example.com",
      "phone_number": "+15551234567",
      "whatsapp_number": "+15559876543",
      "email_stat": {
        "status": "DELIVERED"
      },
      "sms_stat": {
        "status": "DELIVERED",
        "segments_count": 2
      },
      "push_stat": null,
      "whatsapp_stat": null
    }
  ]
}
GET /v1/subscription-notifications/{id}/

Get a sent notification

Retrieve details of a specific subscription sent notification by ID.

Parameters

NameInTypeDescription
id required path integer A unique integer value identifying this subscription sent notification.

Example request

curl -X GET "https://api.notify-me.app/v1/subscription-notifications/{id}/" \
  -H "X-Api-Key: YOUR_API_KEY"

Example response

{
  "id": 12345,
  "bundle": "FIRST_ALERT",
  "sent_at": "2024-01-15T08:00:00Z",
  "subscription_id": 67890,
  "product_id": 98765,
  "variant_id": 11111,
  "sku": "SKU-12345",
  "email": "customer@example.com",
  "phone_number": "+15551234567",
  "whatsapp_number": "+15559876543",
  "email_stat": {
    "status": "DELIVERED"
  },
  "sms_stat": {
    "status": "DELIVERED",
    "segments_count": 2
  },
  "push_stat": null,
  "whatsapp_stat": null
}
GET /v1/pre-orders/

List shop pre-orders

Retrieve a paginated list of shop pre-orders for your shop.

Parameters

NameInTypeDescription
financial_status query array<string> Filter by financial status: AUTHORIZED, PAID, PARTIALLY_PAID, PARTIALLY_REFUNDED, PENDING, REFUNDED, VOIDED.
fulfillment_status query array<string> Filter by fulfillment status: FULFILLED, IN_PROGRESS, ON_HOLD, OPEN, RESTOCKED, PARTIALLY_FULFILLED, PENDING_FULFILLMENT, SCHEDULED, UNFULFILLED.
cancelled_at_isnull query boolean true = active, false = cancelled.
email query string Filter by customer email (case-insensitive).
shopify_order_id query integer Filter by Shopify order ID.
product_id query integer Filter by Shopify product ID.
variant_id query integer Filter by Shopify variant ID.
sku query string Filter by SKU (case-insensitive).
selling_plan_settings_name query string Filter by selling plan settings name.
created_at_gte query string (ISO 8601) Created on or after this date.
created_at_lte query string (ISO 8601) Created on or before this date.
ordering query string Sort field. Allowed: created_at, id, total_price. Prefix with - for descending.

Example request

curl -X GET "https://api.notify-me.app/v1/pre-orders/" \
  -H "X-Api-Key: YOUR_API_KEY"

Example response

{
  "count": 123,
  "next": "https://api.notify-me.app/v1/pre-orders/?offset=100&limit=100",
  "previous": null,
  "results": [
    {
      "id": 12345,
      "shopify_order_id": 9876543210,
      "email": "customer@example.com",
      "phone_number": "+15551234567",
      "created_at": "2024-01-15T08:00:00Z",
      "total_price": 99.99,
      "product_price": 49.99,
      "product_ordered_quantity": 2,
      "financial_status": "PAID",
      "fulfillment_status": "UNFULFILLED",
      "locale": "en",
      "cancelled_at": null,
      "cancellation_reason": null,
      "product_id": 98765,
      "variant_id": 11111,
      "variant_sku": "SKU-001",
      "selling_plan_settings_name": "Summer Pre-Order"
    }
  ]
}
GET /v1/pre-orders/{id}/

Get a pre-order

Retrieve details of a specific shop pre-order by ID.

Parameters

NameInTypeDescription
id required path integer A unique integer value identifying this shop pre-order.

Example request

curl -X GET "https://api.notify-me.app/v1/pre-orders/{id}/" \
  -H "X-Api-Key: YOUR_API_KEY"

Example response

{
  "id": 12345,
  "shopify_order_id": 9876543210,
  "email": "customer@example.com",
  "phone_number": "+15551234567",
  "created_at": "2024-01-15T08:00:00Z",
  "total_price": 99.99,
  "product_price": 49.99,
  "product_ordered_quantity": 2,
  "financial_status": "PAID",
  "fulfillment_status": "UNFULFILLED",
  "locale": "en",
  "cancelled_at": null,
  "cancellation_reason": null,
  "product_id": 98765,
  "variant_id": 11111,
  "variant_sku": "SKU-001",
  "selling_plan_settings_name": "Summer Pre-Order"
}
GET /v1/pre-order-notifications/

List sent notifications

Retrieve a paginated list of pre-order sent notifications for your shop.

Parameters

NameInTypeDescription
bundle query array<string> Filter by bundle: PRE_ORDER, DELAYED_SHIPMENT.
email query string Filter by email (case-insensitive).
email_status query array<string> Filter by email delivery status.
phone_number query string Filter by phone number.
sms_status query array<string> Filter by SMS status.
pre_order_id query integer Filter by pre-order ID.
sent_at_gte query string (ISO 8601) Sent on or after this date.
sent_at_lte query string (ISO 8601) Sent on or before this date.
ordering query string Sort field. Allowed: id, sent_at. Prefix with - for descending.

Example request

curl -X GET "https://api.notify-me.app/v1/pre-order-notifications/" \
  -H "X-Api-Key: YOUR_API_KEY"

Example response

{
  "count": 123,
  "next": "https://api.notify-me.app/v1/pre-order-notifications/?offset=100&limit=100",
  "previous": null,
  "results": [
    {
      "id": 12345,
      "bundle": "PRE_ORDER",
      "sent_at": "2024-01-15T08:00:00Z",
      "pre_order_ids": [
        100,
        101,
        102
      ],
      "email": "customer@example.com",
      "phone_number": "+15551234567",
      "email_stat": {
        "status": "DELIVERED"
      },
      "sms_stat": null
    }
  ]
}
GET /v1/pre-order-notifications/{id}/

Get a sent notification

Retrieve details of a specific pre-order sent notification by ID.

Parameters

NameInTypeDescription
id required path integer A unique integer value identifying this pre-order sent notification.

Example request

curl -X GET "https://api.notify-me.app/v1/pre-order-notifications/{id}/" \
  -H "X-Api-Key: YOUR_API_KEY"

Example response

{
  "id": 12345,
  "bundle": "PRE_ORDER",
  "sent_at": "2024-01-15T08:00:00Z",
  "pre_order_ids": [
    100,
    101,
    102
  ],
  "email": "customer@example.com",
  "phone_number": "+15551234567",
  "email_stat": {
    "status": "DELIVERED"
  },
  "sms_stat": null
}

Start recovering
lost sales today

Join 35,000+ Shopify and BigCommerce merchants using Notify Me! to turn out-of-stock moments into revenue. Free to install, live in minutes.

Schedule a demo Start free
4.9/5 on the Shopify App Store · 3,400+ reviews
Company
Brand kit
Explore more
Platform
Platform
Never Lose a Sale
© 2026 All rights reserved.
Terms of service Privacy policy