Guides
App CenterSolution Provider PortalSupport
Start typing to search…

How to configure Ordering API for multi-legal entities

Multi-legal entities (MLE) refers to a business structure where a single company or organization operates through multiple legally distinct entities, such as corporations, limited liability companies (LLCs), subsidiaries, affiliates, or cost centers. When customers onboard to Amazon Business (AB), they can mimic their legal structures by configuring MLE and groups. AB orders will then be recorded against the appropriate legal entity.

Ordering API supports MLE by identifying legal entities in the request. For example, if your company is called ACME Corp and has two legal entities, ACME Finance Germany and Acme Analytik GmbH, the Ordering API request will include identifiers for the legal entities that will own the order. Each placed order will then be recorded against the appropriate entity.

❗️

Once MLE is configured for an Ordering API group, you cannot place an order for that group without identifying a legal entity or group in the request.

To enable MLE for Ordering API, follow these steps:

Prerequisites

Before configuring MLE, complete onboarding to Ordering API. For more information, see Developer partner onboarding.

Step 1. Configure your purchasing system

Configure a purchasing system for the master group. This configuration will then be extended to all legal entities under the group. To create this master group and configure a purchasing system, complete the steps in Customer onboarding.

Step 2. Choose your legal entity identifiers

Define the identifiers your organization will pass in the API request to identify legal entities. Ordering API identifies legal entities with an Auxiliary attribute type that contains key/value pairs.

The key is an object containing a value field. The name of the key can be any string defined by your organization for legal entities. The value must be a valid identifier type used to identify the entity. You can use the same key for multiple legal entities, but each value must be unique. Ordering API supports the following identifier types:

Identifier typeDescriptionSample keySample value
Legal entity nameName of the legal entity.AcmeCorpCostCenterCostCenter
Tax IDTax identifier.AcmeCorpTaxIdvatid14156352
Custom fieldUser-defined custom identifier.AcmeCorpMLEAcmeCorp123

For example, if you want to use custom fields to identify legal entities for ACME Corp, you may have the following values defined:

Legal EntityCustom field mapping
ACME Finance Germany146452
ACME Analytik GmbH146451
ACME Product Service GmbH146250

Here is how this would look in a payload for ACME Finance Germany, where the “key” is LegalEntity:

"attributes": [ 
         {
            "attributeType": "Auxiliary",
            "values": {
                 "LegalEntity": {
                     "value" : "146452"
                    }
                }
        },

You can also identify legal entities by Tax ID and legal entity name. Here are sample payloads for each:

 "attributes": [ 
         {
            "attributeType": "Auxiliary",
            "values": {
                 "LegalEntityName": {
                     "value" : "AcmeCostCenter"
                    }
                }
        },  
        

 "attributes": [ 
         {
            "attributeType": "Auxiliary",
            "values": {
                 "TaxId": {
                     "value" : "vatid14156352"
                    }
                }
        },

Step 3. Work with Amazon Business to configure your MLE setup

After determining how you will identify your legal entities, share your key/value pair(s) with your Amazon Business technical contact. Amazon Business will configure your backend MLE setup with your selected identifiers to record and identify each order. Your Amazon Business contact will confirm when MLE is configured for your group and you are able to proceed with placing orders via Ordering API.

For ACME Corp, for example, you would share the following key/value pairs with AB:

Legal EntityKeyCustom field mapping
ACME Finance GermanylegalEntityId146452
ACME Analytik GmbHlegalEntityId146451
ACME Product Service GmbHlegalEntityId146250

Step 4. Include auxiliary fields in API request

After backend configuration, include the auxiliary fields in each Ordering API request to identify the legal entity or group to record and identify an order. If you want to route an order to multiple legal entities, you can include several key/value pairs in a single request.

A successful request will record the order against the specified legal entity or entities. Here is a sample request where the Auxiliary attribute contains a key of LegalEntityName and a value of ACMECostCenter:

POST /ordering/2022-10-30/orders

{
    "externalId": "ExternalID-OrderLevel-IT-{{$randomPhoneNumber}}",
    "lineItems": [
        {
            "externalId": "LineLevel-1",
            "quantity": 1,
            "attributes": [
                {
                    "attributeType": "SelectedProductReference",
                    "productReference": {
                        "id": "B00CA31590",
                        "productReferenceType": "ProductIdentifier"
                    }
                }
            ],
            "expectations": [
                {
                    "expectationType": "ExpectedUnitPrice",
                    "amount": {
                        "currencyCode": "EUR",
                        "amount": 115
                    }
                },
                {
                    "expectationType": "ExpectedCharge",
                    "amount": {
                        "currencyCode": "EUR",
                        "amount": 10000
                    },
                    "source": "SUBTOTAL"
                }
            ]
        }
    ],
    "attributes": [
        {
            "attributeType": "Auxiliary",
            "values": {
                "LegalEntityName": {
                    "value": "ACMECostCenter"
                }
            }
        },
        {
            "attributeType": "PurchaseOrderNumber",
            "purchaseOrderNumber": "PO2"
        },
        {
            "attributeType": "BuyerReference",
            "userReference": {
                "userReferenceType": "UserEmail",
                "emailAddress": "example@amazon.com"
            }
        },
        {
            "attributeType": "BuyingGroupReference",
            "groupReference": {
                "groupReferenceType": "GroupIdentity",
                "identifier": "Leg5Grp1"
            }
        },
        {
            "attributeType": "Region",
            "region": "IT"
        },
        {
            "attributeType": "SelectedPaymentMethodReference",
            "paymentMethodReference": {
                "paymentMethodReferenceType": "StoredPaymentMethod"
            }
        },
        {
            "attributeType": "ShippingAddress",
            "address": {
                "addressType": "PhysicalAddress",
                "fullName": "Amazon Test Order- Return",
                "phoneNumber": "9898989898",
                "companyName": "companyName_amazoncompany",
                "addressLine1": "Viale Monte Grappa 3/5",
                "addressLine2": "",
                "city": "Milano",
                "stateOrRegion": "Milano",
                "postalCode": "28045",
                "countryCode": "IT"
            }
        },
        {
            "attributeType": "BillingAddress",
            "address": {
                "addressType": "PhysicalAddress",
                "fullName": "i2 IT test2",
                "phoneNumber": "4402075501000",
                "companyName": "",
                "addressLine1": "325 9th Ave N,",
                "addressLine2": "",
                "city": "Seattle",
                "stateOrRegion": "WA",
                "postalCode": "98109",
                "countryCode": "US"
            }
        }
    ],
    "expectations": [
        {
            "expectationType": "ExpectedCharge",
            "amount": {
                "currencyCode": "EUR",
                "amount": 20
            },
            "source": "SUBTOTAL"
        },
        {
            "expectationType": "ExpectedCharge",
            "amount": {
                "currencyCode": "EUR",
                "amount": 10
            },
            "source": "TAX"
        },
        {
            "expectationType": "ExpectedCharge",
            "amount": {
                "currencyCode": "EUR",
                "amount": 1
            },
            "source": "SHIPPING"
        }
    ]
}

Step 5. Place the order

Send your Ordering API request. Once an order is placed successfully, the order will appear in the “Your Orders” section of the AB website. Each order will be identified with the correct legal entity as specified in the API request.

🚧

If you need to remove MLE configurations from an ordering API group, work with your Amazon Business contact.

Updated 5 months ago

Did this page help you?