Skip to content
Developers

Metafields

A metafield stores a piece of your own data on a user, a listing or an order: the id of the customer in your ERP, a loyalty tier, the warehouse that ships a listing, the invoice number your accounting software assigned to an order. Kreezalid stores it, returns it with the object, and never interprets it.

A metafield has three parts:

Field Role Example
namespace Groups the metafields of one integration, so two integrations never collide. erp
title The key, unique within the namespace for one object. customer_code
value The value, stored as text. C-00841

Endpoints

Section titled “Endpoints”

Metafields are written and listed with the Admin API:

Object List Create or update
User GET /api/v1/users/{id}/metafields POST /api/v1/users/{id}/metafields
Listing GET /api/v1/listings/{id}/metafields POST /api/v1/listings/{id}/metafields
Order GET /api/v1/orders/{id}/metafields POST /api/v1/orders/{id}/metafields

See List an order’s metafields and Add metafields to a listing in the reference.

Write metafields

Section titled “Write metafields”

POST either one metafield or an array of them. A metafield with the same namespace and title on the same object is updated, otherwise it is created, so the call is safe to repeat.

Terminal window
curl -X POST https://acme.mykreezalid.com/api/v1/orders/90311/metafields \
  -u "$KREEZALID_API_KEY:$KREEZALID_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '[
    { "namespace": "erp", "title": "sales_order", "value": "SO-2026-11873" },
    { "namespace": "erp", "title": "invoice_number", "value": "F-2026-04412" }
  ]'

The response echoes what was saved. An array request answers under metafields:

{
  "metafields": [
    { "namespace": "erp", "title": "sales_order", "value": "SO-2026-11873" },
    { "namespace": "erp", "title": "invoice_number", "value": "F-2026-04412" }
  ]
}

A single metafield is sent as an object ({"namespace": …, "title": …, "value": …}), and is answered under metafield, still as a one-element array. Bodies wrapped in a metafield key, as older integrations send them, are accepted too.

Rules

Section titled “Rules”
  • namespace, title and value are all required and must not be empty. A missing one answers 406 with a message such as Invalid data received: value index is required and not empty. In an array, the entries before the invalid one are already saved.
  • value is text. Store numbers and booleans as strings, and structured data as a JSON string you encode and decode yourself.
  • A value of "0" counts as empty and is refused. Store such flags as "false"/"true" or "no"/"yes".
  • There is no endpoint to delete a metafield. To clear one, overwrite its value, for instance with "-", and treat that value as absent on your side.

Read metafields

Section titled “Read metafields”

GET /api/v1/{resource}/{id}/metafields returns every metafield of the object:

{
  "metafields": [
    { "namespace": "erp", "title": "sales_order", "value": "SO-2026-11873" },
    { "namespace": "erp", "title": "invoice_number", "value": "F-2026-04412" }
  ]
}

Metafields also come with the object itself, in a metafields field grouped by namespace then key, or null when there are none. They are included when you retrieve a single user, listing or order, in lists of users and orders, in webhook payloads and in the Front API’s orders and listings. The list of listings (GET /api/v1/listings) leaves them out: read them per listing when you need them.

{
  "object": "Order",
  "id": 90311,
  "metafields": {
    "erp": {
      "sales_order": "SO-2026-11873",
      "invoice_number": "F-2026-04412"
    }
  }
}

Typical uses

Section titled “Typical uses”
Object Namespace and key Value
User crm.contact_id The member’s id in your CRM, to update the right contact.
User loyalty.tier gold, read by your theme or app to show a badge.
Listing pim.product_id The product in your PIM, when external_id already holds the vendor’s SKU.
Order erp.sales_order The sales order created in your ERP, to avoid creating it twice.
Order shipping.label_url The label your logistics provider generated.