Model custom objects

This guide models a piece of data that isn’t a built-in resource - a size guide - using metaobjects. You declare the shape once as a metaobject definition, then create records from it.

Where a custom field adds one value to an existing product or variant, a metaobject is a whole record of your own design - reusable, and referenceable from many products.

Prerequisites

You need an instance and a partner token. You don’t need an existing product for the core steps (a product only comes in at the end, to reference a record).

As in the other guides, the commands below use:

• the organization id - shown as <org_id>
• the instance handle (the tenant) - shown as <tenant>

Before you start

You need an OAuth 2.0 bearer token for a partner account. Sign in below: your token is dropped into every command on this page, and you can pick your organization and instance to fill <org_id> and <tenant> too. See Authentication for more.

Sign in to drop your real token into the commands below.

Enter tenant & organization ID manually

Organization ID Tenant

Steps

1. Define the object type.

   Create a metaobject definition. Give it a type slug, a name, the fieldDefinitions its records will carry, and a displayNameField (the key shown as a record’s label). Capture the @id.

   curl -X POST 'https://<tenant>.product-management.flowkiwi.net/rest/api/metaobject_definitions' \
     -H 'Authorization: Bearer {token}' \
     -H 'X-Flowkiwi-Organization-Id: <org_id>' \
     -H 'Content-Type: application/ld+json' \
     -d '{
       "type": "size_guide",
       "name": "Size guide",
       "displayNameField": "title",
       "fieldDefinitions": [
         {
           "key": "title",
           "name": "Title",
           "type": "/rest/api/metafield_definition_types/single_line_text_field",
           "required": true
         },
         {
           "key": "body",
           "name": "Body",
           "type": "/rest/api/metafield_definition_types/multi_line_text_field",
           "required": false
         }
       ]
     }'

   {
     "@id": "/rest/api/metaobject_definitions/019afc01-1a2b-7c3d-8e4f-0a1b2c3d4e5f",
     "type": "size_guide",
     "displayNameField": "title"
   }

2. Create a record.

   Create a metaobject of that type. Reference the definition, give it a unique handle, and supply the fields values - one per field key. Each value is validated against the field’s type.

   curl -X POST 'https://<tenant>.product-management.flowkiwi.net/rest/api/metaobjects' \
     -H 'Authorization: Bearer {token}' \
     -H 'X-Flowkiwi-Organization-Id: <org_id>' \
     -H 'Content-Type: application/ld+json' \
     -d '{
       "definition": "/rest/api/metaobject_definitions/019afc01-1a2b-7c3d-8e4f-0a1b2c3d4e5f",
       "handle": "mens-shoes-eu",
       "status": "ACTIVE",
       "fields": [
         { "key": "title", "value": "EU men'"'"'s shoes" },
         { "key": "body", "value": "EU 40 = 25.5 cm, EU 41 = 26.2 cm, EU 42 = 27 cm" }
       ]
     }'

3. Fetch it by handle.

   You don’t need the id to read a record back - the type and handle are enough:

   curl 'https://<tenant>.product-management.flowkiwi.net/rest/api/metaobjects/size_guide/mens-shoes-eu' \
     -H 'Authorization: Bearer {token}' \
     -H 'X-Flowkiwi-Organization-Id: <org_id>' \
     -H 'Accept: application/ld+json'

   You can also list every record of the type at /rest/api/metaobject_definitions/size_guide/metaobjects.

Why model it this way?

Defining size_guide once means every record shares the same fields and validation. Create one record per size chart, then attach the right one to many products - without duplicating the data on each product.

Next steps

• Attach a record to a product. Create a metafield definition whose type is a metaobject reference, then set a metafield on a product pointing at your metaobject - that’s how a size guide ends up on a product page. See Add a custom field for the metafield basics.
• Grow the model. Add fieldDefinitions to the definition as your records need more attributes.
• Reference records by slug. Use stable handles so other systems can link to records by a readable key.