Stores API — Manage Retail Locations Under a Company

Stores represent individual physical retail locations operating under a parent company. Every store is linked to exactly one company via companyId, carries a unique store number, and an optional free-text address. Stores can be independently activated or deactivated — only active stores can participate in billing transactions and inventory management. Users (admins and employees) are assigned to stores, and each store maintains its own product inventory through the stores_inventories junction table.

Endpoints overview

Method	Path	Auth required	Description
`GET`	`/api/stores`	No	List stores (paginated, includes company)
`GET`	`/api/stores/:id`	No	Get a single store by UUID
`POST`	`/api/stores`	Admin / Owner	Create a new store
`PUT`	`/api/stores/:id`	Admin / Owner	Update store fields
`PUT`	`/api/stores/activate/:id`	Admin / Owner	Activate a store
`PUT`	`/api/stores/deactivate/:id`	Admin / Owner	Deactivate a store
`GET`	`/api/admin-stores`	Owner	List admins with their assigned store
`DELETE`	`/api/admin-stores/:userId/store`	Owner	Remove store assignment from an admin

Read store endpoints (GET /api/stores, GET /api/stores/:id) are public. Write operations require a valid session with an Admin or Owner role. Admin-store assignment endpoints require the Owner role.

List stores

GET /api/stores

Returns a paginated list of stores. Each record includes the associated company object (companyId, name, rtn).

limit

integer

default:"10"

Maximum number of store records to return per page.

offset

integer

default:"0"

Number of records to skip before starting the page. Use with limit for pagination.

Response `200`

{
  "total": 2,
  "data": [
    {
      "storeId": "a1b2c3d4-0000-4000-8000-000000000001",
      "storeNumber": 1,
      "address": "Blvd. Morazán, Tegucigalpa",
      "isActive": true,
      "companyId": "3f2e1a00-bc45-4d78-a9f2-000000000001",
      "company": {
        "companyId": "3f2e1a00-bc45-4d78-a9f2-000000000001",
        "name": "ServiCredit",
        "rtn": "08011999123456"
      },
      "createdAt": "2024-02-01T08:00:00.000Z",
      "updatedAt": "2024-02-01T08:00:00.000Z"
    }
  ]
}

Get store by ID

GET /api/stores/:id

string

required

UUID of the store to retrieve.

Returns the full store object, including the embedded company object.

Responses

Status	Description
`200`	Store object returned.
`404`	No store found with the given ID.

{
  "storeId": "a1b2c3d4-0000-4000-8000-000000000001",
  "storeNumber": 1,
  "address": "Blvd. Morazán, Tegucigalpa",
  "isActive": true,
  "companyId": "3f2e1a00-bc45-4d78-a9f2-000000000001",
  "company": {
    "companyId": "3f2e1a00-bc45-4d78-a9f2-000000000001",
    "name": "ServiCredit",
    "rtn": "08011999123456"
  }
}

Create a store

POST /api/stores

storeNumber is a positive integer — it identifies the store numerically within its company (e.g., Store 1, Store 2). It is not a street address. The optional address field holds the free-text street or location description.

Request body

storeNumber

integer

required

Numeric identifier for the store within its company. Must be a positive integer (e.g., 1, 2, 5). Non-integer or non-positive values return a 400 error.

companyId

string

required

UUID of the parent company. The company must already exist — a 404 is returned if it does not.

address

string

Optional free-text street address or location description for this store (e.g., "Col. Palmira, Tegucigalpa"). Stored as NULL if omitted.

Example request

curl -X POST https://your-domain.com/api/stores \
  -H "Content-Type: application/json" \
  -d '{
    "storeNumber": 1,
    "address": "Col. Palmira, Tegucigalpa",
    "companyId": "3f2e1a00-bc45-4d78-a9f2-000000000001"
  }'

Responses

Status	Description
`201`	Store created successfully.
`400`	Validation failed — `storeNumber` missing, not a positive integer, or `companyId` blank.
`404`	Parent company not found.
`500`	Unexpected server error.

{
  "message": "Tienda creada correctamente",
  "store": {
    "storeId": "a1b2c3d4-0000-4000-8000-000000000001",
    "storeNumber": 1,
    "address": "Col. Palmira, Tegucigalpa",
    "isActive": true,
    "companyId": "3f2e1a00-bc45-4d78-a9f2-000000000001",
    "createdAt": "2024-06-01T14:30:00.000Z",
    "updatedAt": "2024-06-01T14:30:00.000Z"
  }
}

Update a store

PUT /api/stores/:id

string

required

UUID of the store to update.

All body fields are optional. Only the fields provided will be updated.

storeNumber

integer

New store number. Must remain a positive integer if supplied.

address

string

New free-text address. Pass an empty string or omit to clear the field.

companyId

string

Reassign the store to a different company UUID. The target company must exist.

Responses

Status	Description
`200`	Store updated successfully.
`400`	Validation failed — invalid `storeNumber` or blank `companyId`.
`404`	Store or target company not found.
`500`	Unexpected server error.

{
  "message": "Tienda actualizada correctamente",
  "store": {
    "storeId": "a1b2c3d4-0000-4000-8000-000000000001",
    "storeNumber": 2,
    "address": "San Pedro Sula, Cortés",
    "isActive": true,
    "companyId": "3f2e1a00-bc45-4d78-a9f2-000000000001"
  }
}

Activate a store

PUT /api/stores/activate/:id

Sets isActive to true for the specified store. Returns 400 if the store is already active.

string

required

UUID of the store to activate.

Responses

Status	Description
`200`	Store activated successfully.
`400`	Store is already active.
`404`	Store not found.

{ "message": "Tienda activada correctamente" }

Deactivate a store

PUT /api/stores/deactivate/:id

Sets isActive to false for the specified store. Returns 400 if the store is already inactive.

string

required

UUID of the store to deactivate.

Responses

Status	Description
`200`	Store deactivated successfully.
`400`	Store is already inactive.
`404`	Store not found.

{ "message": "Tienda desactivada correctamente" }

Admin store assignment

Admin users can be assigned to a specific store so they manage that location. The admin-stores resource exposes two utility endpoints, both restricted to the Owner role and requiring a valid token cookie.

List admins with their assigned store

GET /api/admin-stores

Authentication: ✅ Required — Owner role Returns all users who hold the ADMIN role, each with their assigned store object embedded (or null if unassigned).

[
  {
    "userId": "u1u1u1u1-0000-4000-8000-000000000001",
    "first_name": "María",
    "first_last_name": "López",
    "email": "maria@servicredit.com",
    "storeId": "a1b2c3d4-0000-4000-8000-000000000001",
    "store": {
      "storeId": "a1b2c3d4-0000-4000-8000-000000000001",
      "storeNumber": 1,
      "address": "Col. Palmira, Tegucigalpa",
      "isActive": true
    },
    "roles": [{ "roleId": "r1r1r1r1-0000-0000-0000-000000000001", "name": "ADMIN" }]
  }
]

Remove store assignment from an admin

DELETE /api/admin-stores/:userId/store

Clears the storeId field (NULL) on the specified user, effectively un-assigning them from their current store. Authentication: ✅ Required — Owner role

userId

string

required

UUID of the admin user whose store assignment should be removed.

Status	Description
`200`	Assignment removed successfully.
`401`	Missing or invalid `token` cookie.
`403`	Authenticated user does not have the `Owner` role.
`404`	User not found.

{ "message": "Tienda removida correctamente" }

Store object reference

storeId

string

UUID v4 primary key, auto-generated on creation.

storeNumber

integer

Numeric identifier for this store within its company. Positive integer, not nullable.

address

string | null

Optional free-text street address or location description.

isActive

boolean

Whether the store is currently active. Defaults to true on creation. Only active stores can process bills.

companyId

string

UUID of the parent company this store belongs to.

company

object

Embedded company object included in list and single-record GET responses.

Show company fields

companyId

string

UUID of the parent company.

name

string

Legal name of the company.

rtn

string

Tax registration number of the company.

createdAt

string

ISO 8601 timestamp of record creation.

updatedAt

string

ISO 8601 timestamp of the most recent update.

Overview

Users & Access

Organization

Catalog

Billing & Payments

Analytics

Stores API — Manage Retail Locations Under a Company

Endpoints overview

List stores

Response `200`

Get store by ID

Responses

Create a store

Request body

Example request

Responses

Update a store

Responses

Activate a store

Responses

Deactivate a store

Responses

Admin store assignment

List admins with their assigned store

Remove store assignment from an admin

Store object reference

Build docs developers (and LLMs) love

Overview

Users & Access

Organization

Catalog

Billing & Payments

Analytics

Documentation Index

​Endpoints overview

​List stores

​Response 200

​Get store by ID

​Responses

​Create a store

​Request body

​Example request

​Responses

​Update a store

​Responses

​Activate a store

​Responses

​Deactivate a store

​Responses

​Admin store assignment

​List admins with their assigned store

​Remove store assignment from an admin

​Store object reference

Build docs developers (and LLMs) love

Endpoints overview

List stores

Response `200`

Get store by ID

Responses

Create a store

Request body

Example request

Responses

Update a store

Responses

Activate a store

Responses

Deactivate a store

Responses

Admin store assignment

List admins with their assigned store

Remove store assignment from an admin

Store object reference