Glossary
Terms used across the commerce domain that are either non-obvious, have names that conflict with their meaning, or are used inconsistently across the codebase.
users_plans (table)
The order line items table. The name is a legacy artifact from when the platform modeled one plan per user directly. Today it represents a line item inside an Order: the binding between a user, a plan or product, and the billing terms. A single order can have multiple rows in this table.
UserPlan
The Eloquent model for a row in users_plans. In conversation and code, "UserPlan" and "order line item" are used interchangeably.
Order The root purchase entity. One order per cart checkout. An order always has at least one UserPlan.
Payment
An immutable financial event row in the payments table. Not to be confused with "the act of paying": a payment row can have status = 'pending', status = 'refunded', and so on. See Payment Ledger Model.
Shipping payment
A row in payments with user_plan_id = null and plan_type = 'shipping'. Represents the carrier cost for a physical order. It is not backed by any plan. See Shipping Payment.
plan_type = 'shipping'
A synthetic value assigned by the checkout process to carrier-cost payment rows. It does not correspond to any value in the Plan model's type column.
Recurring cycle (recurring_cycle)
A 1-based integer on a payment row counting how many times a subscription has been billed. Cycle 1 is the first charge, cycle 2 is the second, and so on. For shipping payments, the cycle is copied from the companion product payment.
Sandbox
An order or payment created in a test environment. Set once at order creation from the gateway's environment configuration and never changed. Live and sandbox records coexist in the same tables; always filter by sandbox = false in production reports.
Gateway type
The value in gateway_type on an Order, UserPlan, or Payment. Can be a real payment gateway (stripe, mercadopago, yuno, payu) or a non-payment source (manual, bulk, external, lti, saml, totalDiscountCoupon). manual, bulk, lti, and saml never create payment rows. external always creates one via PaymentSync. totalDiscountCoupon creates a nominal $1.00 USD marker row (regardless of the original price) only when the tenant has charge_total_discount_coupon enabled; otherwise no row is created. Distinct from gateway_id, which is the foreign key to the gateways table row. Historical records may also carry paypal; see Deprecated gateways.
gateway_id
Foreign key on payments (and other models) pointing to the specific gateways table row used. Different from gateway_type (a string identifier). Two tenants using Stripe will share gateway_type = 'stripe' but have different gateway_id values.
Yuno A payment orchestrator integrated as a gateway. Despite being an orchestrator (a layer above gateways), it is treated as a single gateway in Farfalla's model. The subscription flow creates the order inside the recurring payment service after the user completes the Yuno checkout step; the one-off (OTT) flow creates the order before payment, like every other gateway. See Yuno Checkout Flow.
PayU A legacy gateway. Supported for existing one-off orders only. No new tenants are onboarded. No refund path. Not supported in the reader or gift flows.
PayPal
Deprecated gateway. Excluded from the active gateway set. Historical records exist in the database, but no new orders are routed to PayPal. An ongoing background process (CancelPaypalRecurringSubscriptions) is cancelling existing PayPal recurring subscriptions. See Deprecated gateways.
PlanGatewayMeta
A record linking a plan to a gateway, storing plan-level prices and gateway-specific remote plan identifiers (Stripe plan id, MercadoPago preapproval plan id). Reused across purchases of the same plan to avoid creating duplicate remote plans at the gateway. Not used for gateway routing. Routing reads each gateway's supported_currencies and order columns; see Gateway Routing.
sale_type
A field on payments that categorizes the financial event: retail, subscription, external, or shipping. Derived from plan_type at payment creation. The mapping:
plan_type = 'single'→sale_type = 'retail'plan_type = 'retail'→sale_type = 'retail'plan_type = 'prepaid'→sale_type = 'subscription'plan_type = 'recurring'→sale_type = 'subscription'plan_type = 'external'→sale_type = 'external'plan_type = 'shipping'→sale_type = 'shipping'
There is no sale_type = 'prepaid'. If you are looking for prepaid plan payments, query sale_type = 'subscription' and filter further on plan_type if needed.
gateway_key
The gateway's identifier for the operation associated with an order or payment. For recurring plans, it is the subscription or preapproval id (set on the first successful cycle). For one-off payments (MercadoPago, Yuno) it is the gateway payment id. Used to query the gateway for status updates. Null until the user completes the payment flow and returns.
external_reference
The order's uuid field sent to MercadoPago at preapproval creation time. Used as a fallback when an inbound IPN cannot find its order by gateway_key (which happens when the user does not return to the store after paying). See Subscriptions Flow with MercadoPago.
gateway_status
The raw status string returned by the gateway on a payments row, captured before being mapped to the platform's status taxonomy (pending, approved, refunded, etc.). Useful when debugging unexpected status mappings.
payment_payload
JSON column on payments that holds gateway event metadata. Refund rows store the source payment id here under the original_payment_id key, the refund reason, and the email/id of the user who issued the refund. There is no original_payment_id column on the table itself.
is_configured
A derived flag on a gateway row indicating whether the gateway has the minimum settings needed to operate (per-type rules: Yuno additionally requires the yuno_checkout_enabled feature flag). Used as a routing filter so unconfigured rows are not offered at checkout.