The Seller API, also called v2/REST API, is our seller-centric API, and as such you cannot (by default) use it to access any objects or attributes that do not reside in the "Seller Domain". A key example of this is the Order object and its attributes.
This article describes an exception to this rule, by allowing the Marketplacer Operator to permit the Seller API to return specific Order External IDs associated with Invoices.
Review of Order / Invoice Hierarchy
Review
- Orders are a Marketplacer-level concept (and as such are not usually available to the Seller). Orders can have one or more Invoices.
- Invoices: This is the Seller's "view" of their part of the order.
External IDs?
Many customers integrating into Marketplacer wish to additionally add "their" IDs to objects within Marketplacer, examples of the objects you can add External IDs to are:
- Orders
- Invoices
- Line Items
This is because often customers do not want to work with the Marketplacer-generated IDs, and instead prefer to use their IDs as a central point of reference. This is especially true in Connected integrations where the order may be created in another platform with another system-generated ID (for example, Salesforce Commerce Cloud, Commerce Tools, etc.) that the customer prefers to use moving forward.
If a customer chooses to use "External IDs" at the Order level, they can make those IDs available to Sellers on the Invoice when the Seller is retrieving Invoice details through the Seller API.
The rest of this article details what the Operator needs to do to allow the External ID payload to be made visible through the Seller API Invoice endpoint.
Anatomy of an "External ID"
An external ID is made up of:
- Key: This identifies what "type" of ID you have. You may have multiple types of External ID. For instance, one for each system participating in the transaction: Salesforce_ID, Oracle_ID etc.
- Value: This is the actual external ID value
Ultimately the key + value should be unique. For example:
- Key: SalesforceCC_ID
- Value: ABDD12345
Expose External IDs
As the Marketplacer Operator:
- Login to the Operator Portal with Administrator privileges.
- Go to Configuration > Seller Settings.
- Scroll down to Seller Invoices Spreadsheet Download.
Here you can add the External Id "Keys" that you want to expose to sellers.
Example
The Operator may attach the following external IDs to all its orders:
- The Salesforce Commerce Cloud Order ID (SalesforceCC_ID)
- The Customer ID from their Microsoft Dynamics CRM (Customer_ID)
The Operator can expose the Salesforce Commerce Cloud ID to the Sellers because they do not need it or have not used it) but want to expose the Customer ID. In this case, they would add the Customer_ID to the "Order external IDs to include" fields:
Once they are finished with changes, click "Submit" to save the changes applied.
Retrieving External IDs through the Seller API
Instructions for using the Seller API are outside the scope of this document. Full documentation on how to use the Invoices endpoint, including returning Order External IDs, can be found in our API documentation.
Related articles