This guide is for Salesforce admins and consultants who need to configure how buyers provide shipping addresses during checkout. It explains both supported address approaches, how shipment fields are rendered, and how shipping address data affects delivery logic and VAT calculation.
Before you start
Confirm which buyer experience you want to support:
- Controlled selection from approved Address records
- Flexible address entry directly on the shipment
- Either option with additional shipment fields
Also confirm which shipment fields are required for shipping calculation, delivery selection, fulfillment, and tax.
Configuration model at a glance
OrderCentral uses different configuration layers for shipping addresses:
- Address records control the selectable-address experience
- Checkout Shipping Field custom metadata controls which shipment fields appear in the form
- Delivery Method and Site scoping can limit which fields appear in specific storefronts or for specific delivery methods
- Shipment field values can be prefilled based on predefined values, default addresses, prior shipments, or Account fields
In the default tax calculation, shipment Shipping Country and Shipping State determine which VAT rule is applied.
Option 1: Configure fixed Address records
Use this option when buyers should select from approved Address records instead of typing a shipping address during checkout.
What enables this experience
The address selector becomes relevant when:
- The buyer has read access to Address records
- The buyer's account has at least one active shipping address
When these conditions are met, the shipment shipping address is shown in read-only mode and the buyer can change it through the address selection flow.
Configure the Address records
- Create or maintain Address records related to the customer account.
- Set Type to Shipping.
- Set Active to true for addresses buyers are allowed to use.
- Mark one address as default if you want it prioritized.
- Populate the standard address values shown in the table below.
- Give buyers the correct object and field permissions based on whether they should only select addresses or also maintain them.
| Address field | Notes |
|---|---|
| Street | Required for a complete shipping address. |
| City | Required for a complete shipping address. |
| Postal Code | Required for delivery and tax accuracy. |
| Country Code | Must match a valid configured country value. |
| State Code | Use when the country requires state or province values. |
How selectable addresses are filtered
Only addresses that meet all of the following conditions are selectable:
- Related to the buyer's account
- Active
- Type = Shipping
Addresses marked as default are prioritized first.
What happens when a buyer selects an address
When the buyer selects an address, OrderCentral copies the selected values onto the shipment.
| Shipment field | Result |
|---|---|
| Address To | Stores the selected Address record. |
| Shipping Street | Stores the selected street value on the shipment. |
| Shipping City | Stores the selected city value on the shipment. |
| Shipping Postal Code | Stores the selected postal code on the shipment. |
| Shipping Country | Stores the selected country value on the shipment. |
| Shipping State | Stores the selected state value on the shipment when applicable. |
This keeps downstream delivery and fulfillment logic working from the shipment, not only from the Address record.
Because the default tax calculation uses shipment Shipping Country and Shipping State, VAT can also change when the selected address changes.
Recommended use cases
Use fixed Address records when:
- Customers order repeatedly to known locations
- Delivery locations need approval or governance
- Buyers should not enter arbitrary shipping addresses
Option 2: Configure editable shipment address fields
Use this option when buyers should type their shipment address directly during checkout.
What controls the form
Editable shipping fields are controlled by Checkout Shipping Field custom metadata records. Each record identifies a Shipment field to show in the checkout shipping form and defines how that field behaves.
Supported field behavior
| Setting | What it does |
|---|---|
| Shipment Field | Identifies the Shipment field shown in checkout. Only Shipment fields are supported. |
| Order | Controls the display sequence in the shipping form. |
| Hide | Excludes the field from the form. |
| Read Only | Shows the field without allowing buyers to edit it. |
| Required | Requires the buyer to complete the field before proceeding. |
| Predefined Value | Provides a fixed value for the field. This has the highest prefill priority. |
| Prepopulated Account Field | Copies a value from an Account field into the Shipment field when the data types are compatible. |
| Site Id | Limits the field to a specific Experience Cloud site. Leave blank to use it across sites. |
| Delivery Method | Limits the field to a specific delivery method. Leave blank to use it for all delivery methods. |
| Prefill from previous shipment | Reuses the buyer's most recent shipment value when no higher-priority value is available. |
Value precedence for prefilled shipment fields
When shipment values are prepared, OrderCentral applies value sources in this order.
| Priority | Source | Notes |
|---|---|---|
| 1 | Predefined value | Always takes precedence when configured. |
| 2 | Default shipping address | Applies to the core shipping address fields. |
| 3 | Most recent shipment value | Used only when prefill from previous shipment is enabled. |
| 4 | Mapped Account field value | Used when a compatible Account-to-Shipment field mapping is configured. |
This matters when more than one configuration source could populate the same shipment field.
Core shipping address fields
These are the main address fields used by checkout.
| Shipment field | Why it matters |
|---|---|
| Shipping Street | Required for the shipment delivery address. |
| Shipping City | Required for the shipment delivery address. |
| Shipping Postal Code | Used for delivery and tax accuracy. |
| Shipping Country | Used for delivery logic and VAT rule selection. |
| Shipping State | Used for delivery logic and VAT rule selection when applicable. |
If you configure these fields in Checkout Shipping Field metadata, they become part of the editable shipping form when buyers are not using the fixed-address approach.
In the default tax calculation, Shipping Country and Shipping State directly determine which VAT rule is selected.
Country and state configuration guidance
Country and state values must match valid configured values in the org.
| Behavior | What to expect |
|---|---|
| Country selection | Country is selected from available country options. |
| State visibility | State is shown only for countries that have state values. |
| Invalid configured value | If a predefined shipment country or state does not match a valid option, the buyer sees an error message. |
| State requirement | State is not required when the selected country has no states. |
These values are also important for VAT calculation because the default tax calculator selects the VAT rule from shipment Shipping Country and Shipping State.
For best results:
- Use valid country codes or labels supported by your org
- Use valid state codes for countries that require states
- Avoid free-text values that do not match configured country and state options
Add additional shipment fields
You can add extra Shipment fields beyond the standard address.
Examples:
- Delivery instructions
- Reference number
- Contact name
- Internal shipping note
To add an additional shipment field:
- Create the field on Shipment if it does not already exist.
- Create a Checkout Shipping Field record for that Shipment field.
- Set the desired order, required flag, read-only flag, and any scoping rules.
- Save the metadata record.
These fields appear in the shipping form alongside the address fields.
Important limitation:
Only Shipment fields are rendered in this shipping form configuration. Non-shipment fields are ignored.
Scope fields by storefront or delivery method
Use scoping to tailor shipment inputs to a storefront or logistics scenario.
| Scope option | Use it when | Result |
|---|---|---|
| Site Id | A field should appear only in one Experience Cloud storefront. | The field is shown only in that site. |
| Delivery Method | A field should appear only for one shipping method, such as freight or pickup. | The field is shown only for that delivery method. |
| Site Id and Delivery Method | A field should be shown only in a specific storefront and for a specific delivery method. | The field is shown only when both conditions match. |
Field validation and compatibility
Not every field type is suitable for checkout shipping field configuration.
The supported Shipment field types include common checkout-safe types such as:
- Text
- Text Area
- Phone
- Picklist
- Number
- Date
- Date/Time
- Currency
- Checkbox
- Percent
Formula fields should not be used.
If you map an Account field into a Shipment field, the source and target data types must match or be compatible.
Recommended setup patterns
Pattern 1: Controlled shipping addresses
Use:
- Address records with Type = Shipping
- Active addresses only
- Buyer read access to Address
- Minimal editable shipment fields for extra instructions only
Best for:
- B2B buyers using approved delivery locations
Pattern 2: Flexible shipment entry
Use:
- No selectable-address process for buyers
- Checkout Shipping Field records for the five core address fields
- Required validation on essential address fields
- Additional shipment fields only where needed
Best for:
- Businesses with many one-off shipment destinations
Pattern 3: Controlled addresses plus extra shipment data
Use:
- Fixed Address record selection
- Additional Checkout Shipping Field records for shipment-specific information
Best for:
- Businesses that want approved delivery locations but still need extra data per shipment
Troubleshooting
Address selector does not appear
- Check that the buyer can read the Address object
- Check that the account has at least one active Address record with Type = Shipping
Selected address updates the shipment address but not the selector context
- Confirm Address To is being set on the shipment as part of the address selection flow
Field does not appear in the shipping form
- Confirm the field is on Shipment
- Confirm the Checkout Shipping Field record is not hidden
- Confirm the Site Id and Delivery Method filters match the current checkout context
Prefill is not happening
- Check whether Prefill is enabled
- Check whether a more specific source such as Predefined Value is taking precedence
- Check whether there is a prior shipment value available
Country or state shows an error
- Confirm the configured country and state values match valid options in the org
Shipping options do not react as expected after address edits
- Remember that OrderCentral treats the five core address fields as the shipping address that can affect delivery logic
- Changing only additional shipment fields does not count as a shipping address change
VAT amount looks incorrect after an address change
- Confirm the shipment Shipping Country and Shipping State values
- Confirm there is an active VAT rule for that country and state, or a country-level fallback rule