Skip to main content

VelaFront / headless

The module ships full GraphQL parity. If you're running a headless storefront — Byte8's VelaFront, an in-house Next.js / Hydrogen build, or any other Magento headless framework — you don't need the Luma front-end at all.

The schema lives in etc/schema.graphqls. Resolvers under Model/Resolver/. Queries, mutations, and ProductInterface extensions are documented on the GraphQL page — this page is a higher-level integration walkthrough.

What the storefront needs to do​

Three integration points:

  1. PDP — query the pre-order eligibility for the product (or variant) and render the info block.
  2. Cart / checkout — display the deposit / balance split using the existing cart-totals breakdown.
  3. Customer account — render "My pre-orders" using the customerPreorders query and wire up the cancel / pay-balance mutations.

PDP integration​

The ProductInterface is extended with four fields:

  • preorder_enabled: Boolean
  • preorder_eligible: Boolean — accounts for stock state and config
  • preorder_available_from: String — ISO date
  • preorder_message: String — placeholder-substituted

For per-variant lookups on configurable products, use the byte8PreorderEligibility(sku: String!) query — it returns the resolved deposit, message, and availability for a specific child SKU.

query GetPreorderEligibility($sku: String!) {
  byte8PreorderEligibility(sku: $sku) {
    eligible
    deposit_amount
    deposit_type      # PERCENT | FIXED | FULL
    balance_due
    available_from
    message
  }
}

Cart / checkout​

The pre-order fee is wired into Magento's standard cart totals — the existing cart.prices query returns it as part of the totals breakdown alongside subtotal, tax, and shipping. No custom query needed.

Customer account​

query MyPreorders {
  customer {
    preorders {
      items {
        increment_id
        status
        deposit_paid
        balance_due
        available_from
        product { name url_key sku }
        actions {
          can_cancel
          can_pay_balance
          pay_balance_url   # signed link into the completion checkout
        }
      }
    }
  }
}

mutation CompletePreorder($id: Int!) {
  byte8CompletePreorder(preorder_id: $id) {
    success
    order_increment_id
  }
}

VelaFront specifics​

If you're on Byte8's VelaFront theme, the pre-order React components are bundled — no integration code needed beyond enabling the module on the Magento side and pointing VelaFront at your GraphQL endpoint.

The components:

  • PreorderInfo — PDP info block React component
  • PreorderBadge — category / search list badge
  • MyPreordersList — customer account page

All use shadcn/ui + Tailwind, matching VelaFront's visual language. They read the GraphQL schema described above.

Hydrogen / Next.js​

For non-VelaFront stacks, write the components yourself against the schema. The shape is intentionally narrow — three queries and two mutations cover the whole flow. A reference Next.js implementation is on the roadmap.

Authentication​

Everything customer-scoped (customer.preorders, byte8CompletePreorder) requires the standard Magento customer Bearer token in the Authorization header. The eligibility query is unauthenticated — anyone can ask "is this SKU pre-orderable" without a token.