Private API reference

Metafield

Private Metafield API endpoints

Endpoints

GET/metafields
POST/metafields
PATCH/metafields/{metafield_slug}

Get shop's metafields

GET /metafields

Retrieves a paginated list of shop's metadata.

Query parameters

pageoptionalinteger

Page number for pagination

per_pageoptionalinteger

Entities per page

idsoptionalinteger[]

Filter by metadata by IDs. Values must be unique.

slugsoptionalstring[]

Filter by metadata by slugs. Values must be unique.

presetoptionalboolean

Filter by metadata preset

variantoptionalboolean

Filter by metadata variant type

sort[field]optionalstring

Field to sort by. Required whenever any sort key is sent.

Possible values: id, name.

sort[direction]optionalstring

Sort direction; defaults to asc.

Possible values: asc, desc.

Defaults to "asc".

Returnsobject

Successful response

Error responses

422object

A query parameter failed validation: ids or slugs is not an array, an ID is not an integer, a slug is longer than 255 characters, page is below 1, per_page is outside 1 to 100, preset or variant is not a boolean, sort[direction] comes without sort[field], or the sort field or direction is unknown.

curl https://api.subbly.co/private/v1/metafields \
  -H 'X-API-KEY: <api-key>'

Response

{
  "pagination": {
    "current_page": 1,
    "last_page": 2,
    "from": 1,
    "to": 1,
    "total": 20
  },
  "data": [
    {
      "id": 1,
      "name": "Color",
      "slug": "color-red",
      "description": "description",
      "unit": "kg",
      "data_type": "single_line_string",
      "preset": true,
      "multiple": true,
      "access_level": "storefront",
      "save_behavior": "customer",
      "editable": true,
      "values": [
        {
          "id": 1,
          "value": "value"
        }
      ]
    }
  ]
}

Create a new metadata

POST /metafields

Request body

nameRequiredstring

Metadata name. Must not slugify to a value ending in subbly-variant; that suffix is reserved.

descriptionoptionalstring | null

Free‐form description

multipleoptionalboolean

Allow multiple values. May only be true when data_type is one of single_line_string, integer, decimal, datetime, date, time, volume, weight, color, url. Otherwise the request is rejected.

data_typeRequiredstring

Data type for the metadata

Possible values: single_line_string, multi_line_text, rich_text, integer, decimal, datetime, date, time, volume, weight, boolean, color, rating, url, money, json.

access_levelRequiredstring

Who can see/use this metadata

Possible values: storefront, private.

presetoptionalboolean

Values come from a preset list. May only be true when data_type is one of single_line_string, color, time, integer, rating, decimal, money, volume, weight, date, datetime. Otherwise the request is rejected.

unitoptionalstring

Unit label. Required when data_type is volume or weight; prohibited (422) for every other data_type.

save_behavioroptionalstring

Save behavior for the metadata. Defaults to subscription.

Possible values: customer, subscription.

editableoptionalboolean

Whether the metadata value is editable by the customer. Defaults to true.

valuesoptionalobject[] | null

List of allowed values (when preset is true)

ReturnsMetadata

Metadata created successfully

Error responses

422object

name is missing, not a string, or slugifies to a value that ends in subbly-variant (The name should not end with "subbly-variant".); data_type or access_level is missing or unknown; save_behavior is unknown; multiple or preset is true for a data type that does not support it (The multiple is invalid., The preset is invalid.); unit is missing for volume or weight, or sent for any other data type; values is sent without preset, holds duplicates, or holds a value that does not fit the data type; or a values[].value is missing.

curl -X POST https://api.subbly.co/private/v1/metafields \
  -H 'X-API-KEY: <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "name",
  "description": "description",
  "multiple": true,
  "data_type": "single_line_string",
  "access_level": "storefront",
  "preset": true,
  "unit": "unit",
  "save_behavior": "customer",
  "editable": true,
  "values": [
    {
      "value": "value"
    }
  ]
}'

Response

{
  "id": 1,
  "name": "Color",
  "slug": "color-red",
  "description": "description",
  "unit": "kg",
  "data_type": "single_line_string",
  "preset": true,
  "multiple": true,
  "access_level": "storefront",
  "save_behavior": "customer",
  "editable": true,
  "values": [
    {
      "id": 1,
      "value": "value"
    }
  ]
}

Update the metadata

PATCH /metafields/{metafield_slug}

Partially updates the metadata and its values by metadata slug. Variant metafields cannot be updated; the request is rejected with 403.

Path parameters

metafield_slugRequiredstring

The unique slug of the metadata to update

Request body

Fields to update on the metadata

nameoptionalstring

New name of the metadata. Must not slugify to a value ending in subbly-variant; that suffix is reserved.

descriptionoptionalstring | null

Detailed description

access_leveloptionalstring

Access scope for the metadata

Possible values: storefront, private.

unitoptionalstring

Unit of measurement. Required on every update request when the metafield's data_type is volume or weight (resend the current value if unchanged); prohibited for all other data types.

save_behavioroptionalstring

Save behavior for the metadata.

Possible values: customer, subscription.

editableoptionalboolean

Whether the metadata value is editable by the customer.

valuesoptionalobject | null

Operations on preset values

ReturnsMetadata

Metadata updated successfully

Error responses

400object

The metafield belongs to another shop, or is a variant metafield and therefore not updatable.

curl -X PATCH https://api.subbly.co/private/v1/metafields/{metafield_slug} \
  -H 'X-API-KEY: <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "name",
  "description": "description",
  "access_level": "storefront",
  "unit": "unit",
  "save_behavior": "customer",
  "editable": true,
  "values": {
    "create": [
      {
        "value": "value"
      }
    ],
    "update": [
      {
        "id": 1,
        "value": "value"
      }
    ],
    "delete": [
      {
        "id": 1
      }
    ]
  }
}'

Response

{
  "id": 1,
  "name": "Color",
  "slug": "color-red",
  "description": "description",
  "unit": "kg",
  "data_type": "single_line_string",
  "preset": true,
  "multiple": true,
  "access_level": "storefront",
  "save_behavior": "customer",
  "editable": true,
  "values": [
    {
      "id": 1,
      "value": "value"
    }
  ]
}