Artists API

Artists represent a list of all artist categories in a store, used for grouping products together (similar to Categories).

This must be enabled by the account! Artist categories are a specialized feature, so every account has it disabled by default. If an account doesn’t have artist categories enabled, you can expect to receive a 403 Forbidden response with an error message containing a code of account.artists-disabled when making the following requests.

Artist object

Attribute Type Description
id string The unique identifier for the artist.
name string The name of the artist.
permalink string The unique permalink for the artist.
position string The position in which the artist is arranged.

Get all artists

Get all artists for an account.

GET /v1/accounts/{account-id}/artists
{
  "data": [
    {
      "id": "1",
      "type": "artists",
      "attributes": {
        "name": "Example Artist 1",
        "permalink": "example-artist-1",
        "position": 1
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/artists/1"
      }
    },
    {
      "id": "2",
      "type": "artists",
      "attributes": {
        "name": "Example Artist 2",
        "permalink": "example-artist-2",
        "position": 2
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/artists/2"
      }
    }
  ],
  "meta": {
    "count": "2"
  }
}

Parameters

None.

Get an artist

Get a specific artist for an account.

GET /v1/accounts/{account-id}/artists/{artist-id}
{
  "data": {
    "id": "1",
    "type": "artists",
    "attributes": {
      "name": "Example Artist 1",
      "permalink": "example-artist-1",
      "position": 1
    },
    "links": {
      "self": "https://api.bigcartel.com/v1/accounts/1/artists/1"
    }
  }
}

Parameters

None.

Create an artist

Creates a new artist.

POST /v1/accounts/{account-id}/artists

Parameters

Name Type Required Description
type string true The only option right now is artists.
name string true The name of the artist.

Example request

{
  "data": {
    "type": "artists",
    "attributes": {
      "name": "New Example Artist"
    }
  }
}

Response

If successful, we’ll return a 201 Created with the location of the new artist in the Location header and the same body as getting the artist.

Update an artist

Updates a specific artist’s details.

PATCH /v1/accounts/{account-id}/artists/{artist-id}

Parameters

Name Type Required Description
id string true The unique identifier for the artist.
type string true The only option right now is artists.
name string true The name of the artist.

Example request

Update an artist name

{
  "data": {
    "id": "1",
    "type": "artists",
    "attributes": {
      "name": "Updated Example Artist 1"
    }
  }
}

Response

If successful, we’ll return a 200 OK and the same body as getting the artist.

Delete an artist

Deletes a specific artist.

DELETE /v1/accounts/{account-id}/artists/{artist-id}

Parameters

Name Type Required Description
id string true The unique identifier for the artist.
type string true The only option right now is artists.

If successful, we’ll return a 204 No Content response.

Reposition artists

Repositions the list of artists in the specified order.

PATCH /v1/accounts/{account-id}/relationships/artists

Parameters

Name Type Required Description
type string true The only option right now is artists.
id string true The unique identifier for the artist.

Example request

Reposition a list of artists.

{
  "data": [
    {
      "type": "artists",
      "id": "1"
    },
    {
      "type": "artists",
      "id": "3"
    },
    {
      "type": "artists",
      "id": "2"
    }
  ]
}

If successful, we’ll return a 204 No Content response.