Signup and approval
How buyers create a company and how merchants approve it.
A buyer creates a company with POST /store/companies. One call creates the company, its customer group, and the caller as its owner. If any part fails, all of it rolls back.
Two ways to sign up
| Caller | Send customer | Result |
|---|---|---|
| New buyer, with a registration token | Required (customer_required without it) | A customer is created with the company |
| Signed-in customer with no company | Not allowed (customer_not_allowed) | The existing customer becomes the owner |
A customer who is already in a company gets already_in_company.
New buyer
- Register an identity:
POST /auth/customer/{provider}/register. The response holds a registration token. - Sign up the company with that token and
customer:
curl -X POST http://localhost:9000/store/companies \
-H "x-publishable-api-key: pk_..." \
-H "Authorization: Bearer <registration token>" \
-H "Content-Type: application/json" \
-d '{
"company": { "name": "Northwind Supply", "email": "purchasing@northwind.example" },
"customer": { "email": "jordan@northwind.example", "first_name": "Jordan" }
}'- Refresh the token with
POST /auth/token/refresh. The old token has no customer, so other routes reject it.
currency_code is optional. Without it the company gets the store's default currency. See Authentication for the token types.
Approval
The company.signup_requires_approval setting decides the starting status. It is off by default.
| Setting | New company | Buyer can |
|---|---|---|
| Off (default) | active | Use the company and check out straight away |
| On | pending | Read the company, but not change it or check out, until approved |
Merchants approve, suspend, and reactivate with POST /admin/companies/{id}, sending status. To list companies waiting for approval, call GET /admin/companies with status=pending.
Status changes
| From | To | Meaning |
|---|---|---|
pending | active | Approval. Emits company.approved as well as company.updated. |
active | suspended | Suspension. Buyers keep read access but can't change data or check out. |
suspended | active | Reactivation. |
Any other change fails with invalid_status_transition. A company can't go back to pending, and a pending company can't be suspended. Sending the current status is allowed.
curl -X POST http://localhost:9000/admin/companies/comp_123 \
-u "sk_...:" \
-H "Content-Type: application/json" \
-d '{ "status": "active" }'Buyers can't change a company's status, currency, or settings. POST /store/companies/me accepts contact details only: name, email, phone, and tax_id.