Skip to main content
AttributeFormatLengthRequiredDescriptionExample
owner_typeStringN/AYesThe type of object that owns the metafield. Acceptable values include ShopperShopper
owner_refString (format depends on type)N/AYesA unique identifier for the owner. The format depends on the owner_type.sh-1234
namespaceStringN/AYesA grouping for the metafield. Typically custom for user-defined fields.custom
keyStringN/AYesA unique identifier for the metafield within its namespace. It should be unique per owner and namespace.favorite_color
is_listBoolean [true|false]N/AYesIndicates whether the metafield contains a list of values. Acceptable values are true or false.false
value_typeStringN/AYesThe data type of the metafield value. Acceptable values include single_line_text_field, boolean, date, etc.single_line_text_field
valueDepends on value_typeN/AYesThe actual value of the metafield. Accepted values depend on the selected value_type.Blue
activeBoolean [true|false]N/AYesDefines whether the metafield should be active. When set to false, the metafield should be removed.true

​
Owner Type

The owner_type field defines which BSPK object the metafield belongs to. Available options:
  • Shopper

​
Owner Reference

The owner_ref must match an existing object in BSPK for the provided owner_type. Its format may vary depending on the type of owner.

​
Namespace and Key

The combination of namespace and key identifies the metafield definition within a given owner. For example:
  • namespace: custom
  • key: favorite_color
This allows integrations to group related metafields and avoid naming collisions.

​
List Values

When is_list is set to true, the metafield value is expected to represent a list of values instead of a single value. When is_list is set to false, the metafield value is treated as a single value.

​
Value Type

The value_type determines how the value field is interpreted. Examples include:
  • single_line_text_field
  • boolean
  • date
The provided value must be compatible with the selected value_type.

​
Active

The active field controls whether the metafield should exist in BSPK.
  • When true, the metafield is created or updated
  • When false, the metafield is removed

​
Sample File

owner_type,owner_ref,namespace,key,is_list,value_type,value,active
Shopper,sh-1234,loyalty,id,false,single_line_text_field,1304,true
Shopper,sh-1234,loyalty,program_subscription,false,single_line_text_field,true,true
Shopper,sh-1234,loyalty,points,false,single_line_text_field,600,true
Shopper,sh-1234,loyalty,status,false,single_line_text_field,Premium,true
Shopper,sh-789,loyalty,id,false,single_line_text_field,8776,true
Shopper,sh-789,loyalty,program_subscription,false,single_line_text_field,true,true
Shopper,sh-789,loyalty,points,false,single_line_text_field,100,true
Shopper,sh-789,loyalty,status,false,single_line_text_field,Premium,true
Shopper,sh-789,prefs,tags,true,single_line_text_field,"tag1;tag2",true