Skip to main content

Branch Creation

Overview​

A branch represents a cashier (or point of sale) within a store. Creating branches allows a store to distribute day-to-day operations across multiple cashiers while keeping ownership of the funds centralized.

Although each branch operates independently using its own credentials, all balances always belong to the parent store. Branches provide operational separation and transaction traceability rather than separate ownership of funds.

Why create branches?​

Creating branches allows you to:

  • ✅ Keep all balances under the parent store.
  • ✅ Give each cashier their own credentials.
  • ✅ Track who performed each operation.
  • ✅ Perform cash reconciliation more easily.
  • ✅ Avoid concentrating all activity in a single account.

How it works​

A branch is a sub-account created by a store user. Each branch has its own independent user account and can perform operations such as creating payment orders and managing it own profit margins. The store that creates a branch is its owner.

When a branch is created, three things happen simultaneously:

  • A new branch entity is registered in the system
  • A new user is created using the provided email address
  • A new financial account under this new user is created

⚠️ This user represents the branch and operates independently — it has its own credentials and access token, separate from the store that created it.


Endpoint​

POST /branch

Full API reference: Branch Creation


Authentication​

This endpoint requires a valid x-api-key and a Bearer Token issued to a user with the store role in headers.

x-api-key: <your_api_key>
Authorization: Bearer <access_token>

Requests from users without the store role will be rejected.

See the Authentication Guide to see more details.


Request Example​

curl -X POST "/api/v1/branch" \
-H "Content-Type: application/json" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <your_access_token>" \
-d '{
"name": "Branch 1",
"email": "branch@example.com"
}'

Behavior​

When this endpoint is called successfully:

  1. A new branch entity is created and associated with the calling store account
  2. A new user account is automatically generated using the provided email
  3. This user account represents the branch within the system and will be used for all branch-level operations

Next Steps​

After the branch is created, the branch user must complete the authentication process independently before making any API requests.

  1. The branch user follows the Authentication Guide
  2. Upon successful authentication, the branch user receives their own access token
  3. All subsequent requests made by the branch must use that token — not the store's token

Important Notes​

  • Only users with the store role can call this endpoint
  • Each branch operates independently with its own credentials and session
  • Access tokens are not shared between store and branch users