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 is available to all authenticated users, subject to connector configuration.

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
    },
    {
      "id": 6,
      "name": "my_second_pim_select_attribute-en_US",
      "project": 67
    },
    {
      "id": 7,
      "name": "my_third_pim_select_attribute-en_US-ecommerce",
      "project": 67
    }
  ]
}

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

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. This endpoint is available to all authenticated users, but the connector must be configured to 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

A single request can include up to 1,000 options. You cannot use this endpoint to update existing options — it only adds new ones.

Example request:

PATCH https://sdm.akeneo.cloud/api/v1/options_collections/{id}/add-options/
{
  "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,
  "push_results": {
    "connector_results": {
      "AkeneoConnection": { "success": true }
    }
  },
  "successful_options": ["my-new-option-code"],
  "failed_unknown_options": []
}

The response includes:

• successful_options — option names successfully pushed to the PIM and saved in SDM
• failed_unknown_options — option names that could not be pushed or had an unknown result; these are not saved in SDM
• push_results — per-connector details of the push operation

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."