GraphQL v26.7+
Maho exposes the same resources over GraphQL as over REST, via API Platform's built-in GraphQL support. Every resource's fields, arguments, and types are introspectable from the schema.
Endpoint: POST /api/graphql Admin GraphQL: POST /api/admin/graphql (requires a fully-authenticated admin session)
Both are opt-in: enable the graphql / admin_graphql protocols under System → Configuration → Services → API → API Protocols. Authentication is the same JWT bearer token as REST (see Authentication); send it in the Authorization header.
# Query: fetch a product by its node IRI
query {
product(id: "/api/rest/v2/products/123") {
id
sku
name
price
}
}
# Mutation: update stock for a SKU
mutation {
updateStock(input: {sku: "ABC-123", qty: 50}) {
sku
qty
previousQty
success
}
}
Field naming
API Platform derives every custom GraphQL field name as lcfirst(operationName + ResourceShortName) - the resource noun is always appended. Only the reserved item/collection queries escape this and yield the clean singular/plural (product / products, order / orders). So a custom operation named setPaymentMethodOn on the Cart resource becomes the field setPaymentMethodOnCart; operations are named with a natural qualifier (a verb, or on / to / from / my / guest / current) so the appended noun reads well rather than stuttering (setPaymentMethodCart).
Two consequences worth knowing:
- The signed-in customer is
currentCustomer(notme), a guest cart/order isguestCart/guestOrder, and a caller's own collections aremyAddresses/myReviews/myWishlistItems/myRevocationRequests. - Natural-key lookups are collection filter arguments, not separate
by<X>queries. Filter the collection to fetch by a key:products(sku:),products(barcode:),categories(urlKey:),productAttributes(code:),cmsPages(identifier:),cmsBlocks(identifier:)- each returns the 0-or-1 match.
Reference
Item queries take a node IRI (id: "/api/rest/v2/products/123"); collection queries are plural and accept pagination plus any listed filter arguments. Admin-only queries/mutations require an admin or service token with the relevant permission (see Authentication).
Catalog
| Resource | Queries | Mutations |
|---|---|---|
| Product | product(id:), products - filters sku:, barcode:, search: | - (writes are REST-only) |
| Category | category(id:), categories - filter urlKey:, categoryProducts(id:) | - |
| Product attribute | productAttribute(id:), productAttributes - filter code: | - |
| Attribute set | attributeSet(id:), attributeSets | - |
| Layered filter | layeredFilter(id:), layeredFilters | - |
| Review | review(id:), reviews, productReviews(productId:), myReviews | submitReview |
Cart & checkout
| Resource | Queries | Mutations |
|---|---|---|
| Cart | cart(id:), carts, customerCart, guestCart(maskedId:) | createCart, addToCart, updateItemQtyInCart, removeItemFromCart, applyCouponToCart, removeCouponFromCart, setShippingAddressOnCart, setBillingAddressOnCart, setShippingMethodOnCart, setPaymentMethodOnCart, assignCustomerToCart, applyGiftcardToCart, removeGiftcardFromCart, setGiftMessageOnCart, removeGiftMessageFromCart |
Gift messages have no separate resource - they are the setGiftMessageOnCart / removeGiftMessageFromCart mutations above.
setShippingAddressOnCart and setBillingAddressOnCart take prefix, middleName, suffix and vatId next to the other fields of the address. They also take saveInAddressBook v27.1+: on a customer cart, true adds the address to the address book of the customer when the order is placed. Without it, or with false, the address does not go to the address book. A guest cart ignores it.
Customers
| Resource | Queries | Mutations |
|---|---|---|
| Customer | currentCustomer, customer(id:) (admin), customers (admin) | loginCustomer, logoutCustomer, updateCustomer, changePasswordCustomer, forgotPasswordCustomer, resetPasswordCustomer |
| Address | address(id:), addresses, myAddresses | createAddress, updateAddress, deleteAddress |
| Customer group | customerGroup(id:), customerGroups (admin) | - |
Sales
| Resource | Queries | Mutations |
|---|---|---|
| Order | order(id:), orders (admin), guestOrder(incrementId:, accessToken:), customerOrders | placeOrder, cancelOrder, holdOrder, unholdOrder, addCommentOrder |
| Shipment | shipment(id:), shipments, orderShipments(orderId:) | createShipment, addTrackShipment, removeTrackShipment |
| Credit memo | creditMemo(id:), creditMemos, orderCreditMemos(orderId:) | createCreditMemo |
| Revocation request | revocationRequest(id:), revocationRequests (admin), myRevocationRequests | submitRevocationRequest |
placeOrder applies the rules of the place-order endpoints (see Orders). It takes agreementIds, the terms and conditions that the customer accepted, and sendConfirmation for an admin or an API token with the grant to create orders. The placeOrder mutation of the admin GraphQL endpoint takes sendConfirmation too.
Inventory & promotions
| Resource | Queries | Mutations |
|---|---|---|
| Stock | stock(id:), stocks (admin) | updateStock, bulkUpdateStock |
| Coupon | coupon(id:), coupons (admin) | createCoupon, updateCoupon, deleteCoupon, validateCoupon |
| Gift card | giftCard(id:) (admin), giftCards (admin), checkBalanceGiftCard(code:) (public) | createGiftCard, adjustBalanceGiftCard, sendEmailGiftCard |
checkBalanceGiftCard(code:) is the public balance check (returns balance + status with the code masked, no recipient/sender PII).
createGiftCard sends no email v27.1+. sendEmailGiftCard(input: {giftCardId:}) sends it, as the Send Email button of the admin and POST /giftcards/{id}/send-email do. A card without recipientEmail gives an error on recipientEmail.
v26.9+ breaking change
createGiftCard takes websiteIds: [Int!] in place of the removed scalar websiteId argument, and gift card types expose websiteIds rather than websiteId. A client still sending websiteId fails input validation. Unlike REST create, the mutation accepts no legacy alias. Omitting websiteIds defaults to the current website.
Content
| Resource | Queries | Mutations |
|---|---|---|
| CMS page | cmsPage(id:), cmsPages - filter identifier: | - (writes are REST-only) |
| CMS block | cmsBlock(id:), cmsBlocks - filter identifier: | - |
| Blog post | blogPost(id:), blogPosts | - |
| Blog category | blogCategory(id:), blogCategories | - |
Marketing
| Resource | Queries | Mutations |
|---|---|---|
| Newsletter | newsletter(id:) (admin), newsletters (admin), statusNewsletter | subscribeNewsletter, unsubscribeNewsletter |
| Wishlist item | wishlistItem(id:) (admin), wishlistItems (admin), myWishlistItems | addWishlistItem, removeWishlistItem, moveToCartWishlistItem, syncWishlistItem, shareWishlistItem |
| Product alert | productAlert(id:), productAlerts, myProductAlerts | subscribeProductAlert, unsubscribeProductAlert |
Store, directory & tax
| Resource | Queries | Mutations |
|---|---|---|
| Store config | currentStoreConfig, storeConfig(id:), storeConfigs | - |
| Country | country(id:), countries | - |
| Tax class / rate / rule (admin) | taxClass / taxClasses, taxRate / taxRates, taxRule / taxRules | - (writes are REST-only) |
| URL resolver | resolveUrlResolveResult(path:) | - |
resolveUrlResolveResult resolves a storefront path to its target entity. The doubled noun is unavoidable under the naming rule - naming it resolveUrl would force a Url type and a nonsense url / urls list query - so it's kept as-is.