Assigning Merchants to Plans

A Plan decides which of your Connections a merchant's transactions are routed to, and which Routing Rules apply when that decision is made. A merchant holds exactly one plan at a time.

Assigning a plan is the last configuration step before a merchant can process routed transactions. If a transaction arrives for a merchant that has no plan, and the request does not name a connection explicitly, Preczn cannot resolve a route and returns:

Transaction routing could not be resolved. All transactions require either a specified processor or a routing plan assigned to the merchant.

📘

Naming a connection bypasses the plan

A transaction request that specifies a processor is routed to that connection directly, and no plan rules are evaluated. A plan is what Preczn uses when the request leaves the routing decision to us.

You may already have a plan

Adding a connection to your platform automatically creates a plan for it, named Default {connection} Plan and enabled straight away. That plan holds the one connection and routes 100% of volume to it.

So if a merchant only needs to reach a single connection, there is nothing to build — assign the default plan for that connection and you are done. You only need to create a plan when you want to split traffic across connections or apply Routing Rules.

Before you assign

A merchant can only be moved onto a plan when all three are true:

If a merchant is missing credentials for a connection in the plan, board or link that connection first — see Merchant Onboarding or Linking Existing Credentials.

Assign a single merchant

There are two ways to reach the Change Merchant Plan drawer, and both open the same drawer with the merchant already selected. Start from Merchant Vault in the left navigation.

From the Merchant Vault table, find the merchant's row and open the dropdown arrow beside the Edit button in the last column, then select Change Merchant Plan. This is the quicker route when you are working through a list.

From the merchant's detail view, select the merchant to open it, then select the link on the Plan field in the detail header. The link reads as the merchant's current plan name, or Assign Plan if the merchant does not have one yet.

Once the drawer is open:

1. Under DESTINATION PLAN, choose the plan. The dropdown shows each plan's connections so you can confirm the merchant is a fit.
2. Under WHEN TO MOVE, choose Move Now, or Schedule for Later to pick a future date and time — see Schedule a move for later.
3. Select Continue, review the summary, and confirm.

📘

A merchant with a move already pending

When a merchant has a scheduled move waiting to run, its detail header shows a Scheduled Move badge next to the Plan field. Cancel that move before assigning a new plan — see Review, edit, or cancel a scheduled move.

Move merchants in bulk

Use a bulk move when you are standing up a new plan, retiring an old one, or shifting a cohort of merchants between connections.

1. Open Merchant Vault in the left navigation to view your portfolio.
2. Select the merchants you want to move using the checkboxes in the left column, or the header checkbox to select every merchant in the current view. Filter or search first to narrow the list — see Labeling Merchants for filtering by cohort.
3. Select Bulk Actions above the table, then Move Merchant(s). The Change Merchant Plan drawer opens. (The Bulk Actions button stays disabled until at least one merchant is selected.)
4. Under DESTINATION PLAN, choose the plan.
5. Under WHEN TO MOVE, choose Move Now or Schedule for Later.
6. Select Continue. The CONFIRM MOVE step lists every merchant in the move alongside its current plan.
7. Confirm to run the move.

If some of the selected merchants cannot be moved, the drawer lists them by name with the reason under the heading The following Merchants can not be moved. Clear those merchants from the selection and continue with the rest, or resolve the underlying problem first.

Why a merchant is rejected from a move

Schedule a move for later

Both the single-merchant and bulk drawers offer Schedule for Later under WHEN TO MOVE. Scheduling is useful when a plan change should land outside of a merchant's business hours, or on a contracted date.

1. Select Schedule for Later.
2. Enter a Schedule Name. This is how the move is identified later, so name it for the change it makes rather than the date.
3. Set the Date and Time. Times are shown in your own time zone.
4. Select Continue, review the summary, and confirm.

A merchant can hold only one pending scheduled move at a time.

Review, edit, or cancel a scheduled move

Scheduled moves live under Routing → Routing Migrations in the left navigation.

Each entry shows its name, its scheduled date and time, and a status of SCHEDULED or COMPLETED.

• Select a SCHEDULED move to review its merchants and destination plan, change its date and time, or select Cancel Scheduled Move to drop it.
• Select a COMPLETED move to see the details of what ran.

Assign a plan over the API

Two endpoints cover the whole flow: Get Platform Plans to find the plan, and Update Merchant to assign it.

Find the plan

Authenticate with your private API key in the x-api-key header. The key decides the mode — see API Keys and Live vs Test Mode.

GET https://api.preczn.com/v1/plans

[
  {
    "hasTransactions": true,
    "modifiedOn": "2026-04-29T19:29:11Z",
    "createdBy": "user_4mpyyqeqep990v08kxwj3ehs4w",
    "isTestMode": false,
    "name": "Default Braintree Plan",
    "active": true,
    "description": "Default plan for Braintree",
    "modifiedBy": "user_4mpyyqeqep990v08kxwj3ehs4w",
    "id": "plan_23ys814y1398499p1y8sddd9ps",
    "connections": [
      {
        "id": "pfmCon_1c358p6gj699796n4rn7nqd8wk",
        "name": "Braintree US",
        "connection": "Braintree"
      }
    ],
    "createdOn": "2026-04-29T19:29:11Z"
  },
  {
    "hasTransactions": false,
    "modifiedOn": "2026-06-18T12:35:57Z",
    "createdBy": "user_4mpyyqeqep990v08kxwj3ehs4w",
    "isTestMode": false,
    "name": "Split Card Volume",
    "active": true,
    "description": "Braintree and Stripe, 50/50 by volume",
    "modifiedBy": "user_4mpyyqeqep990v08kxwj3ehs4w",
    "id": "plan_20y87a288b83k9080c0kj3xd60",
    "connections": [
      {
        "id": "pfmCon_1c358p6gj699796n4rn7nqd8wk",
        "name": "Braintree US",
        "connection": "Braintree"
      },
      {
        "id": "pfmCon_38j01nyrbc9exa4brh6yb06ze0",
        "name": "Stripe Primary",
        "connection": "Stripe"
      }
    ],
    "createdOn": "2026-06-18T12:35:57Z"
  }
]

📘

Inactive plans are returned too

A plan with active: false is a draft. It is listed here, but a merchant assigned to it cannot route a transaction, so filter on active before offering a plan as a destination.

Within connections, name is the label you gave the connection in the dashboard and connection is the underlying provider. Connections configured with a provider-assigned merchant account identifier also return processorMid.

connections[].id is a platform connection identifier, prefixed pfmCon_. This is the connection as your platform configured it — not the merchant's own record at that provider, which is a separate midCon_ identifier. A plan is built from platform connections, so these are the ids you will see here. Plan identifiers are prefixed plan_. Both take a _test_ segment in Test mode. See Object ID Prefixes.

Assign the plan

Send the plan's id as plan on the merchant.

PATCH https://api.preczn.com/v1/merchants/{merchantId}

{
  "plan": "plan_20y87a288b83k9080c0kj3xd60"
}

{
  "id": "mid_1fq9yd3g409vbbaqkq9t8xbr87",
  "name": "Northwind Supply",
  "legalName": "Northwind Supply LLC",
  "active": false,
  "plan": "plan_20y87a288b83k9080c0kj3xd60",
  "address": {
    "address": "1 Market Street",
    "address2": "Suite 400",
    "city": "San Francisco",
    "region": "CA",
    "postal": "94105",
    "country": "USA"
  }
}

The response is the full merchant record; the fields above are abbreviated to those relevant to the assignment.

Errors

{
  "statusCode": 400,
  "message": "Plan requires merchant to have active connections with the following: Braintree,Stripe",
  "error": "Bad Request"
}

📘

Check connection status first

Call Get Merchant before assigning to confirm the merchant's connections are active. It is a cheaper check than handling the 400 after the fact, and it tells you which connection to board next.

What happens next

Once a merchant holds an active plan and its connections are live, enable the merchant so it can process. From then on, every transaction that does not name a connection is routed by the plan's Routing Rules.