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.
`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.

Some errors will return an additional errors object in the response with information in the following format:

{
  "errors": [
    {
      "code": "not-found",
      "title": "The item you requested was not found",
      "detail": "We couldn't find that account"
    }
  ]
}

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.

GET /v1/categories?sort=name&sort_direction=desc

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.

GET /v1/accounts/1/orders?page[limit]=10&page[offset]=0

When an object supports pagination, a links object is returned that can contain first, last, next, and prev keys with links to their respective pages depending on what page of results is being returned. For example:

{
  "data": [
    ...
  ],
  "links": {
    "next": "http://api.bigcartel.com/v1/accounts/1/orders?page%5Blimit%5D=10&page%5Boffset%5D=10",
    "last": "http://api.bigcartel.com/v1/accounts/1/orders?page%5Blimit%5D=10&page%5Boffset%5D=10"
  }
}

Additionally, we’ll return a meta object with the total number of results available to be paginated through:

{
  "data": [
    ...
  ],
  "meta": {
    "count": 60
  }
}

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.

Original

https://assets.bigcartel.com/example_resource/12345/example.jpg?w=1000&h=1000

Resized

https://assets.bigcartel.com/example_resource/12345/example.jpg?w=500&h=250

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`	account	Sent when an account is updated.
`account.plan.downgraded`	account	Sent when an account is downgraded.
`account.plan.upgraded`	account	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.
`shipment.created`	shipment	Sent when a new shipment is created.
`shipment.updated`	shipment	Sent when a shipment is updated
`shipment.deleted`	shipment	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:

{
  "account_id": "12345",
  "type": "order.created",
  "payload": { ... }
}

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.

Ruby

require 'openssl'
require 'base64'

sha256 = OpenSSL::Digest::SHA256.new
secret = 'YOUR_CLIENT_SECRET'
body = request.body.read
signature = OpenSSL::HMAC.hexdigest(sha256, secret, body)

Python

import hmac
from hashlib import sha256

secret = 'YOUR_CLIENT_SECRET'
body = request.data
signature = hmac.new(secret, body, sha256).hexdigest()

Node

var crypto = require('crypto');
var hmac = crypto.createHmac('sha256', clientSecret);
    hmac.update(responseBody);
var signature = hmac.digest().toString('hex');

PHP

$secret = 'YOUR_CLIENT_SECRET';
$body = file_get_contents('php://input');
$signature = hash_hmac('sha256', $body, $secret);

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.

User-Agent: Example Inc. (http://example.com/contact/)
User-Agent: Example Project (email@example.com)

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.

Grab an OAuth library.
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.

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

Using the access token

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

curl -H "Authorization: Bearer YOUR-ACCESS-TOKEN" https://api.bigcartel.com/accounts/12345

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.

https://api.bigcartel.com/oauth/deauthorize/{account-id}

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.

{
  "error":"client_secret_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.
`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.

Example Response

{
  "data": {
    "id": "1",
    "type": "accounts",
    "attributes": {
      "subdomain": "example",
      "store_name": "My example store",
      "description": "An example store",
      "contact_email": "email@example.com",
      "url": "http://example.bigcartel.com",
      "website": "http://www.webcrawler.com",
      "created_at": "2014-12-25T00:00:00.000Z",
      "updated_at": "2014-12-25T00:00:00.000Z",
      "under_maintenance": false,
      "inventory_enabled": true,
      "artists_enabled": false
    },
    "links": {
      "self": "https://api.bigcartel.com/v1/accounts/1"
    },
    "relationships": {
      "currency": {
        "data": {
          "type": "currencies",
          "id": "USD"
        }
      },
      "country": {
        "data": {
          "type": "countries",
          "id": "US"
        }
      },
      "plan": {
        "data": {
          "type": "plans",
          "id": "diamond"
        }
      },
      "account_image": {
        "data": {
          "type": "account_images",
          "id": "12345"
        }
      },
      "orders": {
        "links": {
          "related": "https://api.bigcartel.com/v1/accounts/1/orders"
        }
      },
      "categories": {
        "links": {
          "self": "https://api.bigcartel.com/v1/accounts/1/relationships/categories",
          "related": "https://api.bigcartel.com/v1/accounts/1/categories"
        }
      },
      "products": {
        "links": {
          "self": "https://api.bigcartel.com/v1/accounts/1/relationships/products",
          "related": "https://api.bigcartel.com/v1/accounts/1/products"
        }
      }
    }
  },
  "included": [
    {
      "id": "USD",
      "type": "currencies",
      "attributes": {
        "name": "U.S. Dollar",
        "sign": "$",
        "locale": "en-US"
      }
    },
    {
      "id": "US",
      "type": "countries",
      "attributes": {
        "name": "United States"
      }
    },
    {
      "id": "diamond",
      "type": "plans",
      "attributes": {
        "max_products": 100,
        "max_images_per_product": 5,
        "name": "Diamond",
        "monthly_rate": "19.99"
      }
    },
    {
      "id": "12345",
      "type": "account_images",
      "attributes": {
        "url": "https://bigcartel.imgix.net/account_images/12345/filename.jpg?fit=clip&w=1000&h=1000"
      }
    }
  ]
}

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.

Example Response

{
  "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"
  }
}

Get an artist

Get a specific artist for an account.

Request

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

Parameters

None.

Example Response

{
  "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"
    }
  }
}

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.

Example Request

{
  "data": {
    "type": "artists",
    "attributes": {
      "name": "New Example 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.

Example Request

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

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.

Example Request

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

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.

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.

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

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.

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

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.

Example Response

{
  "data":[
    {
      "id":"AF",
      "type":"countries",
      "attributes": {
        "name":"Afghanistan"
      }
    },
    {
      "id":"AL",
      "type":"countries",
      "attributes": {
        "name":"Albania"
    },
    {
      "id":"DZ",
      "type":"countries",
      "attributes": {
        "name":"Algeria"
      }
    },
    ...
    {  
      "id":"ZW",
      "type":"countries",
      "attributes": {
        "name":"Zimbabwe"
      }
    }
  ],
  "meta":{
    "count":"247"
  }
}

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

Example Response

{
  "data": [
    {
      "id": "1",
      "type": "discounts",
      "attributes": {
        "name": "10% Off Product Name",
        "code": "TENPERCENT",
        "active_at": "2017-02-24T15:27:00.000Z",
        "expires_at": null,
        "requirement_type": "any_order",
        "expiration_type": "never",
        "reward_type": "percent_discount",
        "application_type": "product",
        "percent_discount": 10,
        "flat_rate_discount": null,
        "use_limit": null,
        "use_count": 0,
        "minimum_cart_total": null,
        "minimum_cart_quantity": null
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/discounts/1"
      },
      "relationships": {
        "product": {
          "data": {
            "type": "products",
            "id": "1"
          }
        },
        "category": {
          "data": null
        }
      }
    },
    {
      "id": "2",
      "type": "discounts",
      "attributes": {
        "name": "Free Shipping",
        "code": "FREESHIPPING",
        "active_at": "2016-12-25T06:00:00.000Z",
        "expires_at": null,
        "requirement_type": "any_order",
        "expiration_type": "on_limit",
        "reward_type": "free_shipping",
        "application_type": "all",
        "percent_discount": null,
        "flat_rate_discount": null,
        "use_limit": 5,
        "use_count": 0,
        "minimum_cart_total": null,
        "minimum_cart_quantity": null
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/discounts/2"
      },
      "relationships": {
        "product": {
          "data": null
        },
        "category": {
          "data": null
        }
      }
    },
    {
      "id": "3",
      "type": "discounts",
      "attributes": {
        "name": "Summer sale - 20% off",
        "code": "SUMMERSALE",
        "active_at": "2017-06-01T14:18:00.000Z",
        "expires_at": "2017-08-31T05:00:00.000Z",
        "requirement_type": "any_order",
        "expiration_type": "on_date",
        "reward_type": "percent_discount",
        "application_type": "all",
        "percent_discount": 20,
        "flat_rate_discount": null,
        "use_limit": null,
        "use_count": 0,
        "minimum_cart_total": null,
        "minimum_cart_quantity": null
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/discounts/3"
      },
      "relationships": {
        "product": {
          "data": null
        },
        "category": {
          "data": null
        }
      }
    }
  ],
  "meta": {
    "count": "3"
  },
  "included": [
    {
      "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"
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/products/1"
      },
      "relationships": {
        "options": {
          "data": [
            {
              "type": "product_options",
              "id": "1"
            },
            {
              "type": "product_options",
              "id": "2"
            }
          ]
        },
        "categories": {
          "data": [
            {
              "type": "categories",
              "id": "1"
            },
            {
              "type": "categories",
              "id": "2"
            },
            {
              "type": "categories",
              "id": "3"
            }
          ]
        },
        "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"
            },
            {
              "type": "product_images",
              "id": "3"
            }
          ]
        }
      }
    }
  ],
  "links": {}
}

Get a discount

Get a specific discount for an account.

Request

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

Parameters

None.

Example Response

{
  "data": {
    "id": "1",
    "type": "discounts",
    "attributes": {
      "name": "10% Off Product Name",
      "code": "TENPERCENT",
      "active_at": "2017-02-24T15:27:00.000Z",
      "expires_at": null,
      "requirement_type": "any_order",
      "expiration_type": "never",
      "reward_type": "percent_discount",
      "application_type": "product",
      "percent_discount": 10,
      "flat_rate_discount": null,
      "use_limit": null,
      "use_count": 0,
      "minimum_cart_total": null,
      "minimum_cart_quantity": null
    },
    "links": {
      "self": "https://api.bigcartel.com/v1/accounts/1/discounts/1"
    },
    "relationships": {
      "product": {
        "data": {
          "type": "products",
          "id": "1"
        }
      },
      "category": {
        "data": null
      }
    }
  },
  "included": [
    {
      "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"
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/products/1"
      },
      "relationships": {
        "options": {
          "data": [
            {
              "type": "product_options",
              "id": "1"
            },
            {
              "type": "product_options",
              "id": "2"
            }
          ]
        },
        "categories": {
          "data": [
            {
              "type": "categories",
              "id": "1"
            },
            {
              "type": "categories",
              "id": "2"
            },
            {
              "type": "categories",
              "id": "3"
            }
          ]
        },
        "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"
            },
            {
              "type": "product_images",
              "id": "3"
            }
          ]
        }
      }
    }
  ]
}

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.

Creates a discount to give customers free shipping on all items in a specific category.

{
  "data": {
    "type": "discounts",
    "attributes": {
      "name": "Free Shipping Discount",
      "code": "FREESHIPPING",
      "active_at": "2016-12-25T00:00:00.000Z",
      "requirement_type": "any_order",
      "reward_type": "free_shipping",
      "application_type": "category",
      "expiration_type": "never"
    },
    "relationships": {
      "category": {
        "data": {
          "type": "categories",
          "id": "1"
        }
      }
    }
  }
}

Creates a discount to give customers a flat-rate discount on their entire order if they order at least 5 items.

{
  "data": {
    "type": "discounts",
    "attributes": {
      "name": "Flat Rate Discount",
      "code": "FLATRATE",
      "active_at": "2014-12-25T00:00:00.000Z",
      "requirement_type": "minimum_cart_quantity",
      "reward_type": "flat_rate_discount",
      "application_type": "all",
      "expiration_type": "never",
      "flat_rate_discount": "10.0",
      "minimum_cart_quantity": 5
    }
  }
}

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 description of the discount.
`code`	string	true	The code customers enter to use the discount.
`active_at`	timestamp	false	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.

Example Request

Update a discount to give customers a $10 flat rate discount on any order with at least 5 items.

{
  "data": {
  	"id": "1",
    "type": "discounts",
    "attributes": {
      "name": "Flat Rate Discount",
      "code": "FLATRATE",
      "active_at": "2023-08-01T00:00:00.000Z",
      "requirement_type": "minimum_cart_quantity",
      "reward_type": "flat_rate_discount",
      "application_type": "all",
      "expiration_type": "never",
      "flat_rate_discount": "10.0",
      "minimum_cart_quantity": 5
    }
  }
}

Update a discount to give customers a 15% discount on a specific product.

{
  "data": {
  	"id": "1",
    "type": "discounts",
    "attributes": {
      "name": "15% off a red shirt",
      "code": "15OFF",
      "requirement_type": "any_order",
      "reward_type": "percent_discount",
      "application_type": "product",
      "expiration_type": "never",
      "percent_discount": 15
    },
    "relationships": {
      "product":{
        "data": {
            "type": "products",
            "id": 1234567
        }
      }
    }
  }
}

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_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`.
`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

Example Response

{
  "data": [
    {
      "id": "LMFN-543196",
      "type": "orders",
      "attributes": {
        "item_count": 1,
        "item_total": "100.1",
        "discount_total": "10.0",
        "shipping_total": "10.0",
        "tax_total": "0.0",
        "total": "100.1",
        "customer_first_name": "Joe",
        "customer_last_name": "Somebody",
        "customer_email": "joe@somebody.com",
        "customer_phone_number": "+1 (123) 456-7890",
        "customer_opted_in_to_marketing": false,
        "customer_note": "Created by Joe",
        "shipping_address_1": "123 some street",
        "shipping_address_2": "#123",
        "shipping_city": "Somewhere",
        "shipping_state": "UT",
        "shipping_zip": "64801",
        "shipping_latitude": null,
        "shipping_longitude": null,
        "shipping_status": "unshipped",
        "payment_status": "completed",
        "created_at": "2014-12-25T00:00:00.000Z",
        "updated_at": "2014-12-25T00:00:00.000Z",
        "completed_at": "2014-12-25T00:00:00.000Z"
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/orders/LMFN-543196"
      },
      "relationships": {
        "currency": {
          "data": {
            "type": "currencies",
            "id": "USD"
          }
        },
        "shipping_country": {
          "data": {
            "type": "countries",
            "id": "US"
          }
        },
        "events": {
          "data": [
            {
              "type": "order_events",
              "id": "1"
            }
          ]
        },
        "items": {
          "data": [
            {
              "type": "order_line_items",
              "id": "2"
            }
          ]
        },
        "transactions": {
          "data": [
            {
              "type": "order_transactions/payments",
              "id": "3"
            }
          ]
        },
        "adjustments": {
          "data": [
            {
              "type": "order_adjustments/shipping",
              "id": "4"
            },
            {
              "type": "order_adjustments/tax",
              "id": "5"
            },
            {
              "type": "order_adjustments/discount",
              "id": "6"
            }
          ]
        }
      }
    }
  ],
  "meta": {
    "count": 25
  },
  "included": [
    {
      "id": "USD",
      "type": "currencies",
      "attributes": {
        "name": "U.S. Dollar",
        "sign": "$",
        "locale": "en-US"
      }
    },
    {
      "id": "US",
      "type": "countries",
      "attributes": {
        "name": "United States"
      }
    },
    {
      "id": "1",
      "type": "order_events",
      "attributes": {
        "created_at": "2014-12-25T00:00:00.000Z",
        "message": "Payment completed"
      }
    },
    {
      "id": "2",
      "type": "order_line_items",
      "attributes": {
        "product_name": "This product",
        "product_option_name": "This option",
        "quantity": 1,
        "price": "100.0",
        "total": "100.0",
        "image_url": "https://images.bigcartel.com/some_resource/12345/-/example.jpg"
      },
      "relationships": {
        "product": {
          "data": {
            "type": "product",
            "id": "7"
          }
        },
        "product_option": {
          "data": {
            "type": "product_option",
            "id": "8"
          }
        }
      }
    },
    {
      "id": "3",
      "type": "order_transactions/payments",
      "attributes": {
        "label": "Visa ending in 1234",
        "amount": "100.0",
        "processor": "stripe",
        "processor_id": "ex_123456789",
        "processor_url": "https://manage.stripe.com/test/payments/ex_123456789"
      },
      "data": {
        "currency": {
          "data": {
            "type": "currencies",
            "id": "USD"
          }
        }
      }
    },
    {
      "id": "4",
      "type": "order_adjustments/shipping",
      "attributes": {
        "amount": "10.0",
        "label": "Shipping charges"
      }
    },
    {
      "id": "5",
      "type": "order_adjustments/tax",
      "attributes": {
        "amount": "0.1"
      }
    },
    {
      "id": "6",
      "type": "order_adjustments/discount",
      "attributes": {
        "amount": "10.0",
        "label": "[FREESHIPPING] Free shipping discount"
      }
    }
  ],
  "links": {
    "next": "https://api.bigcartel.com/v1/accounts/1/orders?page%5Blimit%5D=10&page%5Boffset%5D=10",
    "last": "https://api.bigcartel.com/v1/accounts/1/orders?page%5Blimit%5D=10&page%5Boffset%5D=10"
  }
}

Get an order

Get a specific order for an account.

Request

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

Parameters

None.

Example Response

{
  "data": {
    "id": "LMFN-543196",
    "type": "orders",
    "attributes": {
      "item_count": 1,
      "item_total": "100.1",
      "discount_total": "10.0",
      "shipping_total": "10.0",
      "tax_total": "0.0",
      "total": "100.1",
      "customer_first_name": "Joe",
      "customer_last_name": "Somebody",
      "customer_email": "joe@somebody.com",
      "customer_phone_number": "+1 (123) 456-7890",
      "customer_opted_in_to_marketing": false,
      "customer_note": "Created by Joe",
      "shipping_address_1": "123 some street",
      "shipping_address_2": "#123",
      "shipping_city": "Somewhere",
      "shipping_state": "UT",
      "shipping_zip": "64801",
      "shipping_latitude": null,
      "shipping_longitude": null,
      "shipping_status": "unshipped",
      "payment_status": "completed",
      "created_at": "2014-12-25T00:00:00.000Z",
      "updated_at": "2014-12-25T00:00:00.000Z",
      "completed_at": "2014-12-25T00:00:00.000Z"
    },
    "links": {
      "self": "https://api.bigcartel.com/v1/accounts/1/orders/LMFN-543196"
    },
    "relationships": {
      "currency": {
        "data": {
          "type": "currencies",
          "id": "USD"
        }
      },
      "shipping_country": {
        "data": {
          "type": "countries",
          "id": "US"
        }
      },
      "events": {
        "data": [
          {
            "type": "order_events",
            "id": "1"
          }
        ]
      },
      "items": {
        "data": [
          {
            "type": "order_line_items",
            "id": "2"
          }
        ]
      },
      "transactions": {
        "data": [
          {
            "type": "order_transactions/payments",
            "id": "3"
          }
        ]
      },
      "adjustments": {
        "data": [
          {
            "type": "order_adjustments/shipping",
            "id": "4"
          },
          {
            "type": "order_adjustments/tax",
            "id": "5"
          },
          {
            "type": "order_adjustments/discount",
            "id": "6"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "USD",
      "type": "currencies",
      "attributes": {
        "name": "U.S. Dollar",
        "sign": "$",
        "locale": "en-US"
      }
    },
    {
      "id": "US",
      "type": "countries",
      "attributes": {
        "name": "United States"
      }
    },
    {
      "id": "1",
      "type": "order_events",
      "attributes": {
        "created_at": "2014-12-25T00:00:00.000Z",
        "message": "Payment completed"
      }
    },
    {
      "id": "2",
      "type": "order_line_items",
      "attributes": {
        "product_name": "This product",
        "product_option_name": "This option",
        "quantity": 1,
        "price": "100.0",
        "total": "100.0",
        "image_url": "https://images.bigcartel.com/some_resource/12345/-/example.jpg"
      },
      "relationships": {
        "product": {
          "data": {
            "type": "product",
            "id": "7"
          }
        },
        "product_option": {
          "data": {
            "type": "product_option",
            "id": "8"
          }
        }
      }
    },
    {
      "id": "3",
      "type": "order_transactions/payments",
      "attributes": {
        "label": "Visa ending in 1234",
        "amount": "100.0",
        "processor": "stripe",
        "processor_id": "ex_123456789",
        "processor_url": "https://manage.stripe.com/test/payments/ex_123456789"
      },
      "relationships": {
        "currency": {
          "data": {
            "type": "currencies",
            "id": "USD"
          }
        }
      }
    },
    {
      "id": "4",
      "type": "order_adjustments/shipping",
      "attributes": {
        "amount": "10.0",
        "label": "Shipping charges"
      }
    },
    {
      "id": "5",
      "type": "order_adjustments/tax",
      "attributes": {
        "amount": "0.1"
      }
    },
    {
      "id": "6",
      "type": "order_adjustments/discount",
      "attributes": {
        "amount": "10.0",
        "label": "[FREESHIPPING] Free shipping discount"
      }
    }
  ]
}

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.
`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. 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.

Example Request

{
  "data": {
    "id": "LMFN-543196",
    "type": "orders",
    "attributes": {
      "shipping_status": "shipped"
    }
  }
}

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.

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

Example Response

{
  "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"
  }
}

Get a product

Get a specific product for an account.

Request

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

Parameters

None.

Example Response

{
  "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"
      }
    }
  ]
}

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.

Example Request

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

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.

Example Response

{
    "data": [
        {
            "id": "1",
            "type": "shipments",
            "attributes": {
              "carrier": "USPS",
              "tracking_number": "1234567",
              "tracking_url": "http://tracking.com/1234567",
              "last_notified_at": "2018-12-25T22:38:56.000Z",
              "created_at": "2018-12-17T22:38:56.000Z",
               "updated_at": "2018-12-17T22:38:56.000Z"
            },
            "links": {
                "self": "https://api.bigcartel.com/v1/accounts/1/orders/ABCD-1234/shipments/1"
            },
            "relationships": {
                "order": {
                    "data": {
                        "type": "orders",
                        "id": "ABCD-1234"
                    }
                },
                "items": {
                    "data": [
                        {
                            "type": "shipment_items",
                            "id": "1"
                        }
                    ]
                }
            }
        }
    ],
    "meta": {
        "count": "1"
    },
    "included": [
        {
            "id": "ABCD-1234",
            "type": "orders",
            "attributes": {
              "item_count": 2,
              "item_total": "100.1",
              "discount_total": "10.0",
              "shipping_total": "10.0",
              "tax_total": "0.0",
              "total": "100.1",
              "customer_first_name": "Joe",
              "customer_last_name": "Somebody",
              "customer_email": "joe@somebody.com",
              "customer_opted_in_to_marketing": false,
              "customer_note": "Created by Joe",
              "shipping_address_1": "123 some street",
              "shipping_address_2": "#123",
              "shipping_city": "Somewhere",
              "shipping_state": "UT",
              "shipping_zip": "64801",
              "shipping_latitude": null,
              "shipping_longitude": null,
              "shipping_status": "shipped",
              "payment_status": "completed",
              "created_at": "2014-12-25T00:00:00.000Z",
              "updated_at": "2014-12-25T00:00:00.000Z",
              "completed_at": "2014-12-25T00:00:00.000Z"
            },
            "links": {
                "self": "https://api.bigcartel.com/v1/accounts/1/orders/ABCD-1234"
            },
            "relationships": {
                "currency": {
                    "data": {
                        "type": "currencies",
                        "id": "USD"
                    }
                },
                "shipping_country": {
                    "data": {
                        "type": "countries",
                        "id": "US"
                    }
                },
                "events": {
                    "data": [
                        {
                            "type": "order_events",
                            "id": "1"
                        }
                    ]
                },
                "warnings": {
                    "data": []
                },
                "items": {
                    "data": [
                        {
                            "type": "order_line_items",
                            "id": "1"
                        }
                    ]
                },
                "transactions": {
                    "data": [
                        {
                            "type": "order_transactions/payments",
                            "id": "1"
                        }
                    ]
                },
                "adjustments": {
                    "data": [
                        {
                            "type": "order_adjustments/shipping",
                            "id": "1"
                        },
                        {
                            "type": "order_adjustments/discount",
                            "id": "1"
                        }
                    ]
                }
            }
        },
        {
            "id": "1",
            "type": "shipment_items",
            "attributes": {
                "quantity": 1,
                "order_line_item_id": "1"
            },
            "relationships": {
                "shipment": {
                    "data": {
                        "type": "shipments",
                        "id": "1"
                    }
                },
                "order_line_item": {
                    "data": {
                        "type": "order_line_items",
                        "id": "1"
                    }
                }
            }
        }
    ],
    "links": {}
}

Get a shipment

Get a specific shipment for an order.

Request

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

Parameters

None.

Example Response

{
    "data": {
        "id": "1",
        "type": "shipments",
        "attributes": {
            "carrier": "USPS",
            "tracking_number": "1234567",
            "tracking_url": "http://tracking.com/1234567",
            "last_notified_at": "2018-12-25T22:38:56.000Z",
            "created_at": "2018-12-17T22:38:56.000Z",
            "updated_at": "2018-12-17T22:38:56.000Z"
        },
        "links": {
            "self": "https://api.bigcartel.com/v1/accounts/1/orders/ABCD-1234/shipments/1"
        },
        "relationships": {
            "order": {
                "data": {
                    "type": "orders",
                    "id": "ABCD-1234"
                }
            },
            "items": {
                "data": [
                    {
                        "type": "shipment_items",
                        "id": "1"
                    },
                    {
                        "type": "shipment_items",
                        "id": "2"
                    }
                ]
            }
        }
    },
    "included": [
        {
            "id": "ABCD-1234",
            "type": "orders",
            "attributes": {
              "item_count": 2,
              "item_total": "100.1",
              "discount_total": "10.0",
              "shipping_total": "10.0",
              "tax_total": "0.0",
              "total": "100.1",
              "customer_first_name": "Joe",
              "customer_last_name": "Somebody",
              "customer_email": "joe@somebody.com",
              "customer_opted_in_to_marketing": false,
              "customer_note": "Created by Joe",
              "shipping_address_1": "123 some street",
              "shipping_address_2": "#123",
              "shipping_city": "Somewhere",
              "shipping_state": "UT",
              "shipping_zip": "64801",
              "shipping_latitude": null,
              "shipping_longitude": null,
              "shipping_status": "shipped",
              "payment_status": "completed",
              "created_at": "2014-12-25T00:00:00.000Z",
              "updated_at": "2014-12-25T00:00:00.000Z",
              "completed_at": "2014-12-25T00:00:00.000Z"
            },
            "links": {
                "self": "https://api.bigcartel.com/v1/accounts/1788058/orders/QLOY-054276"
            },
            "relationships": {
                "currency": {
                    "data": {
                        "type": "currencies",
                        "id": "USD"
                    }
                },
                "shipping_country": {
                    "data": {
                        "type": "countries",
                        "id": "US"
                    }
                },
                "events": {
                    "data": [
                        {
                            "type": "order_events",
                            "id": "1"
                        },
                        {
                            "type": "order_events",
                            "id": "2"
                        },
                        {
                            "type": "order_events",
                            "id": "3"
                        }
                    ]
                },
                "warnings": {
                    "data": []
                },
                "items": {
                    "data": [
                        {
                            "type": "order_line_items",
                            "id": "1"
                        },
                        {
                            "type": "order_line_items",
                            "id": "2"
                        }
                    ]
                },
                "transactions": {
                    "data": [
                        {
                            "type": "order_transactions/payments",
                            "id": "1"
                        }
                    ]
                },
                "adjustments": {
                    "data": [
                        {
                            "type": "order_adjustments/shipping",
                            "id": "1"
                        }
                    ]
                }
            }
        },
        {
            "id": "1",
            "type": "shipment_items",
            "attributes": {
                "quantity": 1,
                "order_line_item_id": "1"
            },
            "relationships": {
                "shipment": {
                    "data": {
                        "type": "shipments",
                        "id": "1"
                    }
                },
                "order_line_item": {
                    "data": {
                        "type": "order_line_items",
                        "id": "1"
                    }
                }
            }
        },
        {
            "id": "1",
            "type": "shipment_items",
            "attributes": {
                "quantity": 1,
                "order_line_item_id": "1"
            },
            "relationships": {
                "shipment": {
                    "data": {
                        "type": "shipments",
                        "id": "1"
                    }
                },
                "order_line_item": {
                    "data": {
                        "type": "order_line_items",
                        "id": "1"
                    }
                }
            }
        }
    ]
}

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.

Create a shipment that has one item in it, and will notify the customer when it is created.

{
"data": {
  "type": "shipments",
   "attributes": {
      "carrier": "USPS",
       "tracking_number": "1234567",
       "tracking_url": "https://trackingurl.com/1234567",
       "notify_customer": true,
       "items": [{"quantity": 1, "order_line_item_id": 12345}]
    }
  }
}

Update a shipment

Updates a specific shipment’s details.

Request

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

Parameters

Name	Type	Required	Description
`id`	integer	required	The id of the shipment.
`type`	string	required	The only option right now is shipment.
`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 200 OK and the same body as getting the shipment.

Example Request

{
"data": {
  "id": 1,
  "type": "shipments",
   "attributes": {
      "carrier": "USPS",
       "tracking_number": "1234567",
       "tracking_url": "https://trackingurl.com/1234567",
       "items": [{"quantity": 1, "order_line_item_id": 12345}]
    }
  }
}

Delete a shipment

Deletes a specific shipment.

Request

DELETE /v1/accounts/{account-id}/orders/{order-id}/shipments/{shipment-id}

Parameters

None.

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.

2023-08-09

Added more examples for Update Discount
Corrected description of name property on Discounts—it is the description of the discount
Corrected active_at property as not required for Update Discount

2019-07-11

The Order object now includes customer_phone_number.

2019-01-07

New endpoint to create a shipment.
New endpoint to get a shipment.
New endpoint to get all shipments.
New endpoint to update a shipment.
New endpoint to delete a shipment.

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-06-01

The account.closed webhook is now account.deauthorized.

2017-04-24

The account.closed webhook is now sent when an account owner has revoked access to your application.

2017-03-23

The Order object now includes customer_opted_in_to_marketing for marketing apps.

2017-02-27

New endpoint to create a discount.
New endpoint to get a discount.
New endpoint to get all discounts.
New endpoint to update a discount.
New endpoint to delete a discount.

2017-02-15

New Deauthorization endpoint for revoking access to an account.

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.

2016-02-11

The Products endpoint now supports sorting by created_at and updated_at.

2015-12-03

The Orders endpoint now supports sorting by completed_at and created_at.

2015-11-06

New webhooks for product.created, product.updated, and product.deleted.

2015-10-27

New filter parameter for filtering products by status, category, or artist.
The Account object now includes under_maintenance.
All webhooks now include the account_id attribute.

2015-08-18

The Account object now includes account.image.

2015-08-10

New webhook for account.plan.downgraded.
New webhook for account.plan.upgraded.
The Account object now includes plan.monthly_rate, and plan.id is represented as a string instead of an integer.

2015-06-19

New endpoint to get all products.
New endpoint to get a product.
New endpoint to reposition products.

2015-06-04

New endpoint to reposition artists.
New endpoint to delete an artist.
New endpoint to update an artist.
New endpoint to create an artist.
New endpoint to get all artists.
New endpoint to get an artist.

2015-05-25

New endpoint to reposition categories.
New endpoint to delete a category.
New endpoint to update a category.
New endpoint to create a category.
New endpoint to get all categories.
New endpoint to get a category.

2015-05-20

New endpoint to update an order.
New sort parameter for sorting orders.

2015-05-05

New filter parameter for filtering shipped/unshipped orders.
New search parameter for searching orders.
New endpoint to get all countries.
New webhook for account.closed.

2015-04-20

New endpoint to get an account.
New endpoint to get all orders.
New endpoint to get an order.
New webhook for account.updated.
New webhook for order.created.
New webhook for order.updated.

Introduction

Versioning

Status Codes

Sorting

Pagination

Images

Webhooks

Types of webhooks

Receiving webhooks

Verifying webhooks

Responding to webhooks

Rate Limiting

Making API Calls

Required Headers

Identification

OAuth

Using an OAuth library

OAuth from scratch

1. Redirect the user to Big Cartel to request access

Parameters

2. Big Cartel redirects back to your site

3. Exchange the temporary code for an access token

Parameters

Response

Using the access token

Revoking access

OAuth errors

Personal Projects

Account

Account object

Get an account

Request

Parameters

Artists

Artist object

Get all artists

Request

Parameters

Get an artist

Request

Parameters

Create an artist

Request

Parameters

Response

Update an artist

Request

Parameters

Response

Reposition artists

Request

Parameters

Response

Delete an artist

Request

Parameters

Response

Categories

Category object

Get all categories

Request

Parameters

Get a category

Request

Parameters

Create a category

Request

Parameters

Response

Update a category

Request

Parameters

Response

Reposition categories

Request

Parameters

Response

Delete a category

Request

Parameters