• Last edited on: 18 April 2019

Custom Field Namespace

All new custom-fields are added to a custom-field namespace  to avoid name conflicts and to make customer-added fields more easily identifiable.


Before Coupa 21, any custom fields that you added were included in the API global namespace (off the root element). This made it difficult to identify which fields are standard to Coupa, and which (if any) were added by the customer. Now, new custom fields are added to a <custom-fields> parent element.

How it works

We're not changing any of your existing custom fields or how you add custom fields, but any new custom fields you create will be wrapped (API) when you see them in the API.

In the UI

When you edit a custom field that was added before R21, you'll see that the API Global Namespace checkbox is selected. This means the custom field isn't included in the custom fields namespace, and behaves as it always has. If you deselect this checkbox and save your changes, your legacy custom field will be added to the custom fields namespace.

Newly-created custom fields don't have the API Global Namespace option. They're in the new custom field namespace by default. If you disable the global namespace option for existing custom fields, they'll be placed in the custom field namespace, the checkbox will disappear, and you won't be able to add them back to the global namespace.


Expense category custom fields and attendee-type custom fields do not yet support being added to the custom fields namespace.


Your integrations will continue to support the old format as long as the API Global Namespace option is enabled on the custom field. For the new format, we wrap the API for new custom fields for integration objects. We're showing what this will look like in the examples below.

For the API, Coupa supports your existing custom fields in the new namespace, regardless of configuration. In the case where your custom fields are passed in both the new and old formats, Coupa will utilize the new format and ignore the older format.

API example using XML

For the API, new custom fields are wrapped in a parent <custom-fields> attribute.

		<custom-field-1>Name of first custom field</custom-field-1>
		<custom-field-2>Name of second custom field</custom-field-2>

API example using JSON

For the API, new custom fields are contained in a parent custom-fields attribute.

	"custom-fields": {
		"custom-field-1": "Name of first custom field",
		"custom-field-2": "Name of second custom field"

Related Items

Sourcing API (/quote_requests)

03 September 2021

Use the Coupa Sourcing API to create new RFx events, see supplier responses, and award suppliers at the line level.

Projects API (/projects)

22 December 2021

Use the Projects API to create or update a Project within Coupa.

Task API (/tasks)

22 December 2021

The users API allows you to create, update, or query users.

API Return Formats

03 February 2022

Use Coupa's shallow API format to reduce the amount of data you get during a query.