Treat Salla customer groups as checkout policy

Customer groups are usually introduced as a marketing segmentation feature: VIP, wholesale, inactive or high-value customers. In a Salla integration, however, a group can be more consequential than a label. The documented group payload can combine membership conditions with allowed payment and shipping features, and Salla special offers can target customer-group IDs. That makes a group a checkout policy boundary.

This is powerful, but it also changes the failure mode. A mistaken spreadsheet import no longer affects only a campaign audience; it can expose cash on delivery to the wrong cohort, hide a payment method from legitimate buyers, or attach an offer to an unintended group. The safe design is therefore not “call the group endpoint from a cron job.” It is a small control plane with desired state, validation, staged rollout, audit and rollback.

This explainer uses Salla's official developer documentation as verified on 30 September 2026. It is not announcing a new Salla feature. The examples and thresholds are explicitly hypothetical, and no performance result or merchant outcome is attributed to Noor.

Start with the documented contract

Salla's Create Customer Group endpoint accepts a group name, an array of conditions and a features object. The documented condition types are total sales, total orders, store rating and customers without orders; supported comparison symbols include greater than, less than and between. The example features select payment-method slugs and shipping options. Creating or changing groups requires the customers.read_write scope.

Do not hard-code a payment-method catalog from a documentation example. The Available Payment Methods endpoint returns the methods available to the store and uses the payments.read scope. The endpoint also documents a status filter. Resolve desired slugs against this live catalog before publishing a group policy, because a method that exists in a generic example may not be active or appropriate for a particular store.

The default-group endpoint has a narrower contract: Salla documents that every new customer belongs to the default group and that this endpoint changes only payment and shipping features. Treat the default as the safest baseline, not as a convenient place to experiment. A bad default reaches people before your segmentation logic has observed enough history to classify them.

Separate desired policy from platform state

Store a versioned policy document in your own system. A hypothetical example might name a trusted-repeat-buyers group, define membership as more than three completed orders, allow card and Mada payments, and keep shipping set to all. The document should contain human-readable intent, the exact Salla condition payload, desired features, an owner, an approval reference and effective dates.

Then read Salla's current group state and compute a diff. The deployer should create or update only when the desired and observed states differ. This makes retries safe and produces a reviewable change set: “remove COD from group 812; keep Mada and Apple Pay; membership condition unchanged.” A blind full rewrite makes it harder to distinguish an intentional change from drift or an incomplete previous run.

Keep stable internal policy IDs separate from Salla group IDs. Names are for people and may change; numeric platform IDs are integration references. Persist the mapping per store, never assume IDs are portable between stores, and record which policy version produced the current remote state.

Validate before any write

Validation should happen in three layers. Schema validation checks that the condition type, symbol and value shape match the documented contract. Reference validation confirms that every payment slug exists in the store's available-method response and that every shipping reference is resolvable. Business validation enforces local safety rules: the default group cannot lose all mainstream payment paths, a wholesale group cannot receive a retail-only offer, and a high-risk method cannot be enabled without the required approval.

Reject ambiguous combinations instead of asking the API to interpret them. For a between condition, require explicit minimum and maximum values and ensure the minimum is not greater than the maximum. Normalize money units and time zones in your policy authoring layer. Salla's group examples explain the API shape, but your integration still owns domain rules such as what counts as a completed order or which internal event authorizes a customer's manual promotion.

Use least-privilege credentials. A read-only audit worker can use customers.read and payments.read, while the publisher alone needs customers.read_write. Special-offer automation needs its own specialoffers scopes. Separating readers from writers reduces the damage of a leaked job credential and makes audit logs easier to interpret.

Resolve membership from the customer, not an order snapshot

Salla's Customer Details response includes the customer's group IDs. The Merchant API changelog says the groups array under the customer object in List Orders was deprecated effective 18 February 2026 and directs developers to Customer Details instead. That is an architectural signal: do not build current authorization or eligibility decisions from a denormalized group snapshot on an order-list record.

For online decisions, fetch customer details with a short, bounded cache keyed by store and customer ID. Invalidate or refresh after your integration changes membership. For offline analytics, store the group IDs that were observed at decision time together with the policy version, but label them as historical evidence rather than current truth.

Avoid a Customer Details call for every item in a large order export. Deduplicate customer IDs, respect the endpoint's documented rate limit, cache successful reads, and separate “unknown because lookup failed” from “customer has no matching group.” Failing open can grant an unintended payment or offer; failing closed can block legitimate checkout. Choose the failure policy explicitly for each capability.

Roll out policy like code

Do not change the default group first. Create or choose a low-risk canary group, add a small set of test customers through the documented group workflow, and verify the storefront from their perspective. Check visible payment methods, shipping choices, offer eligibility, tax and totals, mobile and desktop checkout, and both Arabic and English paths.

Promote in stages: internal accounts, a small eligible cohort, then the intended audience. Between stages, compare the desired policy with Salla's observed group state and sample Customer Details responses. Freeze promotion when validation errors, unexpected drift or checkout regressions cross a predeclared threshold.

Rollback should restore the previous complete policy version, not issue an improvised inverse patch. Keep the prior conditions, features, group membership actions and linked offer configuration. The fastest safe rollback may be disabling the dependent offer or restoring broad payment availability before repairing segmentation; decide that ordering in the runbook.

Connect offers without coupling everything

Salla's Create Special Offer documentation includes customer_groups in the request examples. That enables targeted offers, but it also creates a dependency graph: policy version → group ID → offer ID. Record this graph so a group cannot be deleted or repurposed while an active offer still references it.

Keep qualification and benefit separate. The group answers “who is eligible?” The offer answers “what benefit is active, for which products, countries, channels and dates?” Combining both into one opaque automation makes it difficult to pause a promotion while preserving the segment for payment or shipping rules.

Use dry-run output that lists affected groups and offers before any write. For a scheduled promotion, preflight the referenced group membership and checkout capabilities before the start time, then verify again after activation. A valid API response proves that a write was accepted; it does not prove that the whole buyer journey is correct.

Observe outcomes, not only API success

Measure policy deployment separately from customer outcomes. Operational metrics include validation failures, API error rate, policy drift, time to converge and rollback duration. Product metrics include checkout-start to purchase conversion, payment-method selection, payment failure, shipping-option abandonment, support contacts and offer redemption by policy version.

Segment metrics by group and policy version, but avoid high-cardinality labels such as customer ID. Watch guardrails alongside conversion: COD exposure, refund or cancellation rate, delivery exceptions and discount cost may reveal a policy that increases orders but harms unit economics.

Correlation is not causation. A VIP group will differ from the default group before a new policy ships. If the decision requires causal evidence, use a properly designed experiment within an eligible population and keep safety constraints outside randomization. Do not compare raw group averages and call the difference an effect.

A practical deployment contract

Before publishing a group policy, require: a versioned desired-state document; current remote-state read; payment and shipping reference validation; explicit default-group safeguards; a diff preview; scoped credentials; canary accounts; storefront verification; promotion thresholds; drift monitoring; and a tested rollback version.

The useful mental model is simple. Salla holds the operational group, payment, shipping and offer configuration. Your integration owns intent, validation, sequencing and evidence. When groups control checkout capabilities, manage them with the same discipline as feature flags or access policy: small changes, visible diffs, staged exposure and reversible decisions.

Prepared by: Noor Yasser