Products API

Products represent a list of all products in a store.

Product object

Attribute Type Description
id string The unique identifier for the product.
name string The name of the product.
permalink string The unique permalink for the product.
status string The status of the product. Possible values are active, hidden, sold_out, or coming_soon.
description string The description of the product.
created_at timestamp When the product was created.
updated_at timestamp When the product was last updated.
default_price decimal The default price of the product.
on_sale boolean Whether or not the product is on sale.
position integer The position in which the product is arranged.
url string The full URL to access the product.
primary_image_url string The primary image URL of the product.
options[].id integer The unique identifier for the product option.
options[].name string The name of the product option.
options[].price decimal The price of the product option.
options[].quantity integer The quantity in stock of the product option.
options[].sold integer The number of times the product option has been sold.
artists[].id integer The unique identifier for the artist.
artists[].name string The name of the artist.
artists[].permalink string The unique permalink for the artist.
artists[].position string The position in which the artist is arranged.
categories[].id integer The unique identifier for the category.
categories[].name string The name of the category.
categories[].permalink string The unique permalink for the category.
categories[].position string The position in which the category is arranged.
shipping_options[].id integer The unique identifier for the shipping option.
shipping_options[].price_alone decimal The shipped alone amount for the shipping area.
shipping_options[].price_with_others decimal The shipped with others amount for the shipping area.
shipping_options[].country.id string The unique 2-letter code for the product shipping area’s country.
images[].id integer The unique identifier for product image.
images[].url string The customizable URL of the product image.

Get all products

Get all products for an account.

GET /v1/accounts/{account-id}/products
{
  "data": [
    {
      "id": "1",
      "type": "products",
      "attributes": {
        "name": "Product Name",
        "permalink": "product-name",
        "status": "active",
        "description": "This is a sample product description",
        "created_at": "2014-12-25T00:00:00.000Z",
        "updated_at": "2014-12-25T00:00:00.000Z",
        "default_price": "20.0",
        "on_sale": false,
        "position": 1,
        "url": "http://example.bigcartel.com/product/product-name",
        "primary_image_url": "https://images.bigcartel.com/some_resource/12345/-/example1.jpg"
      },
      "relationships": {
        "options": {
          "data": [
            {
              "type": "product_options",
              "id": "1"
            }
          ]
        },
        "categories": {
          "data": [
            {
              "type": "categories",
              "id": "1"
            }
          ]
        },
        "artists": {
          "data": [
            {
              "type": "artists",
              "id": "1"
            }
          ]
        },
        "shipping_options": {
          "data": [
            {
              "type": "shipping_options",
              "id": "1"
            }
          ]
        },
        "images": {
          "data": [
            {
              "type": "product_images",
              "id": "1"
            },
            {
              "type": "product_images",
              "id": "2"
            }
          ]
        }
      }
    }
  ],
  "meta": {
    "count": "10"
  },
  "included": [
    {
      "id": "1",
      "type": "product_options",
      "attributes": {
        "name": "Default",
        "price": "18.0",
        "quantity": 25,
        "sold": 5
      }
    },
    {
      "id": "1",
      "type": "categories",
      "attributes": {
        "name": "Example Category",
        "permalink": "example-category",
        "position": 1
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/categories/1"
      }
    },
    {
      "id": "1",
      "type": "artists",
      "attributes": {
        "name": "Example artist",
        "permalink": "example-artist",
        "position": 1
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/artists/1"
      }
    },
    {
      "id": "1",
      "type": "shipping_options",
      "attributes": {
        "price_alone": "10.0",
        "price_with_others": "5.0"
      },
      "relationships": {
        "country": {
          "data": {
            "type": "countries",
            "id": "US"
          }
        }
      }
    },
    {
      "id": "1",
      "type": "product_images",
      "attributes": {
        "url": "https://images.bigcartel.com/some_resource/12345/-/example1.jpg"
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/product_images/1"
      }
    },
    {
      "id": "2",
      "type": "product_images",
      "attributes": {
        "url": "https://images.bigcartel.com/some_resource/12345/-/example2.jpg"
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/product_images/2"
      }
    }
  ],
  "links": {
    "next": "https://api.bigcartel.com/v1/accounts/1/products?page%5Blimit%5D=10&page%5Boffset%5D=10",
    "last": "https://api.bigcartel.com/v1/accounts/1/products?page%5Blimit%5D=10&page%5Boffset%5D=10"
  }
}

Parameters

Name Type Required Description
filter string false Filter products using status, category_id, or artist_id. Each attribute allows a comma separated list of values.
sort string false Sort products using the specified attribute, in ascending order by default. Prefix the value with - to specify descending order. Allowed values are position (default), created_at, and updated_at.
Filter examples

Use status to filter products using active, coming_soon, hidden, or sold_out.

GET /v1/accounts/{account-id}/products?filter[status]=sold_out

Use category_id to filter products by category.

GET /v1/accounts/{account-id}/products?filter[category_id]=1,2,3

Use artist_id to filter products by artist.

GET /v1/accounts/{account-id}/products?filter[artist_id]=1,2,3

Get a product

Get a specific product for an account.

GET /v1/accounts/{account-id}/products/{product-id}
{
  "data": {
    "id": "1",
    "type": "products",
    "attributes": {
      "name": "Product Name",
      "permalink": "product-name",
      "status": "active",
      "description": "This is a sample product description",
      "created_at": "2014-12-25T00:00:00.000Z",
      "updated_at": "2014-12-25T00:00:00.000Z",
      "default_price": "20.0",
      "on_sale": false,
      "position": 1,
      "url": "http://example.bigcartel.com/product/product-name",
      "primary_image_url": "https://images.bigcartel.com/some_resource/12345/-/example1.jpg"
    },
    "relationships": {
      "options": {
        "data": [
          {
            "type": "product_options",
            "id": "1"
          }
        ]
      },
      "categories": {
        "data": [
          {
            "type": "categories",
            "id": "1"
          }
        ]
      },
      "shipping_options": {
        "data": [
          {
            "type": "shipping_options",
            "id": "1"
          }
        ]
      },
      "images": {
        "data": [
          {
            "type": "product_images",
            "id": "1"
          },
          {
            "type": "product_images",
            "id": "2"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "1",
      "type": "product_options",
      "attributes": {
        "name": "Default",
        "price": "18.0",
        "quantity": 25,
        "sold": 5
      }
    },
    {
      "id": "1",
      "type": "categories",
      "attributes": {
        "name": "Example Category",
        "permalink": "example-category",
        "position": 1
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/categories/1"
      }
    },
    {
      "id": "1",
      "type": "shipping_options",
      "attributes": {
        "price_alone": "10.0",
        "price_with_others": "5.0"
      },
      "relationships": {
        "country": {
          "data": {
            "type": "countries",
            "id": "US"
          }
        }
      }
    },
    {
      "id": "1",
      "type": "product_images",
      "attributes": {
        "url": "https://images.bigcartel.com/some_resource/12345/-/example1.jpg"
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/product_images/1"
      }
    },
    {
      "id": "2",
      "type": "product_images",
      "attributes": {
        "url": "https://images.bigcartel.com/some_resource/12345/-/example2.jpg"
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/product_images/2"
      }
    }
  ]
}

Parameters

None.

Reposition products

Repositions the list of products in the specified order.

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

Parameters

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

Example request

Reposition a list of products.

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

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