In Supplier Data Manager (SDM), fields of type select reference option collections to determine their available options. An option collection is a named list of choices associated with one or more select fields in a project.

Example select field definition showing the options_collection_name property:

{
  "name": "my_select_field",
  "groups": ["my_family"],
  "requirement_level": "optional",
  "type": "select",
  "options_collection_name": "my_option_collection",
  "multiple": false
}

The options_collection_name property links the field to its option collection. You can retrieve, create, and update option collections through the SDM REST API.

Before you start

All SDM REST API requests require a bearer token. See Getting started with the API for how to generate and use your authentication token.

Creating option collections and updating options without a connector requires organization admin permissions. Adding options through the Akeneo PIM connector endpoint requires an active SDM user in an active organization. The connector configuration must also allow the operation.

List option collections

To retrieve all option collections for your organization in SDM, send a GET request to the list endpoint. Results are paginated; page numbers start at 1.

GET https://sdm.akeneo.cloud/api/v1/options_collections/?page=1&limit=25

You can filter results by collection name or by project ID using query parameters:

GET https://sdm.akeneo.cloud/api/v1/options_collections/?project=67&page=1&limit=25

Response example:

{
  "count": 125,
  "previous": null,
  "next": "https://sdm.akeneo.cloud/api/v1/options_collections/?page=2&limit=25",
  "results": [
    {
      "id": 5,
      "name": "my_first_pim_select_attribute",
      "project": 67,
      "create_only_option_creation_supported": true
    },
    {
      "id": 6,
      "name": "my_second_pim_select_attribute-en_US",
      "project": 67,
      "create_only_option_creation_supported": true
    },
    {
      "id": 7,
      "name": "my_third_pim_select_attribute-en_US-ecommerce",
      "project": 67,
      "create_only_option_creation_supported": false
    }
  ]
}

Use the id returned in these results to reference a collection in subsequent update or add-options requests.

The create_only_option_creation_supported field shows whether the current caller can use safe creation. The value is true only when one eligible connector supports an atomic create request. Akeneo simple-select and multi-select attributes support this request. Reference entities and table columns do not support it.

Create an option collection

To create a new option collection in SDM, send a POST request. This endpoint requires organization admin permissions. You can optionally include initial options inline.

POST https://sdm.akeneo.cloud/api/v1/options_collections/
{
  "name": "my_option_collection",
  "project": 67,
  "upsert_options": [
    {
      "name": "option-code-1",
      "label": {
        "en-US": "Option One",
        "fr-FR": "Option Un"
      }
    }
  ]
}

The name must be unique within the project. The upsert_options field is optional.

Success response (201):

{
  "id": 8,
  "name": "my_option_collection",
  "project": 67
}

Update options without an external connector

Use this method when your SDM project configuration does not depend on an external source of truth via any connector.

This endpoint requires organization admin permissions. A single request can upsert up to 1,000 options.

Example request:

PATCH https://sdm.akeneo.cloud/api/v1/options_collections/{id}/update-options/
{
  "upsert_options": [
    {
      "name": "my-new-option-name",
      "label": {
        "en-US": "My new option",
        "fr-FR": "Ma nouvelle option"
      }
    }
  ],
  "delete_options": ["my-old-option-name"],
  "delete_all": false
}

Option names within a single request must be unique. Submitting duplicate names in upsert_options returns a 400 error: "Duplicate option names found: {names}. Option names must be unique."

Example success response:

{
  "id": 6,
  "name": "my-option-collection",
  "project": 67
}

Option collections derived from Akeneo PIM attributes

When your SDM project is connected to an Akeneo PIM connector, certain PIM attribute types automatically create select fields with associated option collections in SDM:

• Single-select and multi-select attributes
• Reference entity attributes
• Price attributes (currency becomes a select field)
• Measurement attributes (unit becomes a select field)

How PIM-derived option collections are named

For select and reference entity attributes, the SDM option collection name is derived from the PIM attribute code combined with the locale and channel codes when applicable:

Use the list option collections endpoint to retrieve the id of the collection you want to update.

Add options to SDM and Akeneo PIM simultaneously

When you want to add new options to both SDM and the connected Akeneo PIM at the same time, use the add-options endpoint. The caller must be an active SDM user in an active organization. The connector must allow option creation for the target attribute.

To enable simultaneous option creation for specific attributes, set the allowed_options_for_pim_attribute_addition field in the connector configuration to the list of attribute codes for which this behavior should be allowed. See How to set up and use the connector.

This endpoint:

1. Validates that the attribute is in the connector's allow-list
2. Pushes the new options to the connected Akeneo PIM
3. Saves the options to SDM only if the PIM accepts them

The endpoint has two modes:

• Safe creation: Set create_only to true and send exactly one new option. The request fails if the option code already exists. Use this mode for interactive option creation.
• Legacy upsert: Omit create_only or set it to false. A request can create or update up to 1,000 options.

Safe creation uses the Akeneo create endpoint for simple-select and multi-select attributes. It does not support reference entities or table columns. It also requires exactly one eligible connector. These rules prevent partial writes that SDM cannot roll back.

Example request:

PATCH https://sdm.akeneo.cloud/api/v1/options_collections/{id}/add-options/
{
  "create_only": true,
  "upsert_options": [
    {
      "name": "my-new-option-code",
      "label": {
        "en-US": "My new option",
        "fr-FR": "Ma nouvelle option"
      }
    }
  ]
}

Example success response:

{
  "id": 6,
  "name": "my_second_pim_select_attribute-en_US",
  "project": 67,
  "create_only_option_creation_supported": true,
  "push_results": {
    "connector_results": {
      "AkeneoMarketplaceConnection:550e8400-e29b-41d4-a716-446655440000": { "success": true }
    }
  },
  "successful_options": ["my-new-option-code"],
  "failed_unknown_options": []
}

The response includes:

• successful_options — option names accepted by the PIM and saved in SDM
• failed_unknown_options — option names that one or more connector requests rejected or could not classify
• push_results — per-connector details of the push operation

Safe creation identifies each connector result as {connector_class}:{connection_id}. Legacy upsert retains the historical {connector_class} key.

Safe creation does not save names in failed_unknown_options. Legacy upsert saves an option when any active connector accepts it. A name can therefore appear in both response lists when legacy connectors disagree.

If no active connector is found for the project, the request returns a 400 error: "No active connector found for this project." If the attribute is not in the connector's allow-list, the request returns a 400 error: "Option creation is not allowed for the attribute '{name}'. Check the connector's allowed_options_for_pim_attribute_addition configuration."

In safe mode, a code that already exists in SDM returns a 400 error before any connector request. An Akeneo collision appears in failed_unknown_options, and SDM does not save the option.