Skip to main content
Masivo coupons, loyalty, and customer profiles share one server connection per merchant and environment. You paste a Masivo SERVER API key in the dashboard under Settings → Integrations. Spark stores that key encrypted. Channel templates never receive it.

What the template does

Keep using the Storefront API customer endpoints: Do not add the Masivo SDK, a Masivo API key, or Masivo product screens to a template. Wallet, campaigns, and Masivo-native coupon or loyalty UIs are implemented in your own channel, outside the template. Redeems stay Fire spark payments. They are not a Masivo wallet screen.

When Spark forwards a profile

After a successful register, identify, or update, Spark forwards the profile only when the Masivo connection for that environment is active and the matching option is on:
  1. Sync registered customers covers a register, identify, or update of a customer who is not anonymous. It defaults to on when the preference is missing, and it stays off until you save it in the confirmation that appears right after you connect.
  2. Sync anonymous customers covers an anonymous register or update. It defaults to off.
Connecting does not start sending. Spark asks you to confirm first, with registered customers on, anonymous customers off, and anonymous order contacts off. Nothing is sent until you save. Choosing “Not now” leaves all three off until you turn one on in Settings → Integrations. Turning an option on does not backfill customers who already exist. The next matching register, identify, or update sends that profile. If the connection is not active, none of these options sends anything. A Masivo failure does not fail the Storefront write. Spark keeps the customer and records the sync error on the connection. Spark retries a temporary failure a few times. If those retries run out, or Masivo rejects the API key, the connection needs attention and Spark emails the account admins with the reason. A contact Masivo refuses as invalid or already stored does not pause the connection. Enter a valid API key again, or verify the stored key, to start sending. Disconnecting is separate: it removes the connection and also emails the admins.

When Spark sends a contact

Sync anonymous order contacts is off until you turn it on. When an anonymous order first becomes fulfilled, and the connection is active, Spark sends one contact to Masivo with the data that order already has. A later update of that fulfilled order does not send again. Registered customers’ orders never create a contact. Past fulfilled orders are not backfilled. If Masivo says the contact is invalid or already exists, Spark keeps the order and records the error. It does not update the contact and it does not pause sending. If Masivo rejects the API key, or a temporary failure keeps happening, the connection needs attention until you verify it or replace the key.

Capability flags

Coupons and Loyalty stay in Marketing. Turning a flag off hides that product’s call to action and leaves the connection in place, including disconnect. Get preferences returns the six flags and no secrets:
  • masivo.coupons_enabled
  • masivo.loyalty_enabled
  • masivo.sync_registered_customers_enabled
  • masivo.sync_anonymous_customers_enabled
  • masivo.sync_anonymous_order_contacts_enabled
  • masivo.validate_orders_enabled
Use them to know whether Spark will sync customers. They are not a Masivo client.

Validate orders with Masivo

Validate orders with Masivo is on until you turn it off under Settings → Integrations. When it is on, the environment has an active Masivo connection, and the order includes rewards, Validate order asks Masivo to preview those rewards before the order is placed. Connecting Masivo creates one FireSpark REDEMPTION payment for that environment and stores its id on masivo_connections.redemption_payment_id (20261110210000_masivo_redemption_payment.sql). The new payment is named Recompensas for es and pt merchants, and Rewards otherwise. Reconnecting reuses the linked payment, or an existing firespark REDEMPTION payment for that merchant and environment, and does not rename it. Spark calls PUT /api/storefront/v1/events/redeem/preview only for redeems of that payment. A PRODUCT reward is not a discount: the cart line keeps its price, the payable total does not drop, and Spark sends it on the order, not on the product. Shipping is only FEE lines whose metadata.fee_based_on is a delivery basis (DISTANCE_STRAIGHT, DISTANCE_STREET, or COVERAGE_ZONE_TAG). Every Masivo rejection comes back as MASIVO_REWARD_NOT_REDEEMABLE. The customer sees our localized copy. Masivo’s message stays in detail. If that payment is missing, deleted, or inactive, the order is rejected with MASIVO_REDEMPTION_PAYMENT_REQUIRED. If Masivo cannot be reached, Spark rejects the order with MASIVO_UNAVAILABLE and records a masivo.failed monitoring event. A bad API key pauses the connection. A timeout does not. The preview order uses the same value, payment method, and shipping as the purchase we send to Masivo.

Send behavior events

@fire-spark/analytics-masivo sends Masivo’s Emit event body from your channel with a publishable key. It is separate from the server connection: it uses no secret. See how each Fire Spark field maps to the body in Analytics destinations.