Skip to main content

Customer Subsidiary Relationship API

In OneWorld accounts, manage which subsidiaries a customer can transact with.

Endpoints​

MethodEndpointDescription
GET/record/v1/customerSubsidiaryRelationshipList relationships
GET/record/v1/customerSubsidiaryRelationship/{id}Get specific relationship
POST/record/v1/customerSubsidiaryRelationshipCreate relationship
PATCH/record/v1/customerSubsidiaryRelationship/{id}Update relationship
DELETE/record/v1/customerSubsidiaryRelationship/{id}Delete relationship

Base URL​

https://{account_id}.suitetalk.api.netsuite.com/services/rest/record/v1/customerSubsidiaryRelationship

Key Fields​

Core Fields​

FieldTypeDescriptionRequired
idstringInternal ID (read-only)-
entityobjectCustomer referenceYes
subsidiaryobjectSubsidiary referenceYes
isPrimarySubsidiarybooleanPrimary subsidiary flagNo

Financial Fields (Read-Only)​

FieldTypeDescription
balancenumberA/R balance in this subsidiary
depositBalancenumberDeposit balance
unbilledOrdersnumberUnbilled order total
overdueBalancenumberOverdue balance amount
consolBalancenumberConsolidated balance
consolDepositBalancenumberConsolidated deposit balance
consolUnbilledOrdersnumberConsolidated unbilled orders
consolOverdueBalancenumberConsolidated overdue balance

Tax & Pricing Fields​

FieldTypeDescription
taxRegistrationobjectTax registration for subsidiary
priceLevelobjectPrice level for this subsidiary
currencyobjectTransaction currency

Classification Fields​

FieldTypeDescription
classobjectClass for this subsidiary
departmentobjectDepartment for this subsidiary
locationobjectLocation for this subsidiary

Example: Create Subsidiary Relationship​

POST /record/v1/customerSubsidiaryRelationship
Content-Type: application/json
Authorization: Bearer {access_token}
{
  "entity": {
    "id": "456"
  },
  "subsidiary": {
    "id": "2"
  },
  "isPrimarySubsidiary": false,
  "priceLevel": {
    "id": "3"
  },
  "currency": {
    "id": "2"
  }
}

Response​

{
  "links": [
    {
      "rel": "self",
      "href": "https://1234567.suitetalk.api.netsuite.com/services/rest/record/v1/customerSubsidiaryRelationship/789"
    }
  ],
  "id": "789",
  "entity": {
    "id": "456",
    "refName": "Acme Corporation"
  },
  "subsidiary": {
    "id": "2",
    "refName": "Acme UK Ltd"
  },
  "isPrimarySubsidiary": false,
  "balance": 0,
  "depositBalance": 0,
  "unbilledOrders": 0,
  "currency": {
    "id": "2",
    "refName": "GBP"
  }
}

Example: Update Subsidiary Relationship​

PATCH /record/v1/customerSubsidiaryRelationship/789
Content-Type: application/json
Authorization: Bearer {access_token}
{
  "priceLevel": {
    "id": "5"
  },
  "class": {
    "id": "10"
  }
}

Response​

{
  "links": [
    {
      "rel": "self",
      "href": "https://1234567.suitetalk.api.netsuite.com/services/rest/record/v1/customerSubsidiaryRelationship/789"
    }
  ],
  "id": "789",
  "entity": {
    "id": "456",
    "refName": "Acme Corporation"
  },
  "subsidiary": {
    "id": "2",
    "refName": "Acme UK Ltd"
  },
  "priceLevel": {
    "id": "5",
    "refName": "Wholesale - UK"
  },
  "class": {
    "id": "10",
    "refName": "International"
  }
}

Query Filters​

Find All Relationships for a Customer​

GET /record/v1/customerSubsidiaryRelationship?q=entity='456'

Find All Customers for a Subsidiary​

GET /record/v1/customerSubsidiaryRelationship?q=subsidiary='2'

Find Primary Subsidiary Relationship​

GET /record/v1/customerSubsidiaryRelationship?q=entity='456' AND isPrimarySubsidiary=true

Find Relationships with Balance​

GET /record/v1/customerSubsidiaryRelationship?q=balance > 0

Find Relationships with Overdue Balance​

GET /record/v1/customerSubsidiaryRelationship?q=overdueBalance > 0

Common Use Cases​

1. Multi-Subsidiary Customer Setup​

Allow a customer to transact in multiple subsidiaries while maintaining separate balances:

// Customer's primary subsidiary (set on customer record)
await createCustomer({
  companyName: "Global Corp",
  subsidiary: { id: "1" }  // US subsidiary (primary)
});

// Add UK subsidiary relationship
await createCustomerSubsidiaryRelationship({
  entity: { id: "456" },
  subsidiary: { id: "2" },  // UK subsidiary
  currency: { id: "2" },    // GBP
  priceLevel: { id: "3" }   // UK pricing
});

// Add Germany subsidiary relationship
await createCustomerSubsidiaryRelationship({
  entity: { id: "456" },
  subsidiary: { id: "3" },  // Germany subsidiary
  currency: { id: "3" },    // EUR
  priceLevel: { id: "4" }   // EU pricing
});

2. Check Customer Balance by Subsidiary​

const relationships = await getCustomerSubsidiaryRelationships("entity='456'");

relationships.forEach(rel => {
  console.log(`${rel.subsidiary.refName}: ${rel.balance}`);
});

// Output:
// Acme US Inc: $50,000
// Acme UK Ltd: £25,000
// Acme DE GmbH: €30,000

3. Set Subsidiary-Specific Pricing​

// Different price levels for different subsidiaries
await patchCustomerSubsidiaryRelationship(usRelId, {
  priceLevel: { id: "1" }  // US Retail
});

await patchCustomerSubsidiaryRelationship(ukRelId, {
  priceLevel: { id: "2" }  // UK Wholesale
});

4. Subsidiary-Specific Classifications​

// Assign different departments/classes per subsidiary
await patchCustomerSubsidiaryRelationship(relId, {
  department: { id: "5" },   // International Sales
  class: { id: "10" },       // Enterprise
  location: { id: "3" }      // London Office
});

5. Tax Registration per Subsidiary​

// Set VAT registration for EU subsidiary
await patchCustomerSubsidiaryRelationship(euRelId, {
  taxRegistration: { id: "15" }  // EU VAT Registration
});

Important Notes​

OneWorld Only​

This record type only exists in NetSuite OneWorld accounts with multiple subsidiaries. If you're not using OneWorld, this endpoint will not be available.

Primary Subsidiary​

  • Each customer must have exactly one primary subsidiary
  • The primary subsidiary is set on the main customer record via the subsidiary field
  • Setting isPrimarySubsidiary=true on a relationship does NOT make it primary
  • To change the primary subsidiary, update the customer record directly

Required Fields​

  • entity: Customer reference is required
  • subsidiary: Subsidiary reference is required
  • The combination of entity + subsidiary must be unique

Read-Only Financial Fields​

All balance fields are calculated by NetSuite and cannot be set via API:

  • balance, depositBalance, unbilledOrders, overdueBalance
  • consolBalance, consolDepositBalance, consolUnbilledOrders, consolOverdueBalance

These fields are automatically updated when transactions are posted.

Consolidated Balances​

Fields prefixed with consol show balances in the parent subsidiary's currency after consolidation. Useful for reporting across subsidiaries.

Currency Handling​

  • Each subsidiary relationship can have its own currency
  • The currency should typically match the subsidiary's base currency
  • If not specified, defaults to the subsidiary's currency

Permissions​

  • Users can only create/view relationships for subsidiaries they have access to
  • Subsidiary restrictions apply based on user role permissions

Deleting Relationships​

  • Cannot delete the primary subsidiary relationship
  • Cannot delete if there are unpaid transactions in the subsidiary
  • Consider setting isInactive=true on the customer record for the subsidiary instead

Best Practices​

  • Create subsidiary relationships during customer onboarding
  • Set appropriate price levels per subsidiary/region
  • Use tax registrations for VAT/GST compliance
  • Monitor balances across subsidiaries for credit management
  • Apply consistent classification schemes across subsidiaries

Multi-Currency Considerations​

Currency per Subsidiary​

// US customer with international operations
const usRel = await createCustomerSubsidiaryRelationship({
  entity: { id: "456" },
  subsidiary: { id: "1" },  // US
  currency: { id: "1" }     // USD
});

const ukRel = await createCustomerSubsidiaryRelationship({
  entity: { id: "456" },
  subsidiary: { id: "2" },  // UK
  currency: { id: "2" }     // GBP
});

Consolidated Reporting​

Use consolBalance fields to see all balances in a common currency:

const relationships = await getCustomerSubsidiaryRelationships("entity='456'");

const totalConsolidated = relationships.reduce((sum, rel) => {
  return sum + rel.consolBalance;  // All in parent subsidiary currency
}, 0);

See Also​