Salesforce ↔ WHMCS Mapping Reference
Complete field mapping and data transformation reference for order fulfillment workflow.
🗺️ Overview
This document provides the authoritative mapping between Salesforce Order/OrderItem data and WHMCS API parameters for the order fulfillment process.
Data Flow
Salesforce Order/OrderItems → BFF Transformation → WHMCS AddOrder API → WHMCS Services
📊 Complete Field Mapping
| Salesforce Field |
WHMCS Parameter |
Example Value |
Type |
Notes |
Order.AccountId |
clientid |
1 |
int |
Resolved via portal mapping table |
| N/A (System) |
paymentmethod |
"mailin" |
string |
Required by WHMCS API |
| N/A (System) |
noinvoice |
true |
bool |
Don't create invoice during provisioning |
| N/A (System) |
noemail |
true |
bool |
Don't send emails during provisioning |
Order.Id |
Added to notes |
"sfOrderId=8014x000000ABCDXYZ" |
string |
For tracking purposes |
OrderItem Array Mapping
| Salesforce Source |
WHMCS Parameter |
Example |
Type |
Transformation |
Product2.WH_Product_ID__c |
pid[] |
["185", "242", "246"] |
string[] |
Convert number to string |
Product2.Billing_Cycle__c |
billingcycle[] |
["monthly", "onetime", "monthly"] |
string[] |
Lowercase transformation |
OrderItem.Quantity |
qty[] |
[1, 1, 1] |
int[] |
Direct mapping |
Optional Parameters
| Salesforce Source |
WHMCS Parameter |
Default Value |
Notes |
| N/A |
promocode |
"" |
Not used in provisioning |
| N/A |
configoptions[] |
["", "", ""] |
Base64 encoded if needed |
| N/A |
customfields[] |
["", "", ""] |
Base64 encoded if needed |
🏷️ Product Mapping Examples
Internet Products
| Product Name |
Salesforce SKU |
WH_Product_ID__c |
WHMCS pid |
Billing_Cycle__c |
WHMCS billingcycle |
| Internet Silver (Home 1G) |
INTERNET-SILVER-HOME-1G |
181 |
"181" |
"Monthly" |
"monthly" |
| Internet Gold (Home 1G) |
INTERNET-GOLD-HOME-1G |
182 |
"182" |
"Monthly" |
"monthly" |
| Internet Platinum (Home 1G) |
INTERNET-PLATINUM-HOME-1G |
183 |
"183" |
"Monthly" |
"monthly" |
| Internet Silver (Apartment 1G) |
INTERNET-SILVER-APT-1G |
184 |
"184" |
"Monthly" |
"monthly" |
| Internet Gold (Apartment 1G) |
INTERNET-GOLD-APT-1G |
185 |
"185" |
"Monthly" |
"monthly" |
| Internet Platinum (Apartment 1G) |
INTERNET-PLATINUM-APT-1G |
186 |
"186" |
"Monthly" |
"monthly" |
Installation Products
| Product Name |
Salesforce SKU |
WH_Product_ID__c |
WHMCS pid |
Billing_Cycle__c |
WHMCS billingcycle |
| Single Installation |
INTERNET-INSTALL-SINGLE |
242 |
"242" |
"One-time" |
"onetime" |
| 12-Month Installation |
INTERNET-INSTALL-12M |
243 |
"243" |
"One-time" |
"onetime" |
| 24-Month Installation |
INTERNET-INSTALL-24M |
244 |
"244" |
"One-time" |
"onetime" |
| Weekend Installation Fee |
INTERNET-INSTALL-WEEKEND |
245 |
"245" |
"One-time" |
"onetime" |
Add-on Products
| Product Name |
Salesforce SKU |
WH_Product_ID__c |
WHMCS pid |
Billing_Cycle__c |
WHMCS billingcycle |
| Hikari Denwa Service |
INTERNET-ADDON-HOME-PHONE |
246 |
"246" |
"Monthly" |
"monthly" |
| Hikari Denwa Installation |
INTERNET-ADDON-DENWA-INSTALL |
247 |
"247" |
"One-time" |
"onetime" |
VPN Products
| Product Name |
Salesforce SKU |
WH_Product_ID__c |
WHMCS pid |
Billing_Cycle__c |
WHMCS billingcycle |
| VPN USA (San Francisco) |
VPN-USA-SF |
33 |
"33" |
"Monthly" |
"monthly" |
| VPN UK (London) |
VPN-UK-LONDON |
54 |
"54" |
"Monthly" |
"monthly" |
| VPN Activation Fee |
VPN-ACTIVATION |
37 |
"37" |
"One-time" |
"onetime" |
📋 Complete Order Example
Salesforce Order Structure
Order {
Id: "8014x000000ABCDXYZ",
AccountId: "001xx000004TmiQAAS",
Status: "Pending Review",
Order_Type__c: "Internet"
}
OrderItems [
{
Id: "8024x000000DEFGABC",
Product2: {
WH_Product_ID__c: 185,
Billing_Cycle__c: "Monthly",
SKU: "INTERNET-GOLD-APT-1G"
},
Quantity: 1
},
{
Id: "8024x000000HIJKLMN",
Product2: {
WH_Product_ID__c: 242,
Billing_Cycle__c: "One-time",
SKU: "INTERNET-INSTALL-SINGLE"
},
Quantity: 1
},
{
Id: "8024x000000OPQRSTU",
Product2: {
WH_Product_ID__c: 246,
Billing_Cycle__c: "Monthly",
SKU: "INTERNET-ADDON-HOME-PHONE"
},
Quantity: 1
}
]
Transformed WHMCS AddOrder Request
{
"action": "AddOrder",
"clientid": 1,
"paymentmethod": "mailin",
"pid": ["185", "242", "246"],
"billingcycle": ["monthly", "onetime", "monthly"],
"qty": [1, 1, 1],
"noinvoice": true,
"noemail": true,
"promocode": "",
"configoptions": ["", "", ""],
"customfields": ["", "", ""]
}
WHMCS AddOrder Response
{
"result": "success",
"orderid": 12345,
"serviceids": "67890,67891,67892",
"addonids": "",
"domainids": "",
"invoiceid": 0
}
🔄 Status Update Mapping
Salesforce Order Status Updates
During Fulfillment
| Step |
Order.Status |
Provisioning_Status__c |
WHMCS_Order_ID__c |
Notes |
| Initial |
"Pending Review" |
null |
null |
Customer placed order |
| CS Approval |
"Activating" |
"In Progress" |
null |
CS clicked provision |
| WHMCS Created |
"Activating" |
"In Progress" |
"12345" |
AddOrder completed |
| Services Active |
"Activated" |
"Fulfilled" |
"12345" |
AcceptOrder completed |
On Failure
| Step |
Order.Status |
Provisioning_Status__c |
Error Fields |
Notes |
| Validation Failure |
"Draft" |
"Failed" |
Error_Codec, Error_Messagec |
Revert to draft |
| WHMCS API Failure |
"Draft" |
"Failed" |
Error_Codec, Error_Messagec |
Rollback status |
OrderItem Status Updates
| Field |
Source |
Example |
Notes |
WHMCS_Service_ID__c |
AddOrder response (serviceids) |
"67890" |
Individual service ID |
Billing_Cycle__c |
Already set |
"Monthly" |
No change during fulfillment |
🔧 Data Transformation Rules
Billing Cycle Transformation
// Salesforce → WHMCS transformation
const billingCycleMap = {
Monthly: "monthly",
Quarterly: "quarterly",
Semiannually: "semiannually",
Annually: "annually",
"One-time": "onetime",
Onetime: "onetime",
};
// Implementation
billingCycle: product.billingCycle.toLowerCase();
Product ID Transformation
// Salesforce WH_Product_ID__c (number) → WHMCS pid (string)
productId: product.whmcsProductId.toString();
Client ID Resolution
// Order.AccountId → WHMCS clientid via mapping table
const mapping = await mappingsService.findBySfAccountId(order.AccountId);
clientId: mapping.whmcsClientId;
🛡️ Validation Rules
Required Field Validation
// Before WHMCS API call
✅ clientid must be valid WHMCS client
✅ paymentmethod must be valid WHMCS payment method
✅ pid[] must contain valid WHMCS product IDs
✅ billingcycle[] must match WHMCS billing cycles
✅ qty[] must be positive integers
Business Rule Validation
// Before provisioning
✅ Order.Status must be "Pending Review" or "Activating"
✅ Order must not already have WHMCS_Order_ID__c
✅ Client must have valid payment method in WHMCS
✅ All products must have WH_Product_ID__c mapping
📝 Implementation Notes
Array Handling
- WHMCS expects arrays: Use
pid[], billingcycle[], qty[] format
- Order matters: Arrays must be in same order (pid[0] matches billingcycle[0])
- Empty values: Use empty strings
"" for optional array elements
Serialization (Advanced)
// For configoptions[] and customfields[] if needed
function serializeForWhmcs(data: Record<string, string>): string {
const serialized = phpSerialize(data);
return Buffer.from(serialized).toString("base64");
}
// PHP serialize format: a:2:{s:3:"key";s:5:"value";}
Error Handling
// WHMCS API error responses
{
"result": "error",
"message": "Client ID Not Found"
}
// Map to structured error codes
WHMCS_CLIENT_NOT_FOUND → ORDER_NOT_FOUND
WHMCS_PRODUCT_INVALID → MAPPING_ERROR
WHMCS_API_ERROR → WHMCS_ERROR
This mapping reference ensures consistent data transformation and provides the complete picture for troubleshooting and maintenance.
7c929eb4dc