Onboarding a Brand Tenant: The Node Operator Guide

A node operator onboarding guide is the checklist a returns network partner uses to bring a new brand tenant live on shared infrastructure without breaking data isolation, SLAs, or grading accuracy for anyone else on the network. At areturnz, that process runs through a defined node spec, a phased go-live sequence, and a set of tenant-level configuration steps that get a brand from signed contract to first inbound parcel in about two to three weeks, not two to three months.

This guide is written for the operator sitting inside that process: the person configuring a new tenant, mapping SKUs, setting disposition rules, and watching the first batch of returns move through grading. If you manage a facility node or you are a partner reselling areturnz capacity under your own brand, this is the sequence you will actually run.

What a brand tenant actually needs on day one

Before any parcel arrives, a new tenant needs four things configured correctly: a SKU and catalog map, access credentials scoped to their data only, disposition rules that match their brand's risk tolerance, and a webhook endpoint that receives their events and nobody else's. Skipping any one of these creates rework later, usually discovered the hard way when the first evidence bundle goes to the wrong dashboard view.

SKU and catalog mapping

Every tenant's catalog gets mapped to the areturnz grading taxonomy before go-live. This is not just a barcode lookup. Apparel tenants need size and color variants tied to their own SKU logic; electronics tenants need serial number capture rules; beauty tenants need lot and expiration fields. Get this wrong and grading confidence scores drop because the AI model is comparing a return against the wrong reference data.

Access and credential scoping

Each tenant gets its own API keys and dashboard roles. Under a multi-tenant setup, isolation has to be airtight at the webhook and data layer, not just at the login screen. Our webhook isolation guide covers the technical pattern in more depth, but the operator-facing summary is simple: one tenant should never be able to see, query, or receive an event tied to another tenant's parcel.

The five-phase onboarding sequence

Most brand tenants move through five phases. The table below shows what happens in each, who owns it, and roughly how long it takes on a typical onboarding.

Facility NJ-01 in East Hanover, New Jersey runs this sequence for most East Coast tenants, and the same phases apply whether the brand is shipping a few hundred returns a month or scaling toward the volume tiers that make up most of our 180K+ processed returns to date.

Setting SLAs before the first parcel arrives

The single biggest onboarding mistake is agreeing to a cycle-time SLA without checking it against category mix. Our network median is about 48 hours from inbound scan to disposition, but a tenant with a heavy electronics mix that requires serial verification will run slower than a tenant returning mostly apparel. Set the SLA against the tenant's actual category blend, not the network average, or you will spend the first quarter explaining variance instead of fixing it.

Disposition rules matter here too. A tenant that wants aggressive auto-restock on B-grade apparel will hit a different cycle time than one that routes every B-grade item to manual review. Confirm these thresholds during phase two, not after the first week of live data comes in looking wrong.

Webhook isolation and the node spec

The node spec is the technical reference every operator should have open during phase three. It defines the event schema, the per-tenant authentication pattern, and the retry and dead-letter behavior for webhook delivery. Configuring a tenant's endpoint against this spec up front avoids the two most common go-live issues: duplicate event delivery and cross-tenant payload leakage.

Match accuracy between the AI grading model and operator overrides sits at about 99.6% across the network. That number matters during onboarding because it sets tenant expectations correctly: overrides will happen, they are logged, and they feed back into the confidence calibration model rather than getting treated as errors to hide. Every return, regardless of tenant, ships with the same evidence bundle format, so a brand's QA team can verify grading decisions from day one instead of taking them on faith.

Common onboarding failure points

Most failed or delayed onboardings trace back to one of three things: a catalog map that was rushed to hit a launch date, disposition rules copied from another tenant without adjusting for category mix, or a webhook endpoint that was never load-tested against real event volume. None of these are hard problems. They are just steps that get skipped when a go-live date is treated as more important than a clean dry run.

If you are still evaluating whether to bring a brand on as a resold tenant at all, our white-label reselling guide and the partner use cases page cover the commercial side of that decision. This guide assumes the deal is signed and focuses purely on the operational build-out.

Pricing and volume tiers

Tenant pricing is tied to volume commitment and category mix, and it should be confirmed before phase one starts, not negotiated mid-onboarding. Full tier detail lives on the pricing page; the node operator's job is to make sure the technical build matches whatever tier was actually sold.

Frequently asked questions

How long does it take to onboard a new brand tenant?

Most tenants go from signed contract to first live parcel in two to three weeks, following the five-phase sequence above. Complex catalogs (multi-category, serialized electronics) can push closer to four weeks.

What is the node spec and why does it matter during onboarding?

The node spec is the technical reference defining event schemas, authentication, and webhook behavior for every tenant on the network. Operators configure phase three against it directly, which is why it should be reviewed before any API keys are issued.

Does every tenant get the same 48 hour cycle-time SLA?

No. The 48 hour figure is a network median. Actual tenant SLAs should be set against that tenant's category mix, since electronics and items requiring manual verification take longer than straightforward apparel returns.

How is tenant data kept separate on shared infrastructure?

Each tenant gets scoped API keys, isolated webhook endpoints, and dashboard permissions that prevent cross-tenant visibility. See the webhook isolation guide for the full technical pattern.

What happens if the AI grading model and the operator disagree during onboarding?

Every override is logged and reviewed. Across the network, AI-versus-operator match accuracy runs about 99.6%, and disagreements during a new tenant's early weeks feed directly into that tenant's confidence calibration rather than being written off as noise.

For the broader set of decisions around running a resold returns program, browse the rest of our partner playbook articles. To get a new brand tenant scoped and scheduled, contact the areturnz team.

Related reading: SLA design for white-label returns partners

Related reading: Per-tenant reporting: giving partners visibility without breaking isolation