Skip to content

Store Credit GraphQL API

The Store Credit GraphQL API adds two queries and two mutations to the GraphQL schema, which is everything a headless storefront needs: read the balance, read the history, and apply or remove credit on a cart. All four require an authenticated customer.

The GraphQL API lives in the separate, optional Hyva_StoreCreditGraphQl module:

composer require hyva-themes/commerce-module-store-credit-graph-ql
bin/magento setup:upgrade

Reading the Balance

storeCreditBalance returns the logged-in customer's balance for the current website, ready to display.

query {
  storeCreditBalance {
    amount
    currency
    formatted
  }
}
Field Type Contents
amount Float The available balance in the website base currency.
currency String The base currency code of the balance.
formatted String The balance already formatted for display, so the client does not have to reimplement price formatting.

The query returns null when store credit is disabled for the website, which is the signal to hide your store credit UI entirely rather than render a zero balance.

Reading the History

storeCreditHistory returns the customer's ledger entries, newest first, with paging.

query {
  storeCreditHistory(pageSize: 20, currentPage: 1) {
    total_count
    items {
      created_at
      action
      amount
      balance_after
      reason
    }
  }
}

pageSize defaults to 20 and currentPage to 1. Entries that did not move the balance are excluded, so total_count reflects meaningful history rather than raw row count.

Field Type Contents
created_at String When the entry was written.
action String The event label, such as Spent, Refunded, or Credit Adjustment.
amount Float The signed change. Negative for spends and debits.
balance_after Float The balance immediately after this entry.
reason String The external reason only. Internal admin notes are never exposed.

History Respects the Config Switch

When Show Store Credit History in Customer Account is set to No for the website, this query returns { items: [], total_count: 0 } rather than an error. A headless storefront therefore honors the same merchant setting as the Hyvä storefront, but only if you treat an empty result as "hidden" rather than as "no history".

Applying and Removing Credit on a Cart

Both mutations take the masked cart ID and return the same result shape.

mutation {
  applyStoreCredit(cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjE") {
    applied
    message
  }
}

mutation {
  removeStoreCredit(cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjE") {
    applied
    message
  }
}
Field Type Contents
applied Boolean Whether store credit is applied to the cart after the mutation ran.
message String A human readable status message you can surface directly.

Applying credit sets the store credit fields on the cart. It does not debit the balance, so re-query the cart totals afterwards to show the customer the new grand total. The balance only moves when the order is placed.

Authentication and Errors

Every query and mutation is for logged-in customers only. A request without a customer token fails with a GraphQlAuthorizationException carrying "The current customer is not authorized." There is no guest store credit.

The mutations resolve the masked cart through Magento's standard cart lookup, so the usual cart errors apply: a cart that does not belong to the customer, or does not exist, fails the way any other cart mutation would. Omitting cart_id fails with "Required parameter \"cart_id\" is missing.", and store credit's own errors, such as an empty balance, come back as input errors with their message intact.