Skip to main content

REST API Endpoints

The suma-elementor theme registers 18+ custom REST API endpoints covering pricing, cart, crypto payments, orders, dealer locations, mobile app, Klaviyo webhooks, and system utilities.

All endpoints are registered in web/app/themes/suma-elementor/inc/endpoints/ on the rest_api_init hook.

Base URL​

All endpoints are prefixed with /wp-json/.

Pricing & Product Endpoints​

POST /wp-json/suma/v1/product/update-prices​

Class: \Suma\Endpoints\Pricing Auth: Bearer token (called by the external Laravel pricing middleware) Frequency: Every minute

Purpose: Receives updated precious metals spot prices and premiums from the Laravel middleware and updates WooCommerce product prices accordingly.

This is the most performance-critical endpoint in the codebase. The price update pipeline must complete quickly to ensure prices are always current.

Request body:

{
  "products": [
    {
      "sku": "SM-1OZ-SILVER-BAR",
      "price": 29.95,
      "sale_price": null,
      "spot_price": 27.50
    }
  ]
}

Response:

{
  "updated": 45,
  "skipped": 3,
  "errors": []
}

POST /wp-json/suma/v1/product/start-sales​

Class: \Suma\Endpoints\Pricing Auth: Auth (cron/internal)

Purpose: Starts scheduled product sales when their start date/time is reached.

POST /wp-json/suma/v1/product/end-expired-sales​

Class: \Suma\Endpoints\Pricing Auth: Auth (cron/internal)

Purpose: Ends product sales that have passed their expiry date.

POST /wp-json/suma/v1/product/spot-price-alert-email​

Class: \Suma\Endpoints\Pricing Auth: Auth

Purpose: Triggers spot price alert emails to customers who have signed up for price notifications at a specific target price.

POST /wp-json/suma/v1/trends​

Class: \Suma\Endpoints\Trends Auth: Public

Purpose: Returns historical pricing trend data for the NFusion live price chart widget and any front-end price trend displays.

Request body:

{
  "metal": "silver",
  "period": "1month"
}

Cart Endpoints​

POST /wp-json/suma/cart/update​

Class: \Suma\Endpoints\Cart Auth: Session (WooCommerce session cookie)

Purpose: Updates cart item quantities or adds/removes items. Used by the Elementor-based cart widget for real-time cart manipulation without page reload.

POST /wp-json/suma/cart/status​

Class: \Suma\Endpoints\Cart Auth: Session

Purpose: Returns the current cart state (items, totals, shipping estimate). Enables real-time cart count updates in the navigation bar.

POST /wp-json/suma/cart/coupons​

Class: \Suma\Endpoints\Cart Auth: Session

Purpose: Applies or removes coupon codes from the cart. Returns updated cart totals.

Crypto Payment Endpoints​

POST /wp-json/suma/v1/check_crypto_payments​

Class: \Suma\Endpoints\Crypto Auth: Auth

Purpose: Checks the payment status of pending CryptoWoo cryptocurrency orders against the blockchain. Updates order statuses for confirmed payments.

Order Endpoints​

GET /wp-json/suma/account/list-orders​

Class: \Suma\Endpoints\Orders Auth: Logged-in user (cookie)

Purpose: Returns a paginated list of the current user's WooCommerce orders. Used by the mobile app and custom My Account page.

Query parameters:

  • page — Page number (default: 1)
  • per_page — Items per page (default: 10)
  • status — Filter by order status

GET /wp-json/suma/account/download-orders​

Class: \Suma\Endpoints\Orders Auth: Logged-in user (cookie) or shop_manager

Purpose: Exports the user's order history as a downloadable CSV file.

Dealer Locator Endpoints​

POST /wp-json/suma/dealers/import​

Class: \Suma\Endpoints\Dealers Auth: shop_manager or administrator

Purpose: Imports dealer location data (from CSV or JSON) into the dealer locator system.

Algolia Feed​

GET /wp-json/suma/algolia/events/feed​

Class: \Suma\Endpoints\Feed Auth: Public

Purpose: Provides an event feed for Algolia Insights event tracking. Called by the Algolia SDK to record search interaction events (clicks, conversions).

POST /wp-json/suma/klaviyo/posts_feed​

Class: \Suma\Endpoints\Feed Auth: Auth

Purpose: Returns blog post data formatted for Klaviyo email personalization blocks.

Mobile App Endpoints​

POST /wp-json/suma/mobile_app/error​

Class: \Suma\Endpoints\MobileApp Auth: API Key (MOBILE_APP_API_KEY env var in Authorization header)

Purpose: Receives and logs error reports from the Scottsdale Mint mobile app.

GET /wp-json/v2/suma/mobile_app/home_images​

Class: \Suma\Endpoints\MobileApp Auth: API Key

Purpose: Returns the current set of home screen banner images for the mobile app. Images are managed in the WordPress admin as a custom option/ACF field.

Klaviyo Webhook Endpoints​

POST /wp-json/suma/v1/klaviyo-failed-order​

Class: \Suma\Endpoints\KlaviyoWebhooks Auth: Klaviyo HMAC signature verification

Purpose: Receives a webhook from Klaviyo when an abandoned order or failed order event is triggered. Updates the WooCommerce order record accordingly.

POST /wp-json/suma/v1/klaviyo-partially-paid​

Class: \Suma\Endpoints\KlaviyoWebhooks Auth: Klaviyo HMAC signature verification

Purpose: Receives a Klaviyo webhook for orders in the partially-paid status (bank wire deposits). Triggers the appropriate Klaviyo flow for bank wire reminder notifications.

System Utilities​

POST /wp-json/suma/v1/utils/clear_cache​

Class: \Suma\Endpoints\Utils Auth: shop_manager or administrator

Purpose: Flushes the Redis object cache. Equivalent to running wp cache flush but accessible via REST API for automation scripts.

ACH Gateway Endpoints (from scottsdale-ach-gateway plugin)​

POST /wp-json/plaid/get-access-token​

See Scottsdale ACH Gateway Plugin for full documentation.

POST /wp-json/plaid/remove-account​

See Scottsdale ACH Gateway Plugin.

Kount ENS Callback (from integration class)​

POST /wp-json/kount/v1/ens​

See Kount ENS Webhook for full documentation.

Dealer Locator (from suma-dealer-locator plugin)​

GET /wp-json/dealer-locator/get-dealers​

See Dealer Locator for full documentation.

Authentication Summary​

Auth TypeUsed ByImplementation
WP Cookie (logged-in)list-orders, download-orders, cart/*Standard WP is_user_logged_in()
shop_manager/admin roledealers/import, utils/clear_cachecurrent_user_can() check
API Key (header)Mobile app endpointsMOBILE_APP_API_KEY env var
Bearer tokenproduct/update-pricesInternal Laravel→WP auth
Klaviyo HMACKlaviyo webhooksHMAC signature verified against Klaviyo signing key
Kount signatureKount ENSKount-provided signature validation
WP NoncePlaid REST routesFrontend::render_api_nonce() in footer
Publictrends, algolia/events/feedNo auth required