Order & Payment Types

Overview

Order Types and Payment Types are global master data entities used to classify sales orders within the Merq platform. Unlike other master data (Channel, Account, etc.), these entities are not workspace-scoped and are shared across all workspaces.

Key characteristics:

• Global entities — No workspace_id field, shared across all workspaces
• Used in sales order creation — Required fields when creating a sales order
• Read-only for mobile — Mobile app can only read active types via /app/v1/ endpoints
• CRUD for web admin — Full create, read, update, delete via /office/v1/ endpoints with RBAC
• Seeded with defaults — 3 order types and 3 payment types seeded on initial deployment

Data Models

OrderType Model

Field	Type	Description	Constraints
id	integer	Primary key	Auto-increment
name	string	Display name (e.g., “Sell In”)	VARCHAR(100), NOT NULL
code	string	Machine code (e.g., “sell_in”)	VARCHAR(50), NOT NULL, UNIQUE
is_active	boolean	Whether type is currently active	DEFAULT TRUE
created_at	timestamp	Creation timestamp	TIMESTAMPTZ
updated_at	timestamp	Last update timestamp	TIMESTAMPTZ
deleted_at	timestamp	Soft delete timestamp	TIMESTAMPTZ (nullable)

PaymentType Model

Field	Type	Description	Constraints
id	integer	Primary key	Auto-increment
name	string	Display name (e.g., “Cash”)	VARCHAR(100), NOT NULL
code	string	Machine code (e.g., “cash”)	VARCHAR(50), NOT NULL, UNIQUE
is_active	boolean	Whether type is currently active	DEFAULT TRUE
created_at	timestamp	Creation timestamp	TIMESTAMPTZ
updated_at	timestamp	Last update timestamp	TIMESTAMPTZ
deleted_at	timestamp	Soft delete timestamp	TIMESTAMPTZ (nullable)

Default Seed Data

Order Types

Seeded by the sales order migration:

ID	Name	Code	Description
1	Sell In	sell_in	Initial stock for new outlet
2	Replenishment	replenishment	Regular restock order
3	Pre Order	pre_order	Future delivery order

Payment Types

ID	Name	Code	Description
1	Cash	cash	Payment on delivery
2	Transfer	transfer	Bank transfer
3	Credit	credit	Credit terms

API Endpoints

Order Types

Method	Endpoint	Permission	Description
GET	/app/v1/order-types	Authenticated	List active types (mobile)
GET	/office/v1/order-types	order_type.view or order_type.manage	List all types (web admin)
GET	/office/v1/order-types/:id	order_type.view or order_type.manage	Get single type (web admin)
POST	/office/v1/order-types	order_type.manage (full)	Create new type
PUT	/office/v1/order-types/:id	order_type.manage (full)	Update type
DELETE	/office/v1/order-types/:id	order_type.manage (full)	Delete type (soft)

Payment Types

Method	Endpoint	Permission	Description
GET	/app/v1/payment-types	Authenticated	List active types (mobile)
GET	/office/v1/payment-types	payment_type.view or payment_type.manage	List all types (web admin)
GET	/office/v1/payment-types/:id	payment_type.view or payment_type.manage	Get single type (web admin)
POST	/office/v1/payment-types	payment_type.manage (full)	Create new type
PUT	/office/v1/payment-types/:id	payment_type.manage (full)	Update type
DELETE	/office/v1/payment-types/:id	payment_type.manage (full)	Delete type (soft)

Note: App endpoints return only is_active=true types. Office endpoints return all types.

Example Requests & Responses

List Order Types (Mobile)

GET /app/v1/order-types

Response:

{
  "data": [
    {
      "id": 1,
      "name": "Sell In",
      "code": "sell_in",
      "is_active": true
    },
    {
      "id": 2,
      "name": "Replenishment",
      "code": "replenishment",
      "is_active": true
    },
    {
      "id": 3,
      "name": "Pre Order",
      "code": "pre_order",
      "is_active": true
    }
  ],
  "message": "order types retrieved",
  "code": "ORDER_TYPE_LIST"
}

List Payment Types (Mobile)

GET /app/v1/payment-types

Response:

{
  "data": [
    {
      "id": 1,
      "name": "Cash",
      "code": "cash",
      "is_active": true
    },
    {
      "id": 2,
      "name": "Transfer",
      "code": "transfer",
      "is_active": true
    },
    {
      "id": 3,
      "name": "Credit",
      "code": "credit",
      "is_active": true
    }
  ],
  "message": "payment types retrieved",
  "code": "PAYMENT_TYPE_LIST"
}

Create Order Type (Admin)

POST /office/v1/order-types
Content-Type: application/json

{
  "name": "Consignment",
  "code": "consignment",
  "is_active": true
}

Response:

{
  "data": {
    "id": 4,
    "name": "Consignment",
    "code": "consignment",
    "is_active": true
  },
  "message": "order type created",
  "code": "ORDER_TYPE_CREATED"
}

Update Payment Type (Admin)

PUT /office/v1/payment-types/3
Content-Type: application/json

{
  "name": "Credit Card",
  "code": "credit_card",
  "is_active": true
}

Response:

{
  "data": null,
  "message": "payment type updated",
  "code": "PAYMENT_TYPE_UPDATED"
}

Delete Order Type (Admin)

DELETE /office/v1/order-types/4

Response:

{
  "data": null,
  "message": "order type deleted",
  "code": "ORDER_TYPE_DELETED"
}

Integration with Sales Order

Order types and payment types are required fields when creating a sales order:

Create Sales Order Request:

{
  "outlet_id": 123,
  "visit_id": 456,
  "order_type_id": 2,
  "payment_type_id": 1,
  "items": [
    {
      "product_id": 10,
      "quantity": 5,
      "unit_price": 50000
    }
  ],
  "po_photos": ["photo1.jpg", "photo2.jpg"],
  "signature": "signature.jpg"
}

Create Sales Order Response:

{
  "data": {
    "id": 789,
    "order_type": {
      "id": 2,
      "name": "Replenishment",
      "code": "replenishment"
    },
    "payment_type": {
      "id": 1,
      "name": "Cash",
      "code": "cash"
    },
    "outlet_id": 123,
    "total": 250000,
    "status": "pending"
  },
  "message": "sales order created",
  "code": "SALES_ORDER_CREATED"
}

Global vs Workspace-Scoped

Unlike other master data (Channel, Account, etc.), Order Types and Payment Types are global:

Characteristic	Order/Payment Types	Other Master Data
Workspace ID	❌ No	✅ Yes
Scoped queries	❌ No	✅ Yes
Shared across workspaces	✅ Yes	❌ No
Customizable per workspace	❌ No	✅ Yes

Rationale:

• Order types and payment types are universal business concepts
• Consistency across workspaces for reporting
• Simplified mobile app (same options everywhere)
• Reduced configuration overhead for new workspaces

RBAC Permissions

Entity	View Permission	Manage Permission
OrderType	order_type.view	order_type.manage
PaymentType	payment_type.view	payment_type.manage

Permission constants:

• PermissionKeyOrderTypeView — View order types (office)
• PermissionKeyOrderTypeManage — Create, update, delete order types
• PermissionKeyPaymentTypeView — View payment types (office)
• PermissionKeyPaymentTypeManage — Create, update, delete payment types

Mobile access:

• App endpoints (/app/v1/) require only authentication (no RBAC)
• Read-only access to active types
• Cannot create, update, or delete types

Office access:

• List endpoints require order_type.view or payment_type.view (or manage)
• Mutation endpoints (POST, PUT, DELETE) require *_manage with AccessLevelFull

Implementation Details

Handler Pattern

Both order types and payment types follow the standard handler → service → repository pattern:

internal/handler/order_type_handler.go
internal/handler/payment_type_handler.go

Key implementation notes:

• GetAll endpoints support pagination via page and limit query params
• is_active filter applied automatically on app endpoints
• Soft delete implemented via deleted_at timestamp
• All office endpoints require authentication + RBAC middleware

Request/Response Structs

Order Type Request:

type orderTypeRequest struct {
    Name     string `json:"name" binding:"required"`
    Code     string `json:"code" binding:"required"`
    IsActive *bool  `json:"is_active"`
}

Payment Type Request:

type paymentTypeRequest struct {
    Name     string `json:"name" binding:"required"`
    Code     string `json:"code" binding:"required"`
    IsActive *bool  `json:"is_active"`
}

Note: is_active defaults to true if not provided in request.

Related Topics

• Sales Order Mobile Guide — Creating sales orders with order/payment types
• Outlet Enrichment — Related master data for outlets
• Products API — Product lookup for sales order items