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.
406
Not Acceptable - something is wrong with your request.
5xx
Server Error - something is wrong on our end.
If you’re receiving 400 or 406 errors, double check to make sure you’re including the required headers.
Sorting
Many of our APIs support sorting results with the sort parameter where you pass the field name to sort by.
When sorting is supported, you can use the sort_direction parameter with either asc or desc to sort ascending or descending respectively.
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.
Sent when a shipment is deleted. This payload will only include the shipment id instead of the full shipment 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.
Making API Calls
All of our endpoints begin with the root URL https://api.bigcartel.com, and require a few headers to be sent along with your request.
Required Headers
All requests 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.
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.
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.
Configure it with your client_id, client_secret, and redirect_uri.
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.
Now that you’ve obtained an access_token for an account, you’ll need to use it in the Authorization header to make API calls - and remember to include the required headers!
Authorization: Bearer YOUR-ACCESS-TOKEN
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, specifying your store’s subdomain for the username. 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. Make sure to include the required headers in your requests.
GET /v1/accounts
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.
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 description 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 description 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.
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.
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_phone_number
string
The phone number 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.
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.
customer_phone_number
string
false
The phone number 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.
The status of shipping the order. Possible values are shipped or unshipped. An order cannot be set to shipped if it has at least one shipment and any unshipped line items. The shipping_status value will just be ignored.
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.
If successful, we’ll return a 204 No Content response.
Shipments
Shipments represent a shipment a store owner has created for an order, and contains tracking information as well as what items from an order have been shipped.
Shipment object
Attribute
Type
Description
id
integer
The unique identifier for the order shipment.
carrier
string
The name of the shipping carrier.
tracking_number
string
The tracking number of the shipment.
tracking_url
string
The URL of the tracking status on the carrier’s website.
last_notified_at
timestamp
The date the customer was notified about the shipment.
created_at
timestamp
The date the order shipment was created.
updated_at
timestamp
The date the order shipment was last updated.
items[].id
integer
The unique identifier of the order item.
items[].quantity
integer
The quantity of the item that has been shipped.
items[].order_item.id
string
The unique identifier of the order item.
Get all shipments
Get all shipments for an order.
Request
GET /v1/accounts/{account-id}/orders/{order-id}/shipments
Parameters
None.
Get a shipment
Get a specific shipment for an order.
Request
GET /v1/accounts/{account-id}/orders/{order-id}/shipments/{shipment-id}
Parameters
None.
Create a shipment
Creates a new shipment.
Request
POST /v1/accounts/{account-id}/orders/{order-id}/shipments
Parameters
Name
Type
Required
Description
type
string
required
The only option right now is shipments.
carrier
string
false
The name of the shipping carrier. (USPS, UPS, Fedex, etc).
tracking_number
string
false
The tracking number of the shipment.
tracking_url
string
false
The URL of the tracking status on the carrier’s website.
notify_customer
boolean
true
Whether the customer should get a notification email about the shipment.
items[].quantity
integer
true
The number of items included in this shipment.
items[].order_line_item_id
integer
true
The unique identifier of the order item.
Response
If successful, we’ll return a 201 Created with the location of the new shipment in the Location header and the same body as getting the shipment.
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.
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.