Copy the link to the article Copied Checklist before enabling corporate customers Copy the link to the article Copied

Contents

1. Before activation
2. Automation rules
3. API integrations
4. API examples

Before activation

Corporate customers are enabled by default for new accounts on plans that include the feature. Older accounts may use compatibility mode if company or banking details were already stored in regular customer cards when the feature was introduced. In compatibility mode, those details continue to use the previous data structure until corporate customers are enabled manually.

Before activation:

• complete the migration review described in Corporate customer settings;
• check that every API-created order has a business type compatible with the linked customer—for example, an order marked as Individual must not be linked to a customer whose business type is Company;
• update integrations and automation rules as described below;
• plan how to correct in-progress orders that could become inconsistent after migration.

Automation rules

After corporate customers are enabled, order.customer can contain either a regular customer or a corporate customer. Orders can also contain order.contact and order.company.

Review every order-change rule that reads data from order.customer:

• If the rule must run only for regular customers, add the condition order.customer.typeCode == 'customer'.
• If it must also support corporate orders, update the rule to handle the different fields available for regular and corporate customers.

API integrations

API versions earlier than v5 do not support corporate customers. Regular customers use /api/v5/customers/*; corporate customers use /api/v5/customers-corporate/*.

A corporate customer contains three related object sets:

• Contacts — links between the corporate customer and regular customer records used as contact people. Each link can specify which companies the contact represents.
• Companies — companies within the corporate customer, including their registration, tax and banking details.
• Addresses — addresses that belong to the corporate customer.

Create a corporate customer

Create contact people first with /api/v5/customers/create or a suitable batch method. Then create the corporate customer with /api/v5/customers-corporate/create, or use /api/v5/customers-corporate/upload for batch upload.

Pass contact links in customerCorporate[customerContacts]. Pass the company’s country-specific business details in customerCorporate[companies][][contragent].

You can also create a corporate customer together with an order through /api/v5/orders/create. In that flow, a new contact person can be created with the order.

Edit related data

Use /api/v5/customers-corporate/{externalId}/edit for the corporate customer’s main profile.

Use the object-specific methods for related records:

• create a contact link: /api/v5/customers-corporate/{externalId}/contacts/create;
• edit a contact link: /api/v5/customers-corporate/{externalId}/contacts/{entityExternalId}/edit;
• create a company: /api/v5/customers-corporate/{externalId}/companies/create;
• edit a company: /api/v5/customers-corporate/{externalId}/companies/{entityExternalId}/edit;
• create an address: /api/v5/customers-corporate/{externalId}/addresses/create;
• edit an address: /api/v5/customers-corporate/{externalId}/addresses/{entityExternalId}/edit.

For entityExternalId, pass the related object’s externalId, or its id when the request includes entityBy=id.

Work with orders

Order creation for regular customers does not change. For a corporate customer, pass customer_corporate in order[customer][type].

For an existing corporate customer, also pass order[customer][id], order[customer][externalId] or order[customer][browserId]. To create a new corporate customer with the order, pass its name in order[customer][nickName].

Pass the contact person in order[contact]. If no contact data is provided, Simla creates a regular customer and links it as a contact of the corporate customer selected in the order.

You can optionally pass the company in order[company]. If a company is provided and order[contragent] is omitted, the order uses the company’s business details.

Synchronization

• Send company registration, tax and banking data through /api/v5/customers-corporate/{externalId}/companies/{entityExternalId}/edit.
• Send personal data for a contact through /api/v5/customers/{externalId}/edit.
• Send corporate addresses through /api/v5/customers-corporate/{externalId}/addresses/{entityExternalId}/edit.
• Send profile-level data, such as the name, discount and important/problem-customer flags, through /api/v5/customers-corporate/{externalId}/edit.
• For reverse synchronization, read corporate changes from /api/v5/customers-corporate/history. It includes profile, company, address, and contact-to-company relationship changes.
• Track changes to contact people through /api/v5/customers/history, and find the related corporate customer with filter[contactIds][] in /api/v5/customers-corporate.
• When synchronizing orders, allow order[customer] to contain either a regular or corporate customer.

API examples

Create a corporate customer with related objects

{
  "externalId": "corp_3144",
  "nickName": "Northwind Europe",
  "site": "main",
  "addresses": [
    {
      "index": "75002",
      "city": "Paris",
      "text": "16 Main Street, 2nd floor",
      "countryIso": "FR",
      "externalId": "corp_3144_fr"
    },
    {
      "index": "28001",
      "city": "Madrid",
      "text": "Calle de Alcalá 26, office 115",
      "countryIso": "ES",
      "externalId": "corp_3144_es"
    }
  ],
  "companies": [
    {
      "isMain": true,
      "externalId": "corp_3144_company",
      "active": true,
      "name": "Northwind Europe",
      "address": {
        "externalId": "corp_3144_es"
      }
    }
  ],
  "customerContacts": [
    {
      "customer": {
        "isMain": true,
        "externalId": "existing_contact_425",
        "site": "main"
      },
      "companies": [
        {
          "company": {
            "externalId": "corp_3144_company"
          }
        }
      ]
    }
  ]
}

Create an order with a new corporate customer

{
  "externalId": "order_3144",
  "firstName": "Alex",
  "lastName": "Morgan",
  "customer": {
    "type": "customer_corporate",
    "nickName": "Northwind Europe"
  }
}

Create an order for an existing corporate customer

{
  "externalId": "order_3145",
  "customer": {
    "type": "customer_corporate",
    "site": "main",
    "externalId": "corp_3144"
  },
  "contact": {
    "id": 34457
  },
  "company": {
    "externalId": "corp_3144_company"
  }
}