commerce/orders/attributedefinition/attributes

Attributes are used to add custom definitions and characteristics to the following objects:

  • Product attributes — are attributes that define the characteristics of products, enabling you to uniquely describe a product. They consist of options, properties, and extras. Refer to Product Attributes in the Guides section for more information.
  • Customer attributes — are custom attributes that you can apply to customer accounts to add further definition for special uses, such as marketing campaigns, or discounts. Refer to Customer Attributes in the Guides section for more information.
  • Order attributes — are custom attributes that enable you to uniquely describe an aspect of an order. Depending on the attribute definition, either you or a shopper can enter values for the order attribute. Refer to Order Attributes in the Guides section for more information.

JSON Example

Attribute Properties

Property Description
adminName

type: string

The administrator name associated with the object/data.

attributeCode

type: string

Merchant-defined code for an extensible attribute. This code may be used to generate an object's fully qualified name, such as for products.

attributeFQN

type: string

The fully qualified name of the attribute. The attributeDefiniteId may be used to generate this name.

attributeMetadata

type: list of attributeMetadataItem

List of metadata key-value pairs defined for an extensible attribute.

attributeMetadataItem.key

type: string

Key used for metadata defined for objects, including extensible attributes, custom attributes associated with a shipping provider, and search synonyms definitions. This content may be user-defined depending on the object and usage.

For search synonym definitions, refer to Synonym Expansion Types for more information about the key usage.

attributeMetadataItem.value

type: string

The value of a property, used by numerous objects within Kibo eCommerce including facets, attributes, products, localized content, metadata, capabilities (Kibo eCommerce and third-party), location inventory adjustment, and more. The value may be a string, integer, or double. Validation may be run against the entered and saved values depending on the object type.

auditInfo

type: auditInfo

Basic audit info about the object, including date, time, and user account. This data may be captured when creating, updating, and removing data.

auditInfo.createBy

type: string

Identifier of the user that created the object. System created and read only.

auditInfo.createDate

type: DateTime

The date and time in UTC format set when the object was created.

auditInfo.updateBy

type: string

Identifier of the user that updated the entity most recently.

auditInfo.updateDate

type: DateTime

The date and time in UTC format the object was updated most recently.

content

type: attributeLocalizedContent

Localizable content (such as a name and/or description) for an attribute. The content may be localized when displayed according to the locale code specified by the master catalog. Content can include descriptive text for product extensible attributes, catalog-level descriptions (displayed if isContentOverriden is true), product bundles, and customer account notes.

attributeLocalizedContent.localeCode

type: string

The two character locale code, per the country code provided. This code determines the localized content to use and display.

attributeLocalizedContent.value

type: string

The value of a property, used by numerous objects within Kibo eCommerce including facets, attributes, products, localized content, metadata, capabilities (Kibo eCommerce and third-party), location inventory adjustment, and more. The value may be a string, integer, or double. Validation may be run against the entered and saved values depending on the object type.

dataType

type: string

The data type of the source product property, typically of type Bool, DateTime, Number, or String.

displayGroup

type: string

Whether the customer or order attribute appears in Admin only, or in both Admin and the website storefront. Possible values are Admin and AdminAndStorefront.

id

type: int

Unique identifier of the source property, such as a catalog, discount, order, or email template.

For a product field it will be the name of the field.

For a category ID, must be a positive integer not greater than 2000000. By default, Kibo eCommerce auto-generates a category ID when categories are created. If you want to specify an ID during creation (which preserves category link relationships when migrating tenant data from one sandbox to another), you must also include the useProvidedId query string in the endpoint. For example, api/commerce/catalog/admin/categories/?useProvidedId=true. Then, use the id property to specify the desired category ID.

For a product attribute it will be the Attribute FQN.

For a document, the ID must be specified as a 32 character, case-insensitive, alphanumeric string. You can specify the ID as 32 sequential characters or as groups separated by dashes in the format 8-4-4-4-12. For example, bba0a1a885e2413bb097ceacf7bac366
or
bba0a1a8-85e2-413b-b097-ceacf7bac366.

For email templates, the ID must be one of the following values:
BackInStock
OrderChanged
OrderShipped
OrderFulfillmentDetailsChanged
ShopperLoginCreated
ShopperPasswordReset
ReturnCreated
ReturnAuthorized
ReturnUpdated
ReturnRejected
ReturnCancelled
ReturnClosed
RefundCreated
StoreCreditCreated
StoreCreditUpdated
GiftCardCreated

inputType

type: string

The type of input selection used to define a value for the attribute, including Yes/No, Date, DateTime, List, TextBox, or TextArea.

isActive

type: bool

Indicates if the object or feature is active.

isMultiValued

type: bool

If true, the attribute can have more than one value.

isReadOnly

type: bool

Flag used to indicate if this attribute definition is read-only. Once an attribute definition is set to read-only this action cannot be undone.

isRequired

type: bool

Indicates if the property, attribute, product option, or product extra is required. If true, the object must have a defined value.

isVisible

type: bool

If true, the attribute is visible in its defined display group.

namespace

type: string

The namespace for the accessible APIs and source capabilities in the core of Kibo eCommerce APIs.

order

type: int

Integer that represents the sequence order of the attribute.

validation

type: attributeValidation

Properties used when validating a value entered for an object, including extensible attributes, products attributes, and database entries.

attributeValidation.maxDateTime

type: DateTime

The latest possible date and time the extensible attribute can be validated.

attributeValidation.maxNumericValue

type: decimal

The maximum number that can be entered as a value for an extensible attribute.

attributeValidation.maxStringLength

type: int

The maximum character length possible for a string value entered for an extensible attribute.

attributeValidation.minDateTime

type: DateTime

The earliest date and time an extensible attribute can be validated.

attributeValidation.minNumericValue

type: decimal

The minimum numeric value required to validate an extensible attribute.

attributeValidation.minStringLength

type: int

The minimum character length possible for a string value entered for an extensible attribute.

attributeValidation.regularExpression

type: string

Regular expression used to process and validate an extensible attribute value that require special formatting, such as phone numbers.

valueType

type: string

An attribute value type is either predefined vocabulary set by the admin during attribute set up, or user-defined with an appropriate type (AdminEntered or ShopperEntered, depending on the user). These types are used by products and attributes. To use a predefined value, you can set this parameter as "predefined" and whatever the admin entered in the Product Attributes > Create New Attribute interface menu will become the predefined value on the attribute. AdminEntered and ShopperEntered are values that are entered rather than system-supplied and are not stored in the database, but captured during a live commerce operations such as during an order.

vocabularyValues

type: list of attributeVocabularyValue

List of valid vocabulary values defined for an attribute.

attributeVocabularyValue.content

type: attributeValueLocalizedContent

Localizable content (such as a name and/or description) for an attribute. The content may be localized when displayed according to the locale code specified by the master catalog. Content can include descriptive text for product extensible attributes, catalog-level descriptions (displayed if isContentOverriden is true), product bundles, and customer account notes.

attributeVocabularyValue.attributeValueLocalizedContent.localeCode

type: string

The two character locale code, per the country code provided. This code determines the localized content to use and display.

attributeVocabularyValue.attributeValueLocalizedContent.value

type: string

The value of a property, used by numerous objects within Kibo eCommerce including facets, attributes, products, localized content, metadata, capabilities (Kibo eCommerce and third-party), location inventory adjustment, and more. The value may be a string, integer, or double. Validation may be run against the entered and saved values depending on the object type.

attributeVocabularyValue.isHidden

type: bool

Indicates if the object is hidden or breaks inheritance, primarily used by facets, products, and attribute vocabulary values. For example, if true, the attribute vocabulary value does not appear in the list when defining a value for an attribute.

attributeVocabularyValue.sequence

type: int

The numeric order of objects, used by a vocabulary value defined for an extensible attribute, images, and categories.

attributeVocabularyValue.value

type: string

The value of a property, used by numerous objects within Kibo eCommerce including facets, attributes, products, localized content, metadata, capabilities (Kibo eCommerce and third-party), location inventory adjustment, and more. The value may be a string, integer, or double. Validation may be run against the entered and saved values depending on the object type.

Operations

Operation Name Request URI Description
CreateAttribute POST %3fresponseFields%3d%7bresponseFields%7d

Create and save a new attribute. These attributes are used in products and product options.

GetAttribute GET %7battributeFQN%7d%3fresponseFields%3d%7bresponseFields%7d

Retrieves the details of the specified product attribute.

GetAttributes GET %3fstartIndex%3d%7bstartIndex%7d%26pageSize%3d%7bpageSize%7d%26sortBy%3d%7bsortBy%7d%26filter%3d%7bfilter%7d%26responseFields%3d%7bresponseFields%7d

Retrieves a paged list of attributes according to any specified filter criteria and sort options.

GetAttributeVocabularyValues GET %7battributeFQN%7d%2fVocabularyValues

Retrieve a list of the vocabulary values defined for the customer attribute specified in the request.

UpdateAttribute PUT %7battributeFQN%7d%3fresponseFields%3d%7bresponseFields%7d

Updates an existing attribute with attribute properties to set.