These are two separate things, and a company can have either or both.
| Shared account | Merchant account | |
|---|---|---|
| Is | Several people ordering as one company | A credit line: charges build a balance, and invoices collect it |
| Record | The company's own customer record, plus a customer_association per person | One merchant_customer per customer |
| People | Managers and buyers, who sign in to the site | Authorized users (kept on the record) |
| Money | Orders carry the account's prices and are billed to it | Spending limit, payment terms (net days), invoices, payments |
| API | crm/shared-accounts (src/crm/shared-accounts.service.ts) | crm/merchant-customers (src/crm/merchant-customer.service.ts) |
| Screen | CRM › Customers & Benefits › Shared Accounts (/customers-benefits?view=shared-accounts) | CRM › Merchant Accounts (/merchant-customers) |
Ask first
- Which company? Its name and email. Is it already a customer? Search for it before making one.
- Shared account: who orders for it, and who manages it. Managers invite and remove people and see all of its orders; buyers only order. For each person: name and email. Is there a note for the invitation email?
- Prices: should buying on the account give group prices? If so, which customer group?
- Merchant account:
- the legal company name and the trade name;
- the billing address;
- the spending limit;
- the payment terms (net days) and the billing day of the month;
- whether invoices go out automatically when the limit is reached.
Part 1: a shared account
1. CRM › Customers: the company customer
The account is a customer record: the company itself. Find it with repo_find on customer (data.email, data.name). If there is none, make it as a contact (accountType: "contact": no sign-in, nothing sent), as in Add customers to a group.
For group prices, put the group on this record's groups (repo_update, dot-path data.groups). Price lists and product tiers read only the account record's own groups. Benefits also apply groups the account falls into by rule. See Price lists and customer group pricing.
Hands on: the account's sk.
2. CRM › Customers & Benefits › Shared Accounts: add the people
Stop: adding a member emails them. Show the person each email and role, and the note. Add only after a clear yes.
call_appengine POST /crm/shared-accounts/<account sk>/members, header x-client-host: <site domain> (used for the links in the email):
{ "email": "[email protected]", "firstName": "Pat", "lastName": "Lee", "role": "manager", "message": "Order supplies here from now on." }| The email is | What happens |
|---|---|
| Already a customer | Linked at once (added: true). They are emailed " |
| Not a customer yet | An invitation (customer_invitation, valid 14 days) is emailed: "invited you to order on /account/shared-accounts?invite=<token> (tested). They sign up or sign in, then accept. |
| Not an email | 400 "A valid email is required" (tested). |
role is manager or buyer (anything else is a buyer). A member must be someone who signs in to the site. Adding a contact links a record that can't order.
On screen: Start a shared account (Which customer is the account?, then Add someone to this account). An account that is already open has Add someone in its drawer.
Hands on: each association's sk, and each invitation's sk.
Check: GET /crm/shared-accounts/<account sk> returns:
members, each withroleandstatus;invitationsthat are pending;memberGroups,accountBenefitsandmanagerCount.
In the list (GET /crm/shared-accounts?search=), needsManager: true means it has members but no manager (tested).
3. Shared Accounts: change, suspend, remove
| To | Call |
|---|---|
| Make a buyer a manager, or the reverse | PUT /crm/shared-accounts/<account sk>/members/<assoc sk> { "role": "manager" } |
| Suspend, or restore | Same, { "status": "suspended" } / { "status": "active" } |
| Remove | DELETE /crm/shared-accounts/<account sk>/members/<assoc sk> |
| Cancel an invitation | POST /crm/shared-accounts/<account sk>/invites/<invitation sk>/cancel (tested) |
A suspended member keeps the link, so their past orders still show why they were on the account. The account drops off their list at their next sign-in (tested). Staff may leave an account with no manager. In the customer's own portal, the last manager can't step down.
Check: GET /crm/shared-accounts/<account sk>.
How members use it
Members see the account in the site's My account › Shared Accounts. Order for this switches the cart to the account, and Myself switches back. Managers invite people, change roles and see the account's orders there. See The customer account portal.
- Switching re-issues the member's sign-in with the account on it (
POST /profile/customer/shared-account { accountId }; an empty body switches back). Someone who isn't a member gets 403 "You are not associated with this account" (tested). - What switches. Orders placed while switched carry
sharedAccountIdandsharedAccountRole, and use the account's prices. Each account has its own cart. - Leads. A lead can carry
sharedAccountId. Its company is then filled from the account, and converting it makes the person a buyer on the account without an email. - Activity.
GET /crm/shared-accounts/<account sk>/orderslists the account's orders with who placed each one.…/activitygives the totals (tested).
Part 2: a merchant account
4. CRM › Merchant Accounts: open the account
call_appengine POST /crm/merchant-customers/detail:
{ "customer": "<customer sk>", "companyName": "Acme Supply LLC", "tradeName": "Acme",
"accountType": "standard", "billingAddress": { "line1": "…", "city": "…", "state": "TX", "zip": "…" },
"credit": { "spendingLimit": 2500, "paymentTermsDays": 30, "billingCycleDay": 1 }, "notes": "…" }It starts pending, with autoInvoice: true and invoiceTrigger: "either". A customer has one merchant account: a second gets 409 MERCHANT_EXISTS (tested). accountType is standard, premium or enterprise. Leaving out spendingLimit gives 5,000, and so does 0 (see What it can't do yet).
On screen: New Merchant.
Hands on: the merchant account's sk.
Check: GET /crm/merchant-customers/detail/<sk>, or GET …/by-customer/<customer sk>.
5. Merchant Accounts: approve, then set the terms
A pending account can't be charged (400 ACCOUNT_NOT_ACTIVE, tested).
Stop: approving emails the customer (merchant-account-approved, tested). So do suspend (-suspended) and reactivate (-reactivated). Confirm the company and the limit first.
| To | Call |
|---|---|
| Approve | POST /crm/merchant-customers/approve/<sk> { "notes": "…" } |
| Change the limit | PUT …/spending-limit/<sk> { "limit": 5000, "notes": "…" } |
| Change the terms | PUT …/payment-terms/<sk> { "paymentTermsDays": 45, "billingCycleDay": 15, "autoInvoice": true, "invoiceTrigger": "limit_reached" } (limit_reached, period_end, either, manual) |
| Suspend | POST …/suspend/<sk> { "reason": "…" }. A pending account can't be suspended (400 ACCOUNT_PENDING, tested). |
| Reactivate | POST …/reactivate/<sk> |
| Close | POST …/close/<sk> { "reason": "…" }. Refused while it owes anything (400 OUTSTANDING_BALANCE, tested). |
| Add an authorized user | POST …/users/<sk> { "customer": "<customer sk>", "role": "user", "canApproveTransactions": false, "spendingLimit": 500 } (admin, manager, user); PUT/DELETE …/users/<sk>/<customer sk> |
On screen: open the merchant, then Approve, Suspend, Reactivate or Close Account. The Settings tab sets the limit, net days, billing day and notes; Users › Add User. invoiceTrigger and autoInvoice are API-only.
Check: GET …/stats/<sk> gives currentBalance, availableCredit and the period totals.
6. Merchant Accounts: charges and credits
What charges the account today:
- delivery orders placed with
paymentMethod: "merchant_account"(POST /client/logistics/orders), for the account's own customer; - a charge you post yourself.
The store checkout doesn't charge a merchant account.
Stop: a charge adds to what the company owes, and a credit takes it off. Confirm the amount and the description.
- Charge:
POST /crm/merchant-customers/charge/<sk>{ "id": "<your reference id>", "type": "service", "amount": 120, "description": "…", "lineItems": [] }. The account must be approved, and the amount must fit in the available credit. Otherwise 400INSUFFICIENT_CREDIT, with the available amount (tested). - Credit:
POST …/credit/<sk>{ "amount": 30, "reason": "…" }.
Charge and credit are API-only. The Transactions tab lists them (GET …/transactions/<sk>).
7. Merchant Accounts: invoice, collect, remind
| Step | Call | Sends |
|---|---|---|
| Generate | POST …/invoices/generate/<sk>. It makes a draft from the current period's charges and starts a new period. | Nothing |
| Send | POST …/invoices/send/<sk>/<invoiceId> | Stop. merchant-invoice-sent to the customer |
| Record a payment | POST …/invoices/payment/<sk>/<invoiceId> { "amount": 150, "method": "check", "transactionId": "…", "notes": "…" } | Stop. merchant-payment-received |
| Mark overdue | POST …/invoices/mark-overdue/<sk>/<invoiceId> | Stop. merchant-invoice-overdue |
| Remind | POST …/reminders/<sk>/<invoiceId>; POST …/reminders/bulk for every overdue one | Stop. merchant-payment-reminder |
| Statement | GET …/statements/<sk>?startDate=&endDate=; POST …/statements/<sk>/send | Stop before sending: merchant-account-statement |
| All merchants | POST …/invoices/generate-all, then POST …/invoices/send-all | Stop. Sends every draft |
When autoInvoice is on and the trigger is limit_reached or either, a charge that brings the balance to the limit is meant to generate and send the invoice by itself. See What it can't do yet.
Record a payment only for the full invoice amount. Any amount marks the invoice paid (see What it can't do yet).
On screen: the merchant's Invoices tab has Generate Invoice, Send Invoice, Record Payment, Mark Overdue and Send Reminder. The list has Generate All Invoices, Send All Drafts and Send Overdue Reminders.
Check:
GET …/dashboardfor the totals;GET …/balances/outstandingfor who owes what;GET …/reports/agingfor what is owed by age;GET …/invoices/all?status=across merchants.
Merchant invoices live on the merchant account (data.invoices). They are not Books invoices, and they don't show in the customer's portal Invoices.
When it's done
Tell the person:
- Shared account: the account, each member and role, and who was invited and still has to accept. Also which group prices buying on it gives.
- Merchant account: its status, limit, terms and available credit, and any invoice sent, paid or overdue.
Open Shared Accounts on the account, or Merchant Accounts on the merchant.
What it can't do yet
- Two lists of groups. The Shared Accounts drawer shows every group the account is in, including rule-based ones, as what buying on it gives. Price lists and tiers use only the groups saved on the account record. Benefits use both.
- No deep link to one shared account. Open the list and search.
- Merchant accounts aren't charged by store checkout. Only delivery orders and posted charges add to the balance. Authorized users are kept on the account, and nothing charges for them yet.
- A spending limit of 0 becomes 5,000 when the account is opened. Set the limit after opening it (
spending-limit). - Partial payments close the invoice. Recording any amount marks the invoice
paid, with nothing outstanding on it, while the balance keeps the rest. The aging report then misses the rest (tested). - A credit doesn't lower the next invoice. A credit lowers the balance, but the next invoice is still for the period's full charges (tested: charges of 150 and a credit of 30 gave an invoice for 150, while its lines added up to 120).
- Statements over-count payments when an invoice has several charges: one payment is counted once per charge (tested).
- Auto-invoice at the limit didn't fire in testing. Reaching the limit produced no invoice or email. Generate and send invoices yourself.
- Before the first invoice, sending, paying or marking overdue an invoice id fails with a server error instead of "Invoice not found".
Don'ts
- Don't add members, send invitations, approve, send invoices, remind or send statements without the person's yes. Each one emails the customer.
- Don't put a company's prices on its members' own records. Put the group on the account record.
- Don't record part-payments as payments on an invoice.
- Don't open a merchant account with
spendingLimit: 0expecting no credit. - Don't post a charge for something the customer paid at checkout. That bills them twice.
- Don't add a contact as a member. Members sign in.