Endpoints v26.7+

Auth

"Current customer" and password reset are part of the Customer resource, see Customers.

Store Configuration

Country listings live under Directory (/countries).

Products & Catalog

Sub-resources (parent path parameter is {productId} throughout):

Layered navigation:

Categories

Cart (Authenticated)

Guest Cart

{id} is the masked cart ID returned by POST /guest-carts.

Customers

Addresses (Address resource, same DTO is exposed under three URL families):

Orders

Guest order lookup (GET /orders/{incrementId}/details): a public, unauthenticated endpoint for rendering order-confirmation views in headless/guest checkouts. The per-order token is passed in the X-Order-Token header (never the query string, which would leak into access logs). The token is single-use: it's cleared on the first successful read, so refreshing the page won't replay the lookup. The endpoint is IP rate-limited to prevent brute-forcing a token against a known increment ID. A missing/invalid token or unknown increment ID returns 404. If no customer account exists for the order's email, the response includes an accountToken the frontend can use with POST /customers/create-from-order.

curl /api/rest/v2/orders/100000123/details \
  -H 'X-Order-Token: <one-time-token>'

The GraphQL counterpart is the guestOrder(incrementId, accessToken) query (same one-time-use semantics).

Order sub-resources:

Customer invoice access:

Shipments

Create shipment:

curl -X POST /api/rest/v2/orders/123/shipments \
  -H 'Authorization: Bearer eyJ...' \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [{"orderItemId": 456, "qty": 2}],
    "tracks": [{"carrierCode": "auspost", "title": "Australia Post", "trackNumber": "AP123456"}],
    "comment": "Shipped via express",
    "notifyCustomer": true
  }'

Omit items to ship every remaining item on the order. Each track entry needs at least trackNumber; carrierCode defaults to custom and title defaults to the carrier code.

Credit Memos / Refunds

Create a credit memo:

curl -X POST /api/rest/v2/orders/123/credit-memos \
  -H 'Authorization: Bearer eyJ...' \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
      {"orderItemId": 456, "qty": 1, "backToStock": true}
    ],
    "comment": "Customer returned item",
    "adjustmentPositive": 5.00,
    "adjustmentNegative": 0,
    "offlineRefund": true
  }'

Response:

{
  "id": 789,
  "incrementId": "100000001",
  "orderId": 123,
  "orderIncrementId": "100000456",
  "state": "refunded",
  "grandTotal": 29.95,
  "baseGrandTotal": 29.95,
  "subtotal": 24.95,
  "taxAmount": 0,
  "shippingAmount": 0,
  "discountAmount": 0,
  "adjustmentPositive": 5.00,
  "adjustmentNegative": 0,
  "items": [
    {
      "id": 101,
      "orderItemId": 456,
      "sku": "TENNIS-BALL-3PK",
      "name": "Tennis Balls (3 pack)",
      "qty": 1,
      "price": 24.95,
      "rowTotal": 24.95,
      "taxAmount": 0,
      "discountAmount": 0,
      "backToStock": true
    }
  ],
  "comment": "Customer returned item"
}

Parameters: - items[], Array of items to refund. Each requires orderItemId and qty. Optional: backToStock (boolean, returns qty to inventory). - comment, Optional refund note. - adjustmentPositive, Additional positive adjustment (add to refund). - adjustmentNegative, Negative adjustment (reduce refund). - offlineRefund, true (default) for offline refund, false to trigger payment gateway refund.

GraphQL:

mutation {
  createCreditMemo(input: {
    orderId: 123
    items: [{orderItemId: 456, qty: 1, backToStock: true}]
    comment: "Returned"
    offlineRefund: true
  }) {
    id
    incrementId
    state
    grandTotal
  }
}

Invoices

There is no standalone collection endpoint or write endpoint for invoices, they are produced as part of the order workflow.

Inventory / Stock Updates

Fast direct-SQL stock updates, no model overhead, no observers.

Single update:

curl -X PUT /api/rest/v2/inventory \
  -H 'Authorization: Bearer eyJ...' \
  -H 'Content-Type: application/json' \
  -d '{
    "sku": "TENNIS-BALL-3PK",
    "qty": 150,
    "isInStock": true,
    "manageStock": true
  }'

Response:

{
  "sku": "TENNIS-BALL-3PK",
  "qty": 150,
  "isInStock": true,
  "manageStock": true,
  "previousQty": 42,
  "success": true
}

Bulk update:

curl -X PUT /api/rest/v2/inventory/bulk \
  -H 'Authorization: Bearer eyJ...' \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
      {"sku": "TENNIS-BALL-3PK", "qty": 150},
      {"sku": "RACQUET-PRO-V2", "qty": 25, "isInStock": true},
      {"sku": "GRIP-TAPE-WHT", "qty": 0}
    ]
  }'

Notes: - isInStock auto-sets to qty > 0 if not provided. - manageStock defaults to true if not provided. - Qty must be 0–99,999,999. - Bulk limit: 100 items per request (validated upfront, executed in a DB transaction).

GraphQL:

mutation {
  updateStock(input: {sku: "TENNIS-BALL-3PK", qty: 150}) {
    sku
    qty
    previousQty
    success
  }
}

mutation {
  updateStockBulk(input: {
    items: [
      {sku: "TENNIS-BALL-3PK", qty: 150},
      {sku: "RACQUET-PRO-V2", qty: 25}
    ]
  }) {
    success
    results {
      sku
      qty
      previousQty
    }
  }
}

Coupons / Price Rules

Full CRUD for coupon/discount rule management + validation.

Create a coupon:

curl -X POST /api/rest/v2/coupons \
  -H 'Authorization: Bearer eyJ...' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "SUMMER25",
    "discountType": "percent",
    "discountAmount": 25,
    "description": "Summer sale 25% off",
    "isActive": true,
    "usageLimit": 500,
    "usagePerCustomer": 1,
    "fromDate": "2026-01-01",
    "toDate": "2026-03-31",
    "minimumSubtotal": 50
  }'

Discount types: | API Value | Maho Action | Description | |-----------|-------------|-------------| | percent | by_percent | Percentage off each item | | fixed | by_fixed | Fixed amount off each item | | cart_fixed | cart_fixed | Fixed amount off cart total | | buy_x_get_y | buy_x_get_y | Buy X get Y free |

Validate a coupon:

curl -X POST /api/rest/v2/coupons/validate \
  -H 'Authorization: Bearer eyJ...' \
  -H 'Content-Type: application/json' \
  -d '{"code": "SUMMER25"}'

Response:

{
  "id": 0,
  "code": "SUMMER25",
  "isValid": true,
  "validationMessage": "Coupon is valid",
  "discountType": "percent",
  "discountAmount": 25,
  "ruleName": "Summer sale 25% off"
}

Collection filters:

GET /api/rest/v2/coupons?code=SUMMER          # Filter by code (LIKE search)
GET /api/rest/v2/coupons?isActive=true        # Filter by active status
GET /api/rest/v2/coupons?page=2&itemsPerPage=50

GraphQL:

mutation {
  createCoupon(input: {
    code: "SUMMER25"
    discountType: "percent"
    discountAmount: 25
    isActive: true
  }) {
    id
    code
    ruleId
  }
}

mutation {
  validateCoupon(input: {code: "SUMMER25"}) {
    isValid
    validationMessage
    discountType
    discountAmount
  }
}

Gift Cards

Balance lookups and adjustments are exposed via GraphQL only (checkGiftcardBalance, adjustGiftcardBalance).

CMS Content

Blog

Media

Reviews

Revocation (EU)

Contract revocation declarations under EU Directive 2023/2673 (the "revocation button"). The API exposes the authenticated channel: a logged-in customer revokes one of their own orders, and admins list and process the declarations. The public, unauthenticated web form remains at /revocation and is not part of the API.

Submit body:

curl -X POST /api/rest/v2/customers/me/revocation-requests \
  -H 'Authorization: Bearer <customer_jwt>' \
  -H 'Content-Type: application/json' \
  -d '{"orderId": 1234, "reason": "I changed my mind"}'

Response fields: id, orderId, orderReference, reason, customerName, email, verified, storeId, receivedAt, processedStatus, processedAt, suppressedAt, suppressedReason. The internal-only fields adminNote, ip, and userAgent are returned only to admins.

Admin processing:

curl -X PUT /api/rest/v2/revocation-requests/1234 \
  -H 'Authorization: Bearer <admin_jwt>' \
  -H 'Content-Type: application/json' \
  -d '{"processedStatus": "accepted", "adminNote": "Refund issued"}'

GraphQL: myRevocationRequests (customer's own declarations), submitRevocation(orderId / orderReference, reason) mutation, plus the standard revocationRequest item / collection queries.

Newsletter

Guest subscription control: Guest (unauthenticated) subscribe is controlled by the Maho config flag newsletter/subscription/allow_guest_subscribe (System > Config > Newsletter > Subscription Options > Allow Guest Subscription). When disabled, only authenticated customers can subscribe. Recommended: set to No for API use to prevent abuse.

Confirmation emails: When newsletter/subscription/confirm is enabled, new subscriptions receive a confirmation email and remain inactive until confirmed (double opt-in).

Contact

GET /contact/config response example:

{
  "id": "contact",
  "enabled": true,
  "captchaProvider": "turnstile",
  "captchaSiteKey": "0x4AAA...",
  "honeypotField": "_h_a4b2c1d3"
}

captchaProvider is one of none, turnstile, recaptcha_v3 (or anything an installed third-party module registers). captchaSiteKey is null when the provider is none. Frontends use these two fields to load the matching widget client-side; for richer per-provider config the helper-based event flow described under CAPTCHA is used instead.

The honeypotField value is deterministic per install (derived from the encryption key) and opaque to the frontend, render it as a hidden input and don't expose its value, e.g. <input type="text" name="{honeypotField}" style="display:none" tabindex="-1" autocomplete="off" />. If a request body arrives with a non-empty value in that field, the API silently treats it as spam (returns success without sending the email). When honeypot is disabled in admin, honeypotField is null and the frontend can skip it.

Directory

Wishlist

URL Resolver