Brainerce
Help CenterPricingResourcesDashboard
API ReferenceEndpointsMetafields

Metafields

Metafields add arbitrary custom fields to products, orders, customers, and other resources. Each metafield definition has a namespace, key, type, and validation rules — values are then attached per-resource.

List metafield definitions

GET
/vc/{connectionId}/metafield-definitions

Authorization

X-Sales-Channel-Origin<token>

For /api/vc/{connectionId}/* routes the connectionId (vc_*) is in the URL path — not a header. Live-mode requests must also send a matching Origin header.

In: header

Path Parameters

connectionIdstring

Header Parameters

originstring
curl -X GET "https://api.brainerce.com/api/vc/string/metafield-definitions" \  -H "origin: string"
{
  "definitions": [
    {
      "id": "clmfd_abc123",
      "name": "string",
      "key": "material",
      "description": "string",
      "type": "SELECT",
      "required": false,
      "filterable": true,
      "enumValues": [
        {}
      ],
      "position": 0
    }
  ]
}

List metafield facet filters with product counts

GET
/vc/{connectionId}/metafield-filters

Authorization

X-Sales-Channel-Origin<token>

For /api/vc/{connectionId}/* routes the connectionId (vc_*) is in the URL path — not a header. Live-mode requests must also send a matching Origin header.

In: header

Path Parameters

connectionIdstring

Query Parameters

locale?unknown

Locale for translated definition names (falls back to the Accept-Language header, then the store default).

Header Parameters

originstring
curl -X GET "https://api.brainerce.com/api/vc/string/metafield-filters" \  -H "origin: string"
{
  "filters": [
    {
      "id": "clmfd_abc123",
      "key": "string",
      "name": "string",
      "type": "SELECT",
      "enumValues": [
        {
          "value": "red",
          "label": "Red"
        }
      ],
      "values": [
        {
          "value": "cotton",
          "count": 12
        }
      ]
    }
  ]
}

Upload customization file

Uploads one buyer-supplied image and returns the URL to use as the value of an IMAGE or GALLERY customer-input customization field (a metafield definition with isCustomerInput). Upload BEFORE add-to-cart: the cart rejects any IMAGE/GALLERY value that is not a URL this endpoint returned for the same store, so an external URL cannot be pasted in.

Send multipart/form-data with a single file part. JPEG, PNG, WebP and GIF only — the declared content type is cross-checked against the file's magic bytes, and SVG is refused outright. Hard limits are 5 MB and 40 megapixels per file, one file per request. Stored bytes count against the merchant's plan storage quota. Rate limited to 10 uploads per minute. Uploads never referenced by a cart line are swept by the customer-uploads cleanup job.

POST
/vc/{connectionId}/customization-upload

Authorization

X-Sales-Channel-Origin<token>

For /api/vc/{connectionId}/* routes the connectionId (vc_*) is in the URL path — not a header. Live-mode requests must also send a matching Origin header.

In: header

Path Parameters

connectionIdstring

Sales-channel connection ID (vc_*)

Header Parameters

origin?string

Request Body

filestring

The image to store. JPEG, PNG, WebP or GIF; 5 MB and 40 MP maximum.

curl -X POST "https://api.brainerce.com/api/vc/string/customization-upload" \  -H "origin: string" \  -F file="string"
{
  "url": "https://cdn.brainerce.com/customizations/abc123.png",
  "key": "customizations/abc123.png",
  "width": 1200,
  "height": 800
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/vc/{connectionId}/customization-upload"
}

List metafield definitions

GET
/v1/metafield-definitions

Authorization

AuthorizationBearer <token>

Admin API key (server-to-server). Issue via the dashboard at Settings → Authentication → API Keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.

In: header

curl -X GET "https://api.brainerce.com/api/v1/metafield-definitions"
[
  {
    "id": "string",
    "accountId": "string",
    "storeId": "string",
    "name": "Warranty Info",
    "key": "warranty_info",
    "description": "string",
    "type": "string",
    "required": true,
    "isCustomerInput": true,
    "appliesToAllProducts": true,
    "filterable": true,
    "minLength": 0,
    "maxLength": 0,
    "minValue": 0,
    "maxValue": 0,
    "dateAvailability": {},
    "enumValues": [
      {
        "label": "string",
        "value": "string",
        "swatchColor": "string",
        "swatchImageUrl": "string"
      }
    ],
    "defaultValue": "string",
    "position": 0,
    "isActive": true,
    "publishedOn": [
      "SHOPIFY"
    ],
    "platformIds": {
      "property1": "string",
      "property2": "string"
    },
    "platformMetadata": {},
    "syncStatus": {
      "property1": "string",
      "property2": "string"
    },
    "lastSyncedAt": {
      "property1": "string",
      "property2": "string"
    },
    "source": "string",
    "products": [
      {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "Summer Collection"
      }
    ],
    "channelPublishes": [
      {
        "salesChannel": {
          "id": "clx1a2b3c4d5e6f7g8h9",
          "name": "My storefront",
          "connectionId": "vc_9f3a2b1c8d7e6f5a"
        },
        "connection": {
          "id": "clx1a2b3c4d5e6f7g8h9",
          "name": "My storefront",
          "connectionId": "vc_9f3a2b1c8d7e6f5a"
        }
      }
    ],
    "vibeCodedPublishes": [
      {
        "salesChannel": {
          "id": "clx1a2b3c4d5e6f7g8h9",
          "name": "My storefront",
          "connectionId": "vc_9f3a2b1c8d7e6f5a"
        },
        "connection": {
          "id": "clx1a2b3c4d5e6f7g8h9",
          "name": "My storefront",
          "connectionId": "vc_9f3a2b1c8d7e6f5a"
        }
      }
    ],
    "_count": {
      "values": 0
    },
    "translations": {},
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
]

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions"
}

Create a new metafield definition

Supports Idempotency-Key header for safe retries.

POST
/v1/metafield-definitions

Authorization

AuthorizationBearer <token>

Admin API key (server-to-server). Issue via the dashboard at Settings → Authentication → API Keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.

In: header

Header Parameters

Idempotency-Key?string

Client-supplied key (a UUID v4 is the recommended form, max 255 characters) that makes this mutation safe to retry.

  • Replay window: 24 hours. The first response for a key is cached; a retry inside the window with the same request body returns the original status and body without re-running the handler.
  • Reusing a key with a different body returns 409 Conflict with code: "IDEMPOTENCY_KEY_REUSED". The request fingerprint (method + path + body hash) is compared against the stored one; a mismatch is refused rather than served the old response.
  • Keys are scoped to the calling credential and store — two API keys may safely use the same key value.
  • Error responses are cached too, so a retry of a request that failed validation returns the same 400 immediately.
  • Sending this header on a GET returns 400 with code: "IDEMPOTENCY_KEY_NOT_SUPPORTED" — GETs are already idempotent.
  • Support is per-route and this parameter is the authoritative signal: a key sent to a route that does not declare it is accepted and silently ignored.

See /docs/api/idempotency.

Lengthlength <= 255

Request Body

Empty Object

curl -X POST "https://api.brainerce.com/api/v1/metafield-definitions" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{}'
{
  "id": "string",
  "accountId": "string",
  "storeId": "string",
  "name": "Warranty Info",
  "key": "warranty_info",
  "description": "string",
  "type": "string",
  "required": true,
  "isCustomerInput": true,
  "appliesToAllProducts": true,
  "filterable": true,
  "minLength": 0,
  "maxLength": 0,
  "minValue": 0,
  "maxValue": 0,
  "dateAvailability": {},
  "enumValues": [
    {
      "label": "string",
      "value": "string",
      "swatchColor": "string",
      "swatchImageUrl": "string"
    }
  ],
  "defaultValue": "string",
  "position": 0,
  "isActive": true,
  "publishedOn": [
    "SHOPIFY"
  ],
  "platformIds": {
    "property1": "string",
    "property2": "string"
  },
  "platformMetadata": {},
  "syncStatus": {
    "property1": "string",
    "property2": "string"
  },
  "lastSyncedAt": {
    "property1": "string",
    "property2": "string"
  },
  "source": "string",
  "products": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "name": "Summer Collection"
    }
  ],
  "channelPublishes": [
    {
      "salesChannel": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "My storefront",
        "connectionId": "vc_9f3a2b1c8d7e6f5a"
      },
      "connection": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "My storefront",
        "connectionId": "vc_9f3a2b1c8d7e6f5a"
      }
    }
  ],
  "vibeCodedPublishes": [
    {
      "salesChannel": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "My storefront",
        "connectionId": "vc_9f3a2b1c8d7e6f5a"
      },
      "connection": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "My storefront",
        "connectionId": "vc_9f3a2b1c8d7e6f5a"
      }
    }
  ],
  "_count": {
    "values": 0
  },
  "translations": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions"
}

Get a single metafield definition by ID

GET
/v1/metafield-definitions/{id}

Authorization

AuthorizationBearer <token>

Admin API key (server-to-server). Issue via the dashboard at Settings → Authentication → API Keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.

In: header

Path Parameters

idstring

Metafield Definition ID

curl -X GET "https://api.brainerce.com/api/v1/metafield-definitions/string"
{
  "id": "string",
  "accountId": "string",
  "storeId": "string",
  "name": "Warranty Info",
  "key": "warranty_info",
  "description": "string",
  "type": "string",
  "required": true,
  "isCustomerInput": true,
  "appliesToAllProducts": true,
  "filterable": true,
  "minLength": 0,
  "maxLength": 0,
  "minValue": 0,
  "maxValue": 0,
  "dateAvailability": {},
  "enumValues": [
    {
      "label": "string",
      "value": "string",
      "swatchColor": "string",
      "swatchImageUrl": "string"
    }
  ],
  "defaultValue": "string",
  "position": 0,
  "isActive": true,
  "publishedOn": [
    "SHOPIFY"
  ],
  "platformIds": {
    "property1": "string",
    "property2": "string"
  },
  "platformMetadata": {},
  "syncStatus": {
    "property1": "string",
    "property2": "string"
  },
  "lastSyncedAt": {
    "property1": "string",
    "property2": "string"
  },
  "source": "string",
  "products": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "name": "Summer Collection"
    }
  ],
  "channelPublishes": [
    {
      "salesChannel": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "My storefront",
        "connectionId": "vc_9f3a2b1c8d7e6f5a"
      },
      "connection": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "My storefront",
        "connectionId": "vc_9f3a2b1c8d7e6f5a"
      }
    }
  ],
  "vibeCodedPublishes": [
    {
      "salesChannel": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "My storefront",
        "connectionId": "vc_9f3a2b1c8d7e6f5a"
      },
      "connection": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "My storefront",
        "connectionId": "vc_9f3a2b1c8d7e6f5a"
      }
    }
  ],
  "_count": {
    "values": 0
  },
  "translations": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions/{id}"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions/{id}"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions/{id}"
}

Update a metafield definition

Supports Idempotency-Key header for safe retries.

PATCH
/v1/metafield-definitions/{id}

Authorization

AuthorizationBearer <token>

Admin API key (server-to-server). Issue via the dashboard at Settings → Authentication → API Keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.

In: header

Path Parameters

idstring

Metafield Definition ID

Header Parameters

Idempotency-Key?string

Client-supplied key (a UUID v4 is the recommended form, max 255 characters) that makes this mutation safe to retry.

  • Replay window: 24 hours. The first response for a key is cached; a retry inside the window with the same request body returns the original status and body without re-running the handler.
  • Reusing a key with a different body returns 409 Conflict with code: "IDEMPOTENCY_KEY_REUSED". The request fingerprint (method + path + body hash) is compared against the stored one; a mismatch is refused rather than served the old response.
  • Keys are scoped to the calling credential and store — two API keys may safely use the same key value.
  • Error responses are cached too, so a retry of a request that failed validation returns the same 400 immediately.
  • Sending this header on a GET returns 400 with code: "IDEMPOTENCY_KEY_NOT_SUPPORTED" — GETs are already idempotent.
  • Support is per-route and this parameter is the authoritative signal: a key sent to a route that does not declare it is accepted and silently ignored.

See /docs/api/idempotency.

Lengthlength <= 255

Request Body

Empty Object

curl -X PATCH "https://api.brainerce.com/api/v1/metafield-definitions/string" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{}'
{
  "id": "string",
  "accountId": "string",
  "storeId": "string",
  "name": "Warranty Info",
  "key": "warranty_info",
  "description": "string",
  "type": "string",
  "required": true,
  "isCustomerInput": true,
  "appliesToAllProducts": true,
  "filterable": true,
  "minLength": 0,
  "maxLength": 0,
  "minValue": 0,
  "maxValue": 0,
  "dateAvailability": {},
  "enumValues": [
    {
      "label": "string",
      "value": "string",
      "swatchColor": "string",
      "swatchImageUrl": "string"
    }
  ],
  "defaultValue": "string",
  "position": 0,
  "isActive": true,
  "publishedOn": [
    "SHOPIFY"
  ],
  "platformIds": {
    "property1": "string",
    "property2": "string"
  },
  "platformMetadata": {},
  "syncStatus": {
    "property1": "string",
    "property2": "string"
  },
  "lastSyncedAt": {
    "property1": "string",
    "property2": "string"
  },
  "source": "string",
  "products": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "name": "Summer Collection"
    }
  ],
  "channelPublishes": [
    {
      "salesChannel": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "My storefront",
        "connectionId": "vc_9f3a2b1c8d7e6f5a"
      },
      "connection": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "My storefront",
        "connectionId": "vc_9f3a2b1c8d7e6f5a"
      }
    }
  ],
  "vibeCodedPublishes": [
    {
      "salesChannel": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "My storefront",
        "connectionId": "vc_9f3a2b1c8d7e6f5a"
      },
      "connection": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "My storefront",
        "connectionId": "vc_9f3a2b1c8d7e6f5a"
      }
    }
  ],
  "_count": {
    "values": 0
  },
  "translations": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions/{id}"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions/{id}"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions/{id}"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions/{id}"
}

Delete a metafield definition

Supports Idempotency-Key header for safe retries.

DELETE
/v1/metafield-definitions/{id}

Authorization

AuthorizationBearer <token>

Admin API key (server-to-server). Issue via the dashboard at Settings → Authentication → API Keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.

In: header

Path Parameters

idstring

Metafield Definition ID

Header Parameters

Idempotency-Key?string

Client-supplied key (a UUID v4 is the recommended form, max 255 characters) that makes this mutation safe to retry.

  • Replay window: 24 hours. The first response for a key is cached; a retry inside the window with the same request body returns the original status and body without re-running the handler.
  • Reusing a key with a different body returns 409 Conflict with code: "IDEMPOTENCY_KEY_REUSED". The request fingerprint (method + path + body hash) is compared against the stored one; a mismatch is refused rather than served the old response.
  • Keys are scoped to the calling credential and store — two API keys may safely use the same key value.
  • Error responses are cached too, so a retry of a request that failed validation returns the same 400 immediately.
  • Sending this header on a GET returns 400 with code: "IDEMPOTENCY_KEY_NOT_SUPPORTED" — GETs are already idempotent.
  • Support is per-route and this parameter is the authoritative signal: a key sent to a route that does not declare it is accepted and silently ignored.

See /docs/api/idempotency.

Lengthlength <= 255
curl -X DELETE "https://api.brainerce.com/api/v1/metafield-definitions/string" \  -H "Idempotency-Key: string"
Empty

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions/{id}"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions/{id}"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions/{id}"
}

Replace platform publishing configuration

Supports Idempotency-Key header for safe retries.

PUT
/v1/metafield-definitions/{id}/platforms

Authorization

AuthorizationBearer <token>

Admin API key (server-to-server). Issue via the dashboard at Settings → Authentication → API Keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.

In: header

Path Parameters

idstring

Metafield Definition ID

Header Parameters

Idempotency-Key?string

Client-supplied key (a UUID v4 is the recommended form, max 255 characters) that makes this mutation safe to retry.

  • Replay window: 24 hours. The first response for a key is cached; a retry inside the window with the same request body returns the original status and body without re-running the handler.
  • Reusing a key with a different body returns 409 Conflict with code: "IDEMPOTENCY_KEY_REUSED". The request fingerprint (method + path + body hash) is compared against the stored one; a mismatch is refused rather than served the old response.
  • Keys are scoped to the calling credential and store — two API keys may safely use the same key value.
  • Error responses are cached too, so a retry of a request that failed validation returns the same 400 immediately.
  • Sending this header on a GET returns 400 with code: "IDEMPOTENCY_KEY_NOT_SUPPORTED" — GETs are already idempotent.
  • Support is per-route and this parameter is the authoritative signal: a key sent to a route that does not declare it is accepted and silently ignored.

See /docs/api/idempotency.

Lengthlength <= 255

Request Body

Empty Object

curl -X PUT "https://api.brainerce.com/api/v1/metafield-definitions/string/platforms" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{}'
{
  "id": "string",
  "accountId": "string",
  "storeId": "string",
  "name": "Warranty Info",
  "key": "warranty_info",
  "description": "string",
  "type": "string",
  "required": true,
  "isCustomerInput": true,
  "appliesToAllProducts": true,
  "filterable": true,
  "minLength": 0,
  "maxLength": 0,
  "minValue": 0,
  "maxValue": 0,
  "dateAvailability": {},
  "enumValues": [
    {
      "label": "string",
      "value": "string",
      "swatchColor": "string",
      "swatchImageUrl": "string"
    }
  ],
  "defaultValue": "string",
  "position": 0,
  "isActive": true,
  "publishedOn": [
    "SHOPIFY"
  ],
  "platformIds": {
    "property1": "string",
    "property2": "string"
  },
  "platformMetadata": {},
  "syncStatus": {
    "property1": "string",
    "property2": "string"
  },
  "lastSyncedAt": {
    "property1": "string",
    "property2": "string"
  },
  "source": "string",
  "products": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "name": "Summer Collection"
    }
  ],
  "channelPublishes": [
    {
      "salesChannel": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "My storefront",
        "connectionId": "vc_9f3a2b1c8d7e6f5a"
      },
      "connection": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "My storefront",
        "connectionId": "vc_9f3a2b1c8d7e6f5a"
      }
    }
  ],
  "vibeCodedPublishes": [
    {
      "salesChannel": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "My storefront",
        "connectionId": "vc_9f3a2b1c8d7e6f5a"
      },
      "connection": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "My storefront",
        "connectionId": "vc_9f3a2b1c8d7e6f5a"
      }
    }
  ],
  "_count": {
    "values": 0
  },
  "translations": {},
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions/{id}/platforms"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions/{id}/platforms"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions/{id}/platforms"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/metafield-definitions/{id}/platforms"
}

Get metafields for a product

GET
/v1/products/{productId}/metafields

Authorization

AuthorizationBearer <token>

Admin API key (server-to-server). Issue via the dashboard at Settings → Authentication → API Keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.

In: header

Path Parameters

productIdstring

Product ID

curl -X GET "https://api.brainerce.com/api/v1/products/string/metafields"
[
  {
    "id": "string",
    "productId": "string",
    "variantId": "string",
    "metafieldDefinitionId": "string",
    "value": "string",
    "translations": {},
    "syncStatus": {},
    "source": "string",
    "lastModifiedBy": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z",
    "definition": {
      "id": "string",
      "accountId": "string",
      "storeId": "string",
      "name": "string",
      "key": "string",
      "description": "string",
      "type": "string",
      "required": true,
      "minLength": 0,
      "maxLength": 0,
      "minValue": "string",
      "maxValue": "string",
      "enumValues": {},
      "defaultValue": "string",
      "dateAvailability": {},
      "isActive": true,
      "isCustomerInput": true,
      "appliesToAllProducts": true,
      "filterable": true,
      "position": 0,
      "publishedOn": [
        "string"
      ],
      "platformIds": {},
      "platformMetadata": {},
      "syncStatus": {},
      "lastSyncedAt": {},
      "source": "string",
      "translations": {},
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  }
]

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/products/{productId}/metafields"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/products/{productId}/metafields"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/products/{productId}/metafields"
}

Upsert a product metafield value

Supports Idempotency-Key header for safe retries.

PUT
/v1/products/{productId}/metafields/{definitionId}

Authorization

AuthorizationBearer <token>

Admin API key (server-to-server). Issue via the dashboard at Settings → Authentication → API Keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.

In: header

Path Parameters

productIdstring

Product ID

definitionIdstring

Metafield Definition ID

Header Parameters

Idempotency-Key?string

Client-supplied key (a UUID v4 is the recommended form, max 255 characters) that makes this mutation safe to retry.

  • Replay window: 24 hours. The first response for a key is cached; a retry inside the window with the same request body returns the original status and body without re-running the handler.
  • Reusing a key with a different body returns 409 Conflict with code: "IDEMPOTENCY_KEY_REUSED". The request fingerprint (method + path + body hash) is compared against the stored one; a mismatch is refused rather than served the old response.
  • Keys are scoped to the calling credential and store — two API keys may safely use the same key value.
  • Error responses are cached too, so a retry of a request that failed validation returns the same 400 immediately.
  • Sending this header on a GET returns 400 with code: "IDEMPOTENCY_KEY_NOT_SUPPORTED" — GETs are already idempotent.
  • Support is per-route and this parameter is the authoritative signal: a key sent to a route that does not declare it is accepted and silently ignored.

See /docs/api/idempotency.

Lengthlength <= 255

Request Body

Empty Object

curl -X PUT "https://api.brainerce.com/api/v1/products/string/metafields/string" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{}'
{
  "id": "string",
  "productId": "string",
  "variantId": "string",
  "metafieldDefinitionId": "string",
  "value": "string",
  "translations": {},
  "syncStatus": {},
  "source": "string",
  "lastModifiedBy": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "definition": {
    "id": "string",
    "accountId": "string",
    "storeId": "string",
    "name": "string",
    "key": "string",
    "description": "string",
    "type": "string",
    "required": true,
    "minLength": 0,
    "maxLength": 0,
    "minValue": "string",
    "maxValue": "string",
    "enumValues": {},
    "defaultValue": "string",
    "dateAvailability": {},
    "isActive": true,
    "isCustomerInput": true,
    "appliesToAllProducts": true,
    "filterable": true,
    "position": 0,
    "publishedOn": [
      "string"
    ],
    "platformIds": {},
    "platformMetadata": {},
    "syncStatus": {},
    "lastSyncedAt": {},
    "source": "string",
    "translations": {},
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/products/{productId}/metafields/{definitionId}"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/products/{productId}/metafields/{definitionId}"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/products/{productId}/metafields/{definitionId}"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/products/{productId}/metafields/{definitionId}"
}

Delete a product metafield value

Supports Idempotency-Key header for safe retries.

DELETE
/v1/products/{productId}/metafields/{definitionId}

Authorization

AuthorizationBearer <token>

Admin API key (server-to-server). Issue via the dashboard at Settings → Authentication → API Keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.

In: header

Path Parameters

productIdstring

Product ID

definitionIdstring

Metafield Definition ID

Query Parameters

variantId?string

Header Parameters

Idempotency-Key?string

Client-supplied key (a UUID v4 is the recommended form, max 255 characters) that makes this mutation safe to retry.

  • Replay window: 24 hours. The first response for a key is cached; a retry inside the window with the same request body returns the original status and body without re-running the handler.
  • Reusing a key with a different body returns 409 Conflict with code: "IDEMPOTENCY_KEY_REUSED". The request fingerprint (method + path + body hash) is compared against the stored one; a mismatch is refused rather than served the old response.
  • Keys are scoped to the calling credential and store — two API keys may safely use the same key value.
  • Error responses are cached too, so a retry of a request that failed validation returns the same 400 immediately.
  • Sending this header on a GET returns 400 with code: "IDEMPOTENCY_KEY_NOT_SUPPORTED" — GETs are already idempotent.
  • Support is per-route and this parameter is the authoritative signal: a key sent to a route that does not declare it is accepted and silently ignored.

See /docs/api/idempotency.

Lengthlength <= 255
curl -X DELETE "https://api.brainerce.com/api/v1/products/string/metafields/string?variantId=string" \  -H "Idempotency-Key: string"
Empty

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/products/{productId}/metafields/{definitionId}"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/products/{productId}/metafields/{definitionId}"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/products/{productId}/metafields/{definitionId}"
}

Attributes

Previous Page

Shipping

Next Page

On this page

No Headings