Edit in GitHubLog an issue

Custom attributes

Custom attributes can extend the core data model in Adobe Commerce, allowing you to add additional attributes to entities without requiring code or database schema changes. Consider a situation where you want to specify a duns_number or industry_type information for a company. Custom attributes make this possible.

These custom attributes operate independently of the EAV (Entity-Attribute-Value) attributes, which are defined in the Admin. They do not apply to products, categories, or customers.

Use standard POST and PUT requests to set custom attributes. All values are strings.

Supported modules

The following sections describe the REST endpoints that support custom attributes. The endpoints are grouped by feature.

Cart

When the quote is converted to an order, the custom attributes are copied to the order.

The following example shows how to set custom attributes on a cart. The quote object contains the custom_attributes array, which includes the custom attributes to set.

Copied to your clipboard
curl -i -X PUT \
   -H "Content-Type:application/json" \
   -H "Authorization:Bearer <TOKEN>" \
   -d \
'{
  "quote": {
    "customer": {
        "id":2
    },
    "store_id":1,
    "custom_attributes":[       
        {
            "attribute_code": "attr_one",
            "value": "value_one"
        },
        {
            "attribute_code": "attr_two",
            "value": "value_two"
        }
    ]
  }
}' \
 'https://<COMMERCE_URL>/rest/all/V1/carts/'

A quote item with custom attributes can be added/updated using PUT /V1/carts/{cartId}/items/:itemId.

Copied to your clipboard
curl -i -X PUT \
   -H "Content-Type:application/json" \
   -H "Authorization:Bearer <TOKEN>" \
   -d \
'{
  "cart_item": {
    "quote_id": "<QUOTE_ID>",
    "qty": 1,
    "sku": "<PRODUCT_SKU>",
    "custom_attributes":[
        {
            "attribute_code": "attr_one",
            "value": "value_one"
        },
        {
            "attribute_code": "attr_two",
            "value": "value_two"
        }
    ]
  }
}' \
 'https://<COMMERCE_URL>/rest/all/V1/carts/1/items/0'

Company

SaaS only

The POST V1/company/setCustomAttributes endpoint allows you to set custom attributes on a company. The request body must include the company_id and an array of custom_attributes.

Copied to your clipboard
curl -i -X POST \
   -H "Authorization:Bearer <TOKEN>" \
   -H "Content-Type:application/json" \
   -d \
'{
  "company_id": "68",
  "custom_attributes":[
    {
      "attribute_code": "attr one",
      "value": "value one"
    },
    {
      "attribute_code": "attr two",
      "value": "valuetwo"
    }
  ]
}' \
 'http://<COMMERCE_URL>/rest/all/V1/company/setCustomAttributes'

Creditmemo

You can use the POST V1/creditmemo and PUT V1/creditmemo/:id endpoints to set custom attributes on a credit memo and its items.

Copied to your clipboard
curl -i -X POST \
   -H "Content-Type:application/json" \
   -H "Authorization:Bearer <TOKEN>" \
   -d \
'{
  "entity": {
    "order_id": 1,
    "items": [
      {
        "order_item_id": 1,
        "qty": 2,
        "base_cost": 10,
        "base_price": 12,
        "custom_attributes": [
          {
            "attribute_code": "attr_one",
            "value": "value_one"
          },
          {
            "attribute_code": "attr_two",
            "value": "value_two"
          }
        ]
      }
    ],
    "custom_attributes": [
      {
        "attribute_code": "attr_one",
        "value": "value_one"
      },
      {
        "attribute_code": "attr_two",
        "value": "value_two"
      }
    ]
  }
}' \
 'http://<COMMERCE_URL>/rest/all/V1/creditmemo'

Invoice

The POST V1/invoices endpoint sets custom attributes on an invoice and its items, as shown in the following example.

Copied to your clipboard
curl -i -X POST \
   -H "Content-Type:application/json" \
   -H "Authorization:Bearer <TOKEN>" \
   -d \
'{
  "entity": {
    "order_id": 46,
    "custom_attributes":[
      {
          "attribute_code": "attr one",
          "value": "value one"
      },
      {
          "attribute_code": "attr two",
          "value": "value two"
      }
    ],
    "items": [
      {
        "orderItemId": 46,
        "qty": 2,
        "sku": "sku12343",
        "custom_attributes":[
          {
              "attribute_code": "attr one",
              "value": "value one"
          },
          {
              "attribute_code": "attr two",
              "value": "value two"
          }
        ]
      }
    ]
  }
}' \
 'http://<COMMERCE_URL>/rest/all/V1/invoices'

Order

The following example uses the POST V1/order endpoint to set custom attributes on an order.

Copied to your clipboard
curl -i -X POST \
   -H "Content-Type:application/json" \
   -H "Authorization:Bearer <token>" \
   -d \
'{
  "entity": {
    "entity_id": 14,
    "custom_attributes":[
      {
          "attribute_code": "attr_one",
          "value": "value_one"
      },
      {
          "attribute_code": "attr_two",
          "value": "value_two"
      }
    ]
  }
}' \
 'https://<COMMERCE_URL>/rest/all/V1/orders'

If an order item has custom attributes, they will be returned as part of the order item object in responses to requests like GET /V1/order/items/{id}.

Negotiable Quote

SaaS only

The POST /V1/negotiableQuote/setCustomAttributes endpoint allows you to set custom attributes on a negotiable quote. The request body must include the quote_id and an array of custom_attributes.

Copied to your clipboard
curl -i -X POST \
   -H "Authorization:Bearer <TOKEN>" \
   -H "Content-Type:application/json" \
   -d \
'{
  "quote_id": "68",
  "custom_attributes":[
    {
      "attribute_code": "attr one",
      "value": "value one"
    },
    {
      "attribute_code": "attr two",
      "value": "valuetwo"
    }
  ]
}' \
 'http://<COMMERCE_URL>/rest/all/V1/negotiableQuote/setCustomAttributes'

Install custom attribute support

PaaS only

Prerequisites

  • Adobe Commerce on cloud infrastructure or on-premises: 2.4.5+
  • PHP 8.1+
  • Magento Open Source is not supported.

Installation

To install custom attributes in Adobe Commerce:

  1. Run the following command to install the modules:

    Copied to your clipboard
    composer require magento/out-of-process-custom-attributes=^0.2.0  --with-dependencies

  2. Enable the new module:

    Copied to your clipboard
    bin/magento module:enable Magento_OutOfProcessCustomAttributes

  3. For on-premises installations, run the following command to upgrade Adobe Commerce and clear the cache.

    Copied to your clipboard
    bin/magento setup:upgrade && bin/magento cache:clean
Was this helpful?