Business Process API Actions

This document provides a comprehensive guide on how to use SureMSA on a standalone basis without Salesforce via REST APIs. Each critical business process is mapped to its corresponding API endpoint.

Overview

SureMSA can operate completely independently of external systems like Salesforce, QuickBooks, or other integrations. All core business processes can be executed through REST APIs.

Core Business Process APIs

1. Customer Lifecycle Management

Business Action	API Endpoint	Method	Status	Notes
Create Customer	`POST /customers`	✅ Available	READY	Auto-generates customer code from name
Update Customer	`POST /customers`	✅ Available	READY	Include `id` field to update
Delete Customer	`DELETE /customers/{id}`	✅ Available	READY	Soft delete
Get Customer by ID	`GET /customers/{id}`	✅ Available	READY	-
Get Customer by Code	`GET /customers?code={code}`	✅ Available	READY	-
List All Customers	`GET /customers/all`	✅ Available	READY	-
Add Customer Tag	`POST /customers/{id}/tag/{tag}`	✅ Available	READY	Organize customers

Create Customer API Example:

POST /customers
Content-Type: application/json

{
  "fullName": "Sterling Bio Inc",
  "name": "Sterling Bio",
  "website": "https://sterlingbio.com",
  "createdViaChannel": "INTERNAL",
  "type": "ENTERPRISE",
  "autoCreateMasterAgreement": true
}

Response:

{
  "id": 123,
  "code": "sterlingb",
  "fullName": "Sterling Bio Inc",
  "name": "Sterling Bio"
}

View Customer Data Model →

2. Master Agreement Management

Business Action	API Endpoint	Method	Status	Notes
Create Master Agreement	`POST /subscriptions/master-agreements`	✅ Available	READY	Primary contract for customer
Update Master Agreement	`POST /subscriptions/master-agreements`	✅ Available	READY	Include `id` field
Auto-Create on Customer	`POST /customers`	✅ Available	READY	Set `autoCreateMasterAgreement: true`
Create Default Agreement	`POST /subscriptions/master-agreements/{customerId}`	✅ Available	READY	Creates with defaults
Delete Master Agreement	`DELETE /subscriptions/master-agreements/{id}`	✅ Available	READY	-
Manual Change Agreement	`POST /subscriptions/master-agreements/manual/change`	✅ Available	READY	With reason tracking

Create Master Agreement API Example:

POST /subscriptions/master-agreements
Content-Type: application/json

{
  "customerCode": "sterlingb",
  "name": "Sterling Bio Enterprise Agreement",
  "dateStart": "2026-01-01",
  "dateEnd": "2026-12-31",
  "status": "ACTIVE",
  "type": "ENTERPRISE"
}

Auto-Create with Customer:

POST /customers
{
  "fullName": "Sterling Bio Inc",
  "autoCreateMasterAgreement": true  // ✅ Auto-creates agreement
}

View Agreements Data Model →

3. Subscription Management

Business Action	API Endpoint	Method	Status	Notes
Create Subscription	`POST /subscriptions`	✅ Available	READY	Under Master Agreement
Update Subscription	`POST /subscriptions`	✅ Available	READY	Include `id` field
Delete Subscription	`DELETE /subscriptions/{id}`	✅ Available	READY	-
Get Subscription by ID	`GET /subscriptions/{id}`	✅ Available	READY	-
Get by Billing Project ID	`GET /subscriptions/by/billingProjectId`	✅ Available	READY	Unique identifier
Get by Customer Code	`GET /subscriptions/by/customerCode`	✅ Available	READY	All customer subs
Generate Billing Project ID	`GET /subscriptions/generate/billingProjectId`	✅ Available	READY	Preview ID before creation
Manual Subscription Change	`POST /subscriptions/manual/change`	✅ Available	READY	With reason tracking

Create Subscription API Example:

POST /subscriptions
Content-Type: application/json

{
  "customerCode": "sterlingb",
  "name": "Enterprise Platform Subscription",
  "dateStart": "2026-01-01",
  "dateEnd": "2026-12-31",
  "masterAgreementId": 456,
  "subscriptionTypeId": 789,
  "status": "ACTIVE"
}

Response:

{
  "id": 321,
  "billingProjectId": "sterlingb-enterprise",
  "customerCode": "sterlingb",
  "name": "Enterprise Platform Subscription"
}

Key Features:

✅ Auto-generates billingProjectId from customer code + subscription name
✅ Links to Master Agreement
✅ Tracks subscription lifecycle (ACTIVE, PAUSED, EXPIRED)

View Subscriptions Data Model →

4. License Management

Business Action	API Endpoint	Method	Status	Notes
Create License	Created via Order/Cart	⚠️ Indirect	VIA CART	Licenses created from orders
Update License Name	`PUT /licenses/{id}/name/{name}`	✅ Available	READY	-
Update Primary Type	`PUT /licenses/{id}/primaryLicenseType/{type}`	✅ Available	READY	-
Update External Project ID	`PUT /licenses/{id}/external-project-id/{id}`	✅ Available	READY	Link to external system
Pause License	`PUT /licenses/{id}/pause`	✅ Available	READY	Temporarily suspend
Resume License	`PUT /licenses/{id}/resume`	✅ Available	READY	Reactivate
Add Named Users	`POST /licenses/{id}/named-users/add`	✅ Available	READY	For named user licenses
Remove Named Users	`DELETE /licenses/{id}/named-users/remove`	✅ Available	READY	-
Swap License	`POST /licenses/{id}/swap`	✅ Available	READY	Transfer to different user
Get License by ID	`GET /licenses/{id}`	✅ Available	READY	-
Get by Subscription	`GET /licenses/by/subscriptionId`	✅ Available	READY	All licenses in subscription
Get by Customer Code	`GET /licenses/by/customerCode`	✅ Available	READY	All customer licenses

Update License Example:

PUT /licenses/123/name/Sterling-Bio-License-001

Add Named Users:

POST /licenses/123/named-users/add
Content-Type: application/json

["john.doe@sterlingbio.com", "jane.smith@sterlingbio.com"]

Important Note:

⚠️ Licenses are not created directly via a POST /licenses endpoint
✅ Licenses are created through the Cart/Order workflow
✅ See Cart & Order Flow below

View Licensing Data Model →

5. Cart & Order Workflow

The Cart is the primary mechanism for creating subscriptions and licenses in SureMSA.

Business Action	API Endpoint	Method	Status	Notes
Create Cart	`POST /cart`	✅ Available	READY	Shopping cart for products
Add Cart Product	`POST /cart/cartProduct`	✅ Available	READY	Add products to cart
Get Cart by ID	`GET /cart/{id}`	✅ Available	READY	-
Get Cart by Opportunity	`GET /cart/by/opportunityId`	✅ Available	READY	Salesforce integration
Set Cart to PLACED	`POST /cart/set/placed/{id}/subsTxType/{type}`	✅ Available	READY	Creates order
Set Cart to COMPLETED	`POST /cart/set/completed/{id}`	✅ Available	READY	Provisions licenses
Set Cart to CANCELED	`POST /cart/set/canceled/{id}`	✅ Available	READY	Cancel order
Delete Cart	`DELETE /cart/{id}`	✅ Available	READY	-

Create Cart API Example:

POST /cart
Content-Type: application/json

{
  "customerCode": "sterlingb",
  "customerName": "Sterling Bio Inc",
  "name": "Q1 2026 Enterprise Purchase",
  "description": "Annual enterprise subscription renewal",
  "dateStart": "2026-01-01",
  "dateEnd": "2026-12-31",
  "months": 12,
  "channel": "INTERNAL",
  "stage": "DRAFT",
  "totalPrice": 50000.00,
  "currency": "USD",
  "repaymentType": "ONE_TIME",
  "cartProducts": [
    {
      "productId": 789,
      "name": "Enterprise Plan",
      "quantity": 10,
      "totalPrice": 50000.00
    }
  ]
}

Cart Workflow:

Cart Stages:

DRAFT - Being built
PLACED - Order submitted
AWAITING_ACCEPT - Pending approval
COMPLETED - Licenses provisioned
CANCELED - Order canceled

View Cart Workflow Details →

6. Product Management

Business Action	API Endpoint	Method	Status	Notes
Create Product	`POST /products`	✅ Available	READY	Define sellable products
Update Product	`POST /products`	✅ Available	READY	Include `id` field
Delete Product	`DELETE /products/{id}`	✅ Available	READY	-
Get Product by ID	`GET /products/{id}`	✅ Available	READY	-
Get All Products	`GET /products/all`	✅ Available	READY	-
Import from QuickBooks	`POST /products/import/quickbooks/all/data`	✅ Available	READY	Optional integration
Import from Salesforce	`GET /products/import/salesforce/data`	✅ Available	READY	Optional integration
Create in QuickBooks	`POST /products/create/quickbooks/product`	✅ Available	READY	Push to QuickBooks

Create Product API Example:

POST /products
Content-Type: application/json

{
  "name": "Enterprise Platform License",
  "code": "EPL-2026",
  "description": "Full platform access with enterprise features",
  "productFamily": "PLATFORM",
  "licenseType": "SUBSCRIPTION",
  "pricePerMonth": 500.00,
  "currency": "USD",
  "billingType": "MONTHLY_PAYMENT",
  "isActive": true
}

Response:

{
  "id": 789,
  "name": "Enterprise Platform License",
  "code": "EPL-2026",
  "pricePerMonth": 500.00
}

View Products Data Model →

Complete Workflow: Customer to License (No Salesforce)

Scenario: New Enterprise Customer with Subscription

# Step 1: Create Customer with Auto-Created Master Agreement
POST /customers
{
  "fullName": "Sterling Bio Inc",
  "name": "Sterling Bio",
  "website": "https://sterlingbio.com",
  "createdViaChannel": "INTERNAL",
  "type": "ENTERPRISE",
  "autoCreateMasterAgreement": true  # ✅ Auto-creates agreement
}

# Response: { "id": 123, "code": "sterlingb" }

# Step 2: Create Subscription
POST /subscriptions
{
  "customerCode": "sterlingb",
  "name": "Enterprise Platform",
  "dateStart": "2026-01-01",
  "dateEnd": "2026-12-31",
  "masterAgreementId": 124,  # From auto-created agreement
  "subscriptionTypeId": 1
}

# Response: { "id": 321, "billingProjectId": "sterlingb-enterprise" }

# Step 3: Create Product (if not exists)
POST /products
{
  "name": "Enterprise License",
  "code": "ENT-LIC",
  "pricePerMonth": 500.00,
  "productFamily": "PLATFORM"
}

# Response: { "id": 789 }

# Step 4: Create Cart with Products
POST /cart
{
  "customerCode": "sterlingb",
  "name": "Initial Purchase",
  "stage": "DRAFT",
  "totalPrice": 5000.00,
  "currency": "USD",
  "repaymentType": "ONE_TIME",
  "cartProducts": [
    {
      "productId": 789,
      "quantity": 10,
      "totalPrice": 5000.00
    }
  ]
}

# Response: { "id": 456 }

# Step 5: Place Cart (Create Order)
POST /cart/set/placed/456/subsTxType/NEW

# Step 6: Process Payment (external or internal)
# ... payment processing ...

# Step 7: Complete Cart (Provision Licenses)
POST /cart/set/completed/456

# ✅ Result: 10 licenses automatically created and provisioned!

Financial Transaction APIs

Quote → Order → Invoice Flow

Business Action	API Endpoint	Method	Status	Notes
Create Quote	`POST /payment/quotes`	✅ Available	READY	Quote is a DRAFT cart
Update Quote	`POST /payment/quotes`	✅ Available	READY	-
Get Quote by ID	`GET /payment/quotes/{id}`	✅ Available	READY	-
Convert Quote to Order	`POST /cart/set/placed/{id}`	✅ Available	READY	Changes stage to PLACED
Create Invoice	Auto-generated	⚠️ Automatic	AUTO	Created on cart completion
Get Invoice by ID	`GET /payment/invoices/{id}`	✅ Available	READY	-
Get Invoices by Customer	`GET /payment/invoices/by/customerCode`	✅ Available	READY	-
Mark Invoice as Paid	`PUT /payment/invoices/{id}/status/PAID`	✅ Available	READY	-

Quote Workflow:

View Quote/Order/Invoice Flow →

Payment Processing APIs

Business Action	API Endpoint	Method	Status	Notes
Create Payment	`POST /payment`	✅ Available	READY	Links to cart/order
Get Payment by ID	`GET /payment/{id}`	✅ Available	READY	-
Get Payment Methods	`GET /payment/methods`	✅ Available	READY	Customer payment methods
Add Payment Method	`POST /payment/methods`	✅ Available	READY	Credit card, ACH, etc.
Process Stripe Payment	`POST /payment/stripe/process`	✅ Available	READY	Stripe integration

API Summary Table

Business Process	Primary API Endpoint	Create Method	API Status	External System Dependency
Customer	`POST /customers`	Direct API	✅ READY	✅ Independent
Master Agreement	`POST /subscriptions/master-agreements`	Direct API	✅ READY	✅ Independent
Subscription	`POST /subscriptions`	Direct API	✅ READY	✅ Independent
License	Via Cart Completion	Indirect (Cart workflow)	✅ READY	✅ Independent
Product	`POST /products`	Direct API	✅ READY	✅ Independent
Cart	`POST /cart`	Direct API	✅ READY	✅ Independent
Quote	`POST /payment/quotes`	Direct API	✅ READY	✅ Independent
Order	`POST /cart/set/placed/{id}`	State Change	✅ READY	✅ Independent
Invoice	Auto-generated on completion	Automatic	✅ READY	✅ Independent
Payment	`POST /payment`	Direct API	✅ READY	⚠️ Optional (Stripe/Gateway)

Table Column Definitions

Business Process - The core business entity or workflow
Primary API Endpoint - Main REST API for creating/managing the entity
Create Method - How the entity is created:
- Direct API: Standard REST POST endpoint
- Indirect: Created as part of another workflow
- State Change: Created by changing entity state
- Automatic: System-generated
API Status - Current implementation status (✅ READY = Production ready)
External System Dependency - Whether Salesforce or other external systems are required:
- ✅ Independent - Works completely standalone
- ⚠️ Optional - Can integrate but not required
- ❌ Required - External system mandatory

External System Integration Notes

Good News: SureMSA is 100% Standalone Ready! 🎉

All core business processes work without any external system dependencies:

✅ No Salesforce Required
- All entities (Customer, Agreement, Subscription, License, Product) can be created via REST API
- Customer codes auto-generated internally
- Billing Project IDs auto-generated from customer + subscription name
- Master Agreements can auto-create with customers or be created independently
⚠️ Optional Integrations Available
- Payment Processing: Can integrate with Stripe, but also supports internal payment tracking
- Salesforce: Optional bidirectional sync for customers who use Salesforce CRM
- QuickBooks: Optional accounting integration for invoice/payment sync
- WooCommerce: Optional e-commerce integration for web orders
How to Enable Optional Integrations (if desired):
- Set appropriate channel field to integration source (e.g., "SALESFORCE", "QUICKBOOKS")
- Configure external system credentials in system settings
- Use import endpoints: POST /customers/import/all/quickbooks/customers
- Link external IDs via CustomerExternalSystemRequest field
Standalone Operation Best Practices:
- Use createdViaChannel: "INTERNAL" for all entities
- Omit customerExternalSystemRequest field when creating customers
- Rely on auto-generation for customer codes and billing project IDs
- Use Cart workflow for end-to-end order processing

The "❌ No" in the old table meant "No external system required" - which is actually great news!

Key Principles for Standalone Operation

1. Customer Code Generation

✅ Auto-generated from customer fullName
✅ Unique and collision-resistant
✅ No external system required

2. Billing Project ID Generation

✅ Auto-generated from customerCode + subscriptionName
✅ Format: {customerCode}-{subscriptionName} (lowercase, sanitized)
✅ Can be previewed before creation

3. Master Agreement Auto-Creation

✅ Set autoCreateMasterAgreement: true in customer creation
✅ Creates default agreement automatically
✅ No manual step required

4. License Provisioning

✅ Licenses created via Cart workflow
✅ Automatic provisioning on cart completion
✅ No separate license creation API needed

5. Channel Independence

✅ Set createdViaChannel: "INTERNAL" for all entities
✅ No external system integration required
✅ Full standalone operation

Authentication & Authorization

All API endpoints require authentication:

Authorization: Bearer {JWT_TOKEN}

Required Roles:

user - Basic access
admin - Full CRUD operations
service - Service-to-service calls

Error Handling

All APIs return standard error responses:

{
  "status": 422,
  "message": "Unable to create customer, validation failed",
  "errors": ["fullName is required"]
}

Common Status Codes:

200 - Success
201 - Created
400 - Bad Request
401 - Unauthorized
404 - Not Found
422 - Unprocessable Entity (validation error)

Next Steps

Set up authentication - Obtain JWT tokens
Create test customer - Use POST /customers with autoCreateMasterAgreement: true
Create products - Define your product catalog
Test cart workflow - Create cart → place → complete
Monitor licenses - Verify automatic license provisioning

Support

For API questions or issues:

📧 Email: support@sterlingbio.com
📚 Documentation: https://docs.suremsa.com
💬 GitHub: https://github.com/JetRev/ink

Overview​

Core Business Process APIs​

1. Customer Lifecycle Management​

2. Master Agreement Management​

3. Subscription Management​

4. License Management​

5. Cart & Order Workflow​

6. Product Management​

Complete Workflow: Customer to License (No Salesforce)​

Scenario: New Enterprise Customer with Subscription​

Financial Transaction APIs​

Quote → Order → Invoice Flow​

Payment Processing APIs​

API Summary Table​

Table Column Definitions​

External System Integration Notes​

Key Principles for Standalone Operation​

1. Customer Code Generation​

2. Billing Project ID Generation​

3. Master Agreement Auto-Creation​

4. License Provisioning​

5. Channel Independence​

Authentication & Authorization​

Error Handling​

Next Steps​

Related Documentation​

Support​

Overview

Core Business Process APIs

1. Customer Lifecycle Management

2. Master Agreement Management

3. Subscription Management

4. License Management

5. Cart & Order Workflow

6. Product Management

Complete Workflow: Customer to License (No Salesforce)

Scenario: New Enterprise Customer with Subscription

Financial Transaction APIs

Quote → Order → Invoice Flow

Payment Processing APIs

API Summary Table

Table Column Definitions

External System Integration Notes

Key Principles for Standalone Operation

1. Customer Code Generation

2. Billing Project ID Generation

3. Master Agreement Auto-Creation

4. License Provisioning

5. Channel Independence

Authentication & Authorization

Error Handling

Next Steps

Related Documentation

Support