Introduction

Our API makes it possible for anyone to make awesome things for Big Cartel’s massive community of artists. Integrate Big Cartel into an existing application or service, create an add-on to extend our core features, or code something up you’d like in your own shop. Whatever it is, we hope these tools allow you to build something great.

Versioning

The current version of the Big Cartel API is V1, and that version number is specified in all endpoints (e.g. /v1/accounts/123). Updates made to the V1 API will always be backwards-compatible, and listed with a datestamp in our API Changelog.

Status Codes

Our API returns HTTP status codes for every request. Here are some examples of typical responses you can expect to receive:

Code Status
200 Everything worked as expected.
201 Created - a new resource was created.
400 Bad Request - missing or invalid parameters.
401 Unauthorized - invalid API credentials.
402 Request Failed - valid parameters, but the request failed.
404 Not Found - requested item doesn’t exist.
5xx Server Error - something is wrong on our end.

Pagination

Requests that return multiple objects will be limited to 20 items by default. The documentation for each endpoint will tell you which objects support pagination, and you can specify further pages using limit and offset inside the page parameter.

Images

Any image URL attribute returned from an endpoint in our API will be include a default size. However, you’d probably like a version optimized for your application. Fortunately, Big Cartel can resize the image in any way you’d like.

Webhooks

Our API makes use of webhooks to notify your application of important changes that have occurred outside of your application for accounts you’ve connected to. You’ll also receive webhooks for changes you make with the API, but you shouldn’t need those since all API requests you make will receive a synchronous response.

Webhooks are currently an invite-only feature, and are only available when building an application that uses OAuth for authentication. If you’d like to take advantage of these features, please apply for an invite.

Types of webhooks

Type Payload Description
account.deauthorized id of the account Sent when an account has been closed or the owner has revoked access to your application.
account.updated Sent when an account is updated.
account.plan.downgraded Sent when an account is downgraded.
account.plan.upgraded Sent when an account is upgraded.
order.created order Sent when a new order is placed.
order.updated order Sent when an order changes.
product.created product Sent when a new product is created.
product.updated product Sent when a product is updated, either by the account or when it’s part of a new order.
product.deleted product Sent when a product is deleted. This payload will only include the product id instead of the full product object.

Receiving webhooks

Webhooks will be sent as an HTTP POST request to the webhook_url for your application in the following JSON format:

Verifying webhooks

In order to ensure the webhook you received is legit, we suggest you verify its signature. To do that, create an HMAC signed using the SHA256 hash algorithm, using your application’s client_secret and the body of the webhook request as keys, and make sure it matches the webhook’s X-Webhook-Signature header.

Responding to webhooks

To acknowledge you received the webhook without any problem, your server should return a 2xx HTTP status code. Any response code other than that will tell Big Cartel that you didn’t receive the webhook, and we’ll continue to retry it at degrading intervals for the next 7 days.

Rate Limiting

Our API doesn’t currently limit the number of requests in a given time period, but rate limiting will be added in the future. For now, please use the API responsibly, and use webhooks to know when an update happens instead of polling regularly.

OAuth

The Big Cartel API uses OAuth 2.0 to provide your application with access to an account without the need for sharing or storing passwords. To do this, you’ll redirect your user to Big Cartel, they’ll login and see a page explaining exactly who wants access and what they’ll have access to. After allowing or denying your request, they’ll be sent back to your site.

Using an OAuth library

Since OAuth is a common and open protocol, there are already a number of projects that make it easy to use without much work on your part.

  1. Grab an OAuth library.
  2. Configure it with your client_id, client_secret, and redirect_uri.
  3. Tell it to use https://my.bigcartel.com/oauth/authorize to request authorization and https://api.bigcartel.com/oauth/token to get access tokens.

That’s it! You can now use your access_token to make API calls.

OAuth from scratch

If you’re the type that likes to have full control over your code, and don’t mind reinventing a wheel now and then, you can create your own OAuth integration.

1. Redirect the user to Big Cartel to request access

To connect your application to a Big Cartel account, redirect them to our authorization page which will prompt them to give you access to their account.

GET https://my.bigcartel.com/oauth/authorize

Parameters

Name Type Required Description
client_id string true Your unique client identifier from your application settings.
response_type string false The only option right now is code.
state string false An arbitrary value, sent back with each response (useful for identifying users on your end).
redirect_uri string false URL where your users are sent after authorization.

2. Big Cartel redirects back to your site

If the user accepts your request, they’ll be redirected to your redirect_uri with a temporary code in a code parameter as well as the state you may have provided in the previous step in a state parameter. If the states don’t match what you expect, the request has been created by a third party and the process should be aborted.

If the user’s account is already connected to your application, they’ll be immediately redirected back to your redirect_uri in the same way as described above, instead of being prompted to allow or deny access.

If the user denies your request, they’ll be redirected to your redirect_uri with the an error parameter containing the appropriate error code.

3. Exchange the temporary code for an access token

You’ll now need to make a request to trade the code you received for an access_token.

POST https://api.bigcartel.com/oauth/token

Parameters

Name Type Required Description
client_id string true Your unique client identifier from your application settings.
client_secret string true Your unique and private client secret from your application settings.
code string true The code parameter you received in the previous step.
redirect_uri string false URL where your users are sent after authorization.

Response

If successful, we’ll return a JSON response in the following format.

{
  "access_token":"YOUR-ACCESS-TOKEN",
  "token_type":"bearer",
  "account_id":12345
}

That’s it! You can now use your access_token to make API calls.

Making API calls

Once you’ve obtained an access_token for an account, you can use it in the Authorization header of all of your requests.

Authorization: Bearer YOUR-ACCESS-TOKEN

All of our endpoints begin with the root URL https://api.bigcartel.com, and require an Accept header of application/vnd.api+json. When making a request that includes a JSON body, we also require that you send a Content-type header of application/vnd.api+json.

Revoking access

To revoke access to an account, send a POST request to our deauthorization endpoint and include the account ID.

This request requires that you use HTTP Basic authentication instead of OAuth - you’ll need to specify your application’s client_id for the username and client_secret for the password. If successful, you’ll receive a 204 No Content response.

OAuth errors

If at any point there are problems or invalid parameters in your request, we’ll send back an error code. Possible errors include:

Name Description
access_denied The user has denied access to their account.
invalid_client_id The client_id you specified is invalid.
invalid_client_secret The client_secret you specified is invalid.
invalid_redirect_uri The redirect_uri you specified is invalid.
invalid_response_type Your request’s response type is invalid.

Personal Projects

If you’d like to make a private integration just for yourself, you can do that without an invite by using HTTP Basic authentication with your store’s subdomain and password. Again though, this should only be for your own store, never ask anyone for their password!

Note that most endpoints require that you include an account ID when making a request. To find the account ID for your store, just make a request to the Account API and retrieve the id attribute from the response.

Identification

You must include a User-Agent header with the name of your application and a contact URL or email where you can be reached. This allows us to warn you if you’re doing something wrong before you get blacklisted, or feature you if you’re doing something awesome. If you don’t supply this header, you will get a 400 Bad Request response.

Account

Accounts are the primary resource of our API. These represent the shops on Big Cartel, and contain the core information and settings.

Account object

Attribute Type Description
id integer The unique identifier for the account.
subdomain string The unique subdomain for the account on .bigcartel.com.
store_name string The name of the shop.
description string A brief description of their shop.
contact_email string The email address the shop can be contacted at.
url string The URL of the online store, either using a custom domain or the default .bigcartel.com one.
website string The URL of a external website the account may have, separate from Big Cartel.
created_at timestamp When the account was created.
updated_at timestamp When the account was last updated.
under_maintenance boolean Whether or not the account is in maintenance mode.
inventory_enabled boolean Whether or not inventory tracking is enabled.
artists_enabled boolean Whether or not artist categories is enabled.
currency.id string The unique 3-letter code for the account’s currency.
currency.name string The name of the account’s currency.
currency.sign string The symbol used for the account’s currency.
currency.locale string The locale associated with the account’s currency.
country.id string The unique 2-letter code for the account’s country.
country.name string The name of the account’s country.
account_image.id integer The unique identifier for the account’s image.
account_image.url string The customizable URL of the account’s image.
plan.id string The unique identifier for the account’s plan. Possible values are gold, platinum, diamond, or titanium.
plan.name string The name of the account’s plan.
plan.max_products integer The maximum number of products the account can have on their plan.
plan.max_images_per_product integer The maximum number of images per product the account can have on their plan.
plan.monthly_rate decimal The rate the account is billed each month.

Get an account

Get the basic account information.

Request

GET /v1/accounts/{account-id}

Parameters

None.

Artists

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

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.

Request

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

Parameters

None.

Get an artist

Get a specific artist for an account.

Request

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

Parameters

None.

Create an artist

Creates a new artist.

Request

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.

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.

Request

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.

Response

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

Reposition artists

Repositions the list of artists in the specified order.

Request

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.

Response

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

Delete an artist

Deletes a specific artist.

Request

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

Parameters

None.

Response

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

Categories

Categories represent a list of all categories in a store, used for grouping products together.

Category object

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

Get all categories

Get all categories for an account.

Request

GET /v1/accounts/{account-id}/categories

Parameters

None.

Get a category

Get a specific category for an account.

Request

GET /v1/accounts/{account-id}/categories/{category-id}

Parameters

None.

Create a category

Creates a new category.

Request

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

Parameters

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

Response

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

Update a category

Updates a specific category’s details.

Request

PATCH /v1/accounts/{account-id}/categories/{category-id}

Parameters

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

Response

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

Reposition categories

Repositions the list of categories in the specified order.

Request

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

Parameters

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

Response

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

Delete a category

Deletes a specific category.

Request

DELETE /v1/accounts/{account-id}/categories/{category-id}

Parameters

None.

Response

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

Countries

Countries represent a list of all available countries used for shipping and billing addresses.

Country object

Attribute Type Description
id string The unique 2-letter code for the country.
name string The full name of the country.

Get all countries

Get a list of all countries sorted alphabetically by name.

Request

GET /v1/countries

Parameters

None.

Discounts

Discounts represent a list of all discounts in a store.

Discount object

Attribute Type Description
id string The unique identifier for the discount.
name string The name of the discount.
code string The code customers enter to use the discount.
active_at timestamp The date the discount is active.
expires_at timestamp The date the discount expires.
requirement_type string Possible values are any_order, minimum_cart_total, or minimum_cart_quantity.
expiration_type string Possible values are never, on_date, or on_limit.
reward_type string Possible values are percent_discount, flat_rate_discount, or free_shipping.
application_type string Possible values are all, category, or product.
percent_discount integer The percentage discount amount.
flat_rate_discount decimal The flat rate discount amount.
use_limit integer The limit for how many times the discount can be used.
use_count integer The number of times the discount has been used.
minimum_cart_total decimal The minimum cart total required to use the discount.
minimum_cart_quantity integer The minimum amount of items in the cart required to use the discount.

Get all discounts

Get all discounts for an account.

Request

GET /v1/accounts/{account-id}/discounts

Parameters

Name Type Required Description
filter string false Filter discounts using status

Status example

Use status to filter discounts with a status of active or expired.

GET /v1/accounts/{account-id}/discounts?filter[status]=active

Get a discount

Get a specific discount for an account.

Request

GET /v1/accounts/{account-id}/discounts/{discount-id}

Parameters

None.

Create a discount

Creates a new discount.

Request

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

Parameters

Name Type Required Description
type string true The only option right now is discounts.
name string true The name of the discount.
code string true The code customers enter to use the discount.
active_at timestamp true The date the discount is active.
expires_at timestamp false The date the discount expires. Must be a date in the future. Required when expiration_type is set to on_date.
requirement_type string true Possible values are any_order, minimum_cart_total, or minimum_cart_quantity.
expiration_type string true Possible values are never, on_date, or on_limit.
reward_type string true Possible values are percent_discount, flat_rate_discount, or free_shipping.
application_type string true Possible values are all, category, or product.
percent_discount integer false The percentage discount amount. Must be less than 100. Required when reward_type is set to percent_discount.
flat_rate_discount decimal false The flat rate discount amount. Required when reward_type is set to flat_rate_discount.
use_limit integer false The limit for how many times the discount can be used. Required when expiration_type is set to on_limit.
minimum_cart_total decimal false The minimum cart total required to use the discount. Required when requirement_type is set to minimum_cart_total.
minimum_cart_quantity integer false The minimum amount of items in the cart required to use the discount. Required when requirement_type is set to minimum_cart_quantity.

The following parameters are only required when creating a discount that applies to specific categories or products - application_type will also need to be set to category or product.

Name Type Required Description
category[].type string true The only option right now is categories.
category[].id integer true The unique identifier of the category.
product[].type string true The only option right now is products.
product[].id integer true The unique identifier of the product.

Response

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

Update a discount

Updates a specific discount’s details.

Request

PATCH /v1/accounts/{account-id}/discounts/{discount-id}

Parameters

Name Type Required Description
type string true The only option right now is discounts.
name string true The name of the discount.
code string true The code customers enter to use the discount.
active_at timestamp true The date the discount is active.
expires_at timestamp false The date the discount expires. Must be a date in the future. Required when expiration_type is set to on_date.
requirement_type string true Possible values are any_order, minimum_cart_total, or minimum_cart_quantity.
expiration_type string true Possible values are never, on_date, or on_limit.
reward_type string true Possible values are percent_discount, flat_rate_discount, or free_shipping.
application_type string true Possible values are all, category, or product.
percent_discount integer false The percentage discount amount. Must be less than 100. Required when reward_type is set to percent_discount.
flat_rate_discount decimal false The flat rate discount amount. Required when reward_type is set to flat_rate_discount.
use_limit integer false The limit for how many times the discount can be used. Required when expiration_type is set to on_limit.
minimum_cart_total decimal false The minimum cart total required to use the discount. Required when requirement_type is set to minimum_cart_total.
minimum_cart_quantity integer false The minimum amount of items in the cart required to use the discount. Required when requirement_type is set to minimum_cart_quantity.

The following parameters are only required when updating a discount that applies to specific categories or products - application_type will also need to be set to category or product.

Name Type Required Description
category[].type string true The only option right now is categories.
category[].id integer true The unique identifier of the category.
product[].type string true The only option right now is products.
product[].id integer true The unique identifier of the product.

Response

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

Delete a discount

Deletes a specific discount.

Request

DELETE /v1/accounts/{account-id}/discounts/{discount-id}

Parameters

None.

Response

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

Orders

Orders represent a purchase someone has made from a store, and contains all of the information required to review the order, ship it to the buyer, and track it’s shipping and payment status.

Order object

Attribute Type Description
id string The unique identifier for the order.
item_count integer The number of items in the order.
item_total decimal The total price of all items.
discount_total decimal The total price of all discounts.
shipping_total decimal The total price of all shipping costs.
tax_total decimal The total price of all taxes.
total decimal The total price of everything.
customer_first_name string The first name of the buyer.
customer_last_name string The last name of the buyer.
customer_email string The email address of the buyer.
customer_opted_in_to_marketing boolean Whether or not the buyer opted-in to marketing at checkout. Marketing apps must honor this.
customer_note string An optional note from the buyer.
shipping_address_1 string The street address for shipping.
shipping_address_2 string An optional addition to the street address for shipping.
shipping_city string The city of the shipping address.
shipping_state string The state or province of the shipping address.
shipping_zip string The zip or postal code of the shipping address.
shipping_country.id string The unique 2-letter code for the order’s country.
shipping_country.name string The name of the order’s country.
shipping_latitude integer The latitude of the shipping address.
shipping_longitude integer The longitude of the shipping address.
shipping_status string The status of shipping the order. Possible values are shipped and unshipped.
payment_status string The status of payment for the order. Possible values are unpaid, pending, completed, failed, and invalid.
created_at timestamp When the order was created.
updated_at timestamp When the order was last updated.
completed_at timestamp When the order was placed and paid for.
currency.id string The unique 3-letter code for the order’s currency.
currency.name string The name of the order’s currency.
currency.sign string The symbol used for the order’s currency.
currency.locale string The locale associated with the order’s currency.
events[].id integer The unique identifier of the order event.
events[].message string A message describing the order event.
events[].created_at timestamp When the order event was created.
items[].id integer The unique identifier of the order item.
items[].product_name string The name of the item’s product.
items[].product_option_name string The name of the item’s product option.
items[].quantity integer The quantity of the item.
items[].price decimal The price of the item.
items[].total decimal The total price of the item, quantity multiplied by price.
items[].image_url string The customizable URL of the product image.
items[].product.id integer The unique identifier of the product.
items[].product_option.id integer The unique identifier of the product option.
transactions[].id integer The unique identifier of the order transaction.
transactions[].label string A message describing the transaction.
transactions[].amount decimal The total price of the transaction.
transactions[].processor string The name of the payment processor. Possible values are cash, paypal_standard, paypal_express, and stripe.
transactions[].processor_id string The payment processor’s transaction ID.
transactions[].processor_url string The URL to view the transaction on the processor’s website.
transactions[].currency.id integer The unique 3-letter code for the transaction’s currency.
transactions[].currency.name string The name of the transaction’s currency.
transactions[].currency.sign string The symbol used for the transaction’s currency.
transactions[].currency.locale string The locale associated with the transaction’s currency.
adjustments[].id integer The unique identifier of the order adjustment.
adjustments[].amount decimal The price of the adjustment.
adjustments[].label string A message describing the adjustment.

Get all orders

Get all orders for an account.

Request

GET /v1/accounts/{account-id}/orders

Parameters

Name Type Required Description
search string false Search orders that match the customer name (customer_first_name + customer_last_name), customer_email, and id attributes.
filter string false Filter orders using the shipping_status attribute. Allowed values are shipped or unshipped.
sort string false Sort orders using the specified attribute, in ascending order by default. Prefix the value with - to specify descending order. Allowed values are completed_at, created_at, and updated_at.

Search example

Get all orders that match example@example.com.

GET /v1/accounts/{account-id}/orders?search=example@example.com

Filter example

Get all orders with the shipping_status of unshipped.

GET /v1/accounts/{account-id}/orders?filter[shipping_status]=unshipped

Sort example

Get all orders, sorted by the time they were created, in descending order.

GET /v1/accounts/{account-id}/orders?sort=-created_at

Get an order

Get a specific order for an account.

Request

GET /v1/accounts/{account-id}/orders/{order-id}

Parameters

None.

Update an order

Updates a specific order’s details.

Request

PATCH /v1/accounts/{account-id}/orders/{order-id}

Parameters

Name Type Required Description
id string true The unique identifier for the order.
type string true The only option right now is orders.
customer_first_name string false The first name of the buyer.
customer_last_name string false The last name of the buyer.
customer_email string false The email address of the buyer.
shipping_address_1 string false The street address for shipping.
shipping_address_2 string false An optional addition to the street address for shipping.
shipping_city string false The city of the shipping address.
shipping_state string false The state or province of the shipping address.
shipping_zip string false The zip or postal code of the shipping address.
shipping_country_id string false The unique 2-letter code for the order’s country.
shipping_status string false The status of shipping the order. Possible values are shipped or unshipped.

Response

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

Products

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.

Request

GET /v1/accounts/{account-id}/products

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.

Request

GET /v1/accounts/{account-id}/products/{product-id}

Parameters

None.

Reposition products

Repositions the list of products in the specified order.

Request

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.

Response

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

Marketing Apps

If you’d like to integrate an email marketing service with Big Cartel, you must allow buyers to opt-in to this marketing, as stated in Section 4e of our API License Agreement.

To help with this, we can configure your app so that any shops using it will present buyers with a “Subscribe to our email list” checkbox in the checkout process. From there, you should use the customer_opted_in_to_marketing order attribute to opt them in or out.

Terms of Service

Before you start making API calls, please make sure to read the full API License Agreement so that you understand the rules and guidelines you are agreeing to by using the API.

Changelog

This changelog represents the evolution of our V1 API. All changes are automatic and fully backwards-compatible, unless stated otherwise.

2017-09-18

  • The OAuth flow has been updated to automatically redirect users back to your application’s redirect_uri if their account is already connected to your application, instead of being prompted to allow or deny access.

2017-04-24

2016-03-11

  • The Account object now includes inventory_enabled and artists_enabled.

2016-02-29

  • The Product object now includes the url and primary_image_url attributes.
Heads up! You're using an unsupported older browser. Click to learn how to update it.