Salesforce B2C Commerce Storefront Order Data Map

These tables illustrate how data in a Salesforce B2C Commerce order packet maps to records in Salesforce Order Management. If you’re implementing your own storefront integration, this map can help you understand the order data requirements.

General:

• B2C Commerce sends orders in New or Open status to Salesforce Order Management. To delay sending an order, for example, to perform a fraud check, keep it in Created status.

• B2C Commerce sends order data to Salesforce Order Management according to a set frequency and when the packet of pending orders reaches a certain size. The process is similar to the one used for Commerce Cloud Order Management. In addition, the integration contacts B2C Commerce every 5 minutes to request any pending order data.

• The B2C Integration can’t create an order with a combined total of more than 200 OrderItems and OrderItemAdjustmentLineItems. For example, it can create an order with 150 OrderItems and 45 OrderItemAdjustmentLineItems, but can’t create an order with 110 OrderItems and 100 OrderItemAdjustmentLineItems. To import an order that exceeds this limit, use Bulk API 2.0. For information about manually importing orders into Order Management, see Importing Order Data.

• The integration associates sites in B2C Commerce with SalesChannels in Order Management. It identifies the SalesChannel for an order by searching for a SalesChannelName value that matches the site/site-id value in the order data.

• For details of the B2C Commerce order data format, see the Order XSD Schema in the B2C Commerce Infocenter.

• The B2C Integration service user is an internal Salesforce user. If you set internal organization-wide sharing defaults for any objects accessed by the integration, set them to Public Read/Write access.

  For information about organization-wide sharing defaults, see Organization-Wide Sharing Defaults in Salesforce Help.

  Note

• If the Salesforce org ID or login URL changes, or if you run DBInit on your B2C Commerce storefront, the integration requires updating. To reprovision the integration, open a case with Salesforce Customer Support as described in the Order Management Implementation Guide.

• If you refresh a sandbox org, or change the Tenant ID of a B2C Commerce instance, repeat the implementation process as described in the Order Management Implementation Guide. For information on sandbox orgs, see the sandbox topics in Salesforce Help.

• To deactivate the integration, open a case with Salesforce Support.

• To stop sending orders from a site, log in to Business Manager, navigate to Merchant Tools | Site Preferences | Order, and turn off the Include in Order Management setting.

Shopper Accounts:

• When the order/billing-address/company-name value in the order data is not null, Order Management always uses a standard account and contact to represent the shopper.

• If you enable Person Accounts, don’t change the names or API names of the two default Account record types. The B2C Integration uses those types to represent shopper accounts.

• You can configure the integration to identify existing shoppers by applying your org’s duplicate and matching rules for Accounts, Contacts, and Person Accounts. To enable this feature, in Setup, in Order Management Settings, turn on B2C Integration Data Matching Rules. For more information on configuring duplicate management, see Manage Duplicate Records in Salesforce Help.

  If your org’s matching rules identify multiple potential duplicate records, the integration selects the one with the highest match score. If multiple records tie for the highest match score, you can’t guarantee which is selected.

  Note

  Applying complex custom matching rules can affect the integration’s performance.

  Note

• The integration can’t look up any encrypted fields on Salesforce objects. Encrypting any of the fields it uses to look up records causes order ingestion to fail. If you want to encrypt the Account.Name, Account.PersonEmail, or Contact.Email field, then you must implement custom duplicate and matching rules that don’t use any encrypted fields. For more information on encryption restrictions, see General Shield Platform Encryption Considerations in Salesforce Help.

• For detailed information on the storage and identification of shopper accounts, see Order Management Shopper Records in Salesforce Order Management in Salesforce Help.

International Considerations

• If the order/taxation value for an order is net, then the integration creates an OrderItemTaxLineItem record for each OrderItem and OrderItemAdjustmentLineItem record.

• If Salesforce state and country/territory picklists aren’t enabled:

  • The state-code values in order data must match a standard 2-character ISO state or province code. The integration copies them to State fields on Salesforce records.
  • The country-code values in order data must match a standard 2-character ISO country/territory code. The integration copies them to Country fields on Salesforce records.

• If Salesforce state and country/territory picklists are enabled:

  • The state-code values in order data must match the state code of an entry in the Salesforce state picklist. The integration copies them to StateCode fields on Salesforce records. The corresponding State fields are set to the matching integration values from the picklist.
  • The country-code values in order data must match the country/territory code of an entry in the Salesforce country/territory picklist. The integration copies them to CountryCode fields on Salesforce records. The corresponding Country fields are set to the matching integration values from the picklist.

Payments

• Order data includes a paired payment instrument and payment transaction for each payment associated with the order.

• If an order/payments/payment/transaction-type value in the order data starts with auth, then the integration creates a PaymentAuthorization record for that transaction. If the value is sale or capture, then it creates a Payment record. These checks aren’t case-sensitive.

• For a credit or debit card payment type, the payments/payment/credit-card/card-type value in the order data must match a value in the CardType picklist on the CardPaymentMethod object.

• To handle a payment method that doesn’t match a CardPaymentMethod CardType or DigitalWallet Type, create a custom payment method as described later in this section.

• If you use Salesforce Payments, the integration sets different values for some of the fields on AlternativePaymentMethod, CardPaymentMethod, and DigitalWallet. The details are described in the map tables.

• The integration recognizes certain custom attributes on order/payments/payment and copies them to standard fields on the PaymentGatewayLog record in Salesforce. To take advantage of this feature, create and populate custom attributes with the following exact names on the Order Payment Transaction object in B2C Commerce:

  • authCode (value copied to PaymentGatewayLog.GatewayAuthCode)
  • avsResultCode (value copied to PaymentGatewayLog.GatewayAvsCode)
  • approvalStatus (value copied to PaymentGatewayLog.GatewayResultCode)

• The integration can copy other custom attributes on order/payments/payment to standard fields on AlternativePaymentMethod, CardPaymentMethod, DigitalWallet, Payment, and PaymentAuthorization records in Salesforce.

• An OrderPaymentSummary for a B2C Commerce order only has a FullName value if the payment method is a credit card. Other payment methods don’t include the data value that the integration uses to set the FullName.

Promotions

• The integration creates an OrderAdjustmentGroup record for each order-level price-adjustments/price-adjustment/promotion-id and for each item-level price-adjustments/price-adjustment/promotion-id that applies to more than one item in the order. For each OrderAdjustmentGroup, it creates an OrderItemAdjustmentLineItem record for each OrderItem in the order that the associated promotion applies to. If an OrderItem is affected by multiple promotions, then it can have an OrderItemAdjustmentLineItem for each one.
• If the order/taxation value for an order is net, then the integration creates an OrderItemTaxLineItem record for each OrderItemAdjustmentLineItem record.

For information on the Salesforce state and country/territory picklists, see Let Users Select State and Country from Picklists in Salesforce Help.

Configure a payment gateway adapter for each merchant account. If you use multiple currencies or payment methods through a single payment processor, you can optionally set up multiple payment gateways for that processor. By default, the Order Management integration with Salesforce B2C Commerce only supports credit card and digital wallet payment types, but you can create your own customizations.

You can use Apex and the Connect REST API to set up payment gateways. See commercepayments namespace and Use Cases for the commercepayments Namespace in the Apex Developer Guide, and Commerce Payments Resources in the Connect REST API Developer Guide.

The B2C Commerce integration processes each storefront payment method in the order data as follows:

1. Does the payment method ID in the order data match the following non-case-sensitive regular expression? If so, then create a DigitalWallet record in Salesforce.

   1paypal|visa_checkout|pay_by_check|.*(apple|google|android|amazon|ali).*(pay)*

2. Does the payment method ID in the order data match the Gateway Provider Payment Method Type of a GtwyProvPaymentMethodType record in Salesforce? If so, then create a record in Salesforce according to the GtwyProvPaymentMethodType’s Payment Method Type.

3. Does the card type in the order data match an entry in the Card Type picklist on the CardPaymentMethod object in Salesforce? If so, then create a CardPaymentMethod record in Salesforce.

   You can’t customize the Card Type picklist.

   Note

4. Return an error message that the payment method isn’t supported.

To support a different payment type, set up a custom payment method as described in the next section.

If you use a storefront payment method that meets both of the following criteria, configure a custom payment method for it.

• The default regular expression doesn’t identify it as a DigitalWallet method.
• It doesn’t match any of the standard card types for a CardPaymentMethod.

To configure a custom payment method as an AlternativePaymentMethod, first create a RecordType for the AlternativePaymentMethod object. Give the record type a name that represents the payment method. For information on creating record types, see Create Record Types in Salesforce Help.

Define a custom payment method by creating a GtwyProvPaymentMethodType (Gateway Provider Payment Method Type) record. The gateway provider payment method type associates the custom payment method with a payment gateway and defines it as an AlternativePaymentMethod, CardPaymentMethod, or DigitalWallet.

Set the GtwyProvPaymentMethodType fields as described here.

Comments: Optional description.

Developer Name: The unique API name of the record.

Master Label: A human-readable name for the record.

Gateway Provider Payment Method Type

The name of the payment method in the storefront. This value must exactly match the payment method ID used in B2C Commerce.

Payment Gateway Provider Id: Reference to the Payment Gateway Provider record associated with the payment processor for the payment method.

Payment Method Type

AlternativePaymentMethod CardPaymentMethod, or DigitalWallet. To use AlternativePaymentMethod, first create a corresponding RecordType record.

Record Type Id: If using an AlternativePaymentMethod, this value is a reference to the RecordType record.

Here’s an example of a gateway provider payment method definition:

1{
2  "DeveloperName" : "BankTransfer"
3  "MasterLabel" : "Bank Transfer",
4  "GtwyProviderPaymentMethodType" : "directBanking",
5  "PaymentGatewayProviderId" : "0cJaa0000000001E67",
6  "PaymentMethodType" : "AlternativePaymentMethod",
7  “RecordTypeId” : "012aa000000008A34F"
8}

The integration can pass custom data on certain B2C Commerce objects to Order Management. To set up the transfer, add custom attributes to objects in B2C Commerce, and add matching custom fields to the corresponding objects in Order Management. The integration compares the B2C Commerce attribute ID and the Order Management field name at the API level. (It doesn’t consider their UI labels.) If they match and the data types match, the integration includes those values when it creates Order Management records. If you also create a matching field on the corresponding summary object, Order Management includes the custom data when it creates a summary record.

You can add custom attributes to product options that exist as product line items, but not to product options that exist as attributes on parent products. You can’t add an attribute to an attribute.

If you add a custom field to an object used in a flow, customize the flow to handle it.

If order data includes a custom attribute value, but the corresponding Salesforce object has no matching custom field, the integration ignores that attribute. If a custom field exists in Salesforce, and order data doesn’t include a matching custom attribute value, the integration ignores it.

You can support product bundles by passing that information as custom data. To set up product bundle associations, define a custom guid attribute for the line item object in your storefront. In Salesforce, define a matching field on OrderItem and OrderItemSummary. When creating an order, assign the same value to the custom attribute on line items that belong together. You can define another custom attribute to identify a line item as part of a bundle. Then build logic into your fulfillment process to handle them accordingly.

You can match custom attributes and fields on these sets of objects. For High-Scale Order Integration (HSOI), custom fields are only necessary on the summary objects. HSOI directly maps to these fields. When using HSOI, don’t add custom fields to standard objects. Setup is streamlined by keeping custom fields in a single location.

The integration supports the following data types for matching custom attributes and fields:

• Boolean
• Currency
• Datetime (Date isn’t supported)
• Double
• Email
• Multipicklist
• Phone
• Picklist
• String
• TextArea
• URL

The Order Management B2C Service permission set provides the integration with access to Salesforce records. When you add a custom field to a Salesforce object, update that permission set by adding read and edit access to the new field. You also must add edit access to the permission set that provides access for your Order Management users.

1. From Setup, in the Quick Find box, enter Permission Sets, and then select Permission Sets.
2. Select Order Management B2C Service.
3. In the Apps section, click Object Settings.
4. Select the object that has the custom field.
5. Click Edit.
6. In the Field Permissions section, select the Edit Access checkbox for the custom field.
7. Click Save.
8. Return to the list of permission sets by selecting Permission Sets in the Setup navigation menu.
9. Select the permission set that controls access for your Order Management users. Normally, it’s called OM Console.
10. In the Apps section, click Object Settings.
11. Select the object that has the custom field.
12. Click Edit.
13. In the Field Permissions section, select the Edit Access checkbox for the custom field.
14. Click Save.

Sync the order data map in Salesforce Order Management with your B2C Commerce org, for example after adding new custom attributes. Trigger the data map refresh to instantly access new schema changes instead of waiting for the next scheduled sync.

1. Click App Launcher, and then select Administration | Global Preferences | Salesforce Order Management Configuration.
2. Click Refresh Data Map.
3. Save your changes.

Order Management always uses standard accounts to represent shoppers that have company names. If an order includes an order/billing-address/company-name value, and no matching account record exists, then the integration creates a standard account, regardless of the Person Accounts for Shoppers setting.

Changing the Person Accounts for Shoppers admin setting doesn’t affect existing shopper data. However, it changes the way that the B2C Commerce integration stores new shopper data and whether it recognizes existing shopper data.

• While Order Management is configured to use standard accounts: the integration recognizes existing shoppers that are stored as person accounts. It associates their new orders with their existing person accounts. If an existing shopper has records of both types, it associates new orders with their standard account and contact.
• While Order Management is configured to use person accounts: the integration doesn’t recognize existing shoppers that are stored as standard accounts and contacts. If one of those shoppers places an order, the integration creates a person account record for them and associates the new order with it. Order Management treats the accounts as separate shoppers. If an existing shopper has records of both types, the integration associates new orders with their person account.

The integration checks the payment_method value of each payment instrument in an order. If it matches the Gateway Provider Payment Method Type of a GtwyProvPaymentMethodType record, then the integration creates a record according to the GtwyProvPaymentMethodType’s Payment Method Type value. If the Payment Method Type is AlternativePaymentMethod, then the integration creates an AlternativePaymentMethod record using the associated RecordType.

The integration checks the payment_method value of each payment instrument in an order against the following regex. If it matches, then the integration creates a DigitalWallet record for the instrument. If it doesn’t match, then the integration checks the payment/credit-card/card-type value against the CardType picklist on the CardPaymentMethod object. If the picklist contains a match, then the integration creates a CardPaymentMethod record for the instrument. Otherwise, to support the payment method, you must set up a custom payment method for it.

1paypal|visa_checkout|pay_by_check|.*(apple|google|android|amazon|ali).*(pay)*

When using person accounts, access shopper contact data using person account records, not contact records. When using standard accounts and contacts, the BillToContactId field on these objects points to the associated contact record:

• Credit Memo
• Fulfillment Order
• Invoice
• Order
• Order Summary

The integration checks the payment_method value of each payment instrument in an order. If it matches the following regex, then the integration creates a DigitalWallet record for the instrument. If it doesn’t match, then the integration tries to create an AlternativePaymentMethod or a CardPaymentMethod record for the instrument.

1paypal|visa_checkout|pay_by_check|.(apple|google|android|amazon|ali).(pay)*

The integration uses both the order/order-no and catalog/catalog-id values to check for duplicate orders. It looks for an existing order record with an OrderReferenceNumber matching the order-no and a SalesChannelId pointing to a SalesChannel that matches the catalog-id. If it finds one, it doesn’t create a duplicate order.

The integration creates one OrderAdjustmentGroup record for each promotion that applies to an entire order or to multiple items in an order. For an order-level promotion, it assigns the OrderAdjustmentGroup to one OrderItemAdjustmentLineItem record for each OrderItem record in the order. It creates the OrderAdjustmentGroup even if the order only contains one OrderItem. For an item-level promotion that applies to multiple OrderItems, it assigns the OrderAdjustmentGroup to one OrderItemAdjustmentLineItem record for each OrderItem record in the Order that the promotion applies to. If an item-level promotion only applies to one OrderItem, the integration doesn’t create an OrderAdjustmentGroup for it.

The integration creates an OrderDeliveryGroup record for each shipment (also called a LineItemGroup in B2C Commerce) in the order data.

For order changes such as returns and cancellations that include prorated delivery amounts, the proration considers the OrderDeliveryGroups containing OrderItems that are part of the change. For example, consider an order that has three OrderDeliveryGroups, each with multiple OrderItems. A return of two OrderItems, each from a different OrderDeliveryGroup, uses the total delivery charges associated with those two OrderDeliveryGroups. It prorates that amount across the OrderItems in those OrderDeliveryGroups by OrderItem price. The shipping refund equals the prorated delivery amounts for the two returned OrderItems. The return doesn’t consider any delivery charges associated with the third OrderDeliveryGroup.

If an order has a TaxLocaleType of Net, then the integration also creates an OrderItemTaxLineItem record for each OrderItem record.

An OrderItemAdjustmentLineItem record represents the application of a promotion to an OrderItem record. Thus, an OrderItem record has one associated OrderItemAdjustmentLineItem record for each promotion that applies to it.

If an order has a TaxLocaleType of Net, then the integration also creates an OrderItemTaxLineItem record for each OrderItemAdjustmentLineItem record.

If an order has a TaxLocaleType of Net, then the integration creates an OrderItemTaxLineItem record for each OrderItem and OrderItemAdjustmentLineItem record in the order. If an order has a TaxLocaleType of Gross, then the integration doesn’t create any OrderItemTaxLineItem records for it.

If an order/payments/payment/transaction-type value in the order data is sale or capture, then the integration creates a Payment record for that transaction. If the value starts with auth, then it creates a PaymentAuthorization record. These checks aren’t case-sensitive.

If an order/payments/payment/transaction-type value in the order data starts with auth, then the integration creates a PaymentAuthorization record for that transaction. If the value is sale or capture, then it creates a Payment record. These checks aren’t case-sensitive.

PendingOrderSummary is only used by High Scale Orders. It holds order data that’s been ingested into ZOS and is waiting for its Salesforce records to be created. You can trigger creation of the records, including the Summary records, by importing a PendingOrderSummary from the Pending Order Summaries page in the Salesforce UI.

Salesforce Order Management doesn’t use the PricebookEntry object. It creates a PriceBookEntry record for each Product2 because the OrderItem object requires a PricebookEntryId value.

The integration identifies products by first searching for a Product2 with a ProductCode value that matches the product-id value in the order data. If it doesn’t find one, it looks for a Product2 with a StockKeepingUnit value that matches the product-id value. If it still doesn’t find one, then it creates a Product2 record.

For information on the Promotion object, see the Loyalty Management Developer Guide.

The integration associates B2C Commerce site IDs with Salesforce SalesChannels.

The integration looks for a WebStore matching the currency and locale of the order, and creates one if needed. It associates one WebStore with each combination of currency and locale that appears in order data. For example, let’s say that you have one site that supports US orders in US dollars. A second site supports UK orders in pounds or Euros, and also supports French orders in Euros. Create four Web Stores to represent them:

• USD - en_US
• GBP - en_GB
• EUR - en_GB
• EUR - fr_FR

j

Salesforce Order Management Developer Guide

Order Management Developer Resources

Order Summary Entity Relationships

Salesforce B2C Commerce Storefront Order Data Map

Importing Order Data

Fulfillment Orders

Taxation in Order Management

API Framework for Exchanges with RMA Returns

Change Order Summary API

Payment Sequencing

Salesforce Order Management Lightning Components

Order on Behalf Of for External Payments

Expand Data Sources for Return Insights

API End-of-Life Policy

Previous Versions