Introducing our brand new Rules Engine —
Read the docs
LogoLogo
Core APIOther APIsChangelog
Getting started
Getting started
  • Welcome to Commerce Layer
    • Guided setup
    • Manual configuration
  • API specification
  • API credentials
  • Authentication
    • Client credentials
    • Password
    • Authorization code
    • Refresh token
    • JWT bearer
    • Revoking a token
  • Roles and permissions
  • Fetching resources
  • Fetching relationships
  • Including associations
  • Sparse fieldsets
  • Sorting results
  • Pagination
  • Filtering data
  • Creating resources
  • Updating resources
  • Tagging resources
  • Deleting resources
  • Importing resources
  • Exporting resources
  • Cleaning up resources
  • External resources
    • External order validation
    • External prices
    • External shipping costs
    • External payment gateways
    • External promotions
    • External tax calculators
  • Rate limits
  • Handling errors
  • Real-time webhooks
  • Callbacks security
On this page
  • Example
  • Removing tags
  • Example
  • Updating the list of tags
  • Example

Tagging resources

How to tag a resource via API

PreviousUpdating resourcesNextDeleting resources

Last updated 2 months ago

can be tagged using one or more existing . To do that, you need to update the resource setting the relationship with the desired tag(s).

A maximum of 10 tags is allowed for each single resource object.

Example

The following request tags the resource identified by the "xYZkjABcde" ID with the two tags identified by the "geJmexflJQ" and "mWJAPvfBaV" IDs:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/skus/xYZkjABcde' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "skus",
      "id": "xYZkjABcde",
      "relationships": {
        "tags": {
          "data": [
            {
              "type": "tags",
              "id": "geJmexflJQ"
            },
            {
              "type": "tags",
              "id": "mWJAPvfBaV"
            }
          ]
        }
      }
    }
  }'

On success, the API responds with a 200 OK status code, returning the updated resource object:

{
  "data": {
    "id": "xYZkjABcde",
    "type": "skus",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/skus/xYZkjABcde"
    },
    "attributes": {
      "code": "TSHIRTMS000000FFFFFFLXXX",
      "name": "Men's Black T-Shirt with White Logo (L)",
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
      "image_url": "https://img.yourdomain.com/skus/xYZkjABcde.png",
      "pieces_per_pack": null,
      "weight": null,
      "unit_of_weight": null,
      "hs_tariff_number": null,
      "do_not_ship": false,
      "do_not_track": false,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "reference_origin": "ANYREFEFERNCEORIGIN",
      "metadata": {}
    },
    "relationships": {
      "shipping_category": { ... },
      "prices": { ... },
      "stock_items": { ... },
      "delivery_lead_times": { ... },
      "sku_options": { ... },
      "attachments": { ... },
      "events": { ... },
      "tags": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/skus/xYZkjABcde/relationships/tags",
          "related": "https://yourdomain.commercelayer.io/api/skus/xYZkjABcde/tags"
        }
      }
    },
    "meta": {
      "mode": "test",
      "organization_id": "YyrQYFzERk"
    }
}
}

Removing tags

To remove one or more tags from a resource you need to update the resource setting the relationship with the updated list of tags. To remove all the tags from a resource, just set the tags relationship as an empty array.

Example

The following request removes all the tags associated with the resource identified by the "xYZkjABcde" ID:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/skus/xYZkjABcde' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "skus",
      "id": "xYZkjABcde",
      "relationships": {
        "tags": {
          "data": []
        }
      }
    }
  }'

On success, the API responds with a 200 OK status code, returning the updated resource object:

{
  "data": {
    "id": "xYZkjABcde",
    "type": "skus",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/skus/xYZkjABcde"
    },
    "attributes": {
      "code": "TSHIRTMS000000FFFFFFLXXX",
      "name": "Men's Black T-Shirt with White Logo (L)",
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
      "image_url": "https://img.yourdomain.com/skus/xYZkjABcde.png",
      "pieces_per_pack": null,
      "weight": null,
      "unit_of_weight": null,
      "hs_tariff_number": null,
      "do_not_ship": false,
      "do_not_track": false,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "reference_origin": "ANYREFEFERNCEORIGIN",
      "metadata": {}
    },
    "relationships": {
      "shipping_category": { ... },
      "prices": { ... },
      "stock_items": { ... },
      "delivery_lead_times": { ... },
      "sku_options": { ... },
      "attachments": { ... },
      "events": { ... },
      "tags": { ... }
    },
    "meta": {
      "mode": "test",
      "organization_id": "YyrQYFzERk"
    }
  }
}

Updating the list of tags

Example

The following request changes the list of tags associated with the resource identified by the "xYZkjABcde" ID:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/skus/xYZkjABcde' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "skus",
      "id": "xYZkjABcde",
      "attributes": {
        "_add_tags": "out-of-stock,old-collection",
        "_remove_tags": "new-collection,vip"
      }
    }
  }'

On success, the API responds with a 200 OK status code, returning the updated resource object:

{
  "data": {
    "id": "xYZkjABcde",
    "type": "skus",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/skus/xYZkjABcde"
    },
    "attributes": {
      "code": "TSHIRTMS000000FFFFFFLXXX",
      "name": "Men's Black T-Shirt with White Logo (L)",
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
      "image_url": "https://img.yourdomain.com/skus/xYZkjABcde.png",
      "pieces_per_pack": null,
      "weight": null,
      "unit_of_weight": null,
      "hs_tariff_number": null,
      "do_not_ship": false,
      "do_not_track": false,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "reference_origin": "ANYREFEFERNCEORIGIN",
      "metadata": {}
    },
    "relationships": {
      "shipping_category": { ... },
      "prices": { ... },
      "stock_items": { ... },
      "delivery_lead_times": { ... },
      "sku_options": { ... },
      "attachments": { ... },
      "events": { ... },
      "tags": { ... }
    },
    "meta": {
      "mode": "test",
      "organization_id": "YyrQYFzERk"
    }
  }
}

automatically removes any existing association.

If a resource is already associated with one or more tags, tagging the resource by will remove all the currently associated tags and replace them with the new list of tags. If you just need to change the list of the tags currently associated with a resource, you can patch the taggable resource and send the trigger attributes _add_tags and/or _remove_tags specifying the comma-separated list of tag names that you want to add and/or remove.

The specified names must belong to existing tags, meaning that the related tags must be previously . The provided tags are automatically and non-existing ones are ignored and not associated with the resource without returning any errors.

The two trigger attributes can be sent within the same PATCH request (i.e. adding some tags and removing some others in just one API call — ). In that case, remember that tag removal is always performed after tag addition.

updating the relationship
see example
Updating resources
Most of Commerce Layer's resources
tags
Deleting a tag
created
validated