Bandcamp

Discover amazing new music and directly support the artists who make it.

Bandcamp API

Merch Orders API

The Bandcamp Merch Orders API gives you access to your merch items and orders via standard web development techniques. You can query the API for new orders, mark existing ones as shipped, and search through older orders, filtering by label, band, or date. You can get details about the merchandise you have for sale on Bandcamp; you can also use the API to update SKU and inventory information.

Overview

The general use-case for the Merch Orders API is to first query Bandcamp for identifying information about the bands and labels you manage, then cache those IDs in your datastore. Later, whenever you need, you can use those IDs to query for new orders or for detailed information about the merchandise you sell. Those queries in turn contain identifying information that let you update orders (to mark some as shipped, for instance) or merch items (for example, to adjust inventory levels).

As with other Bandcamp APIs, the endpoints in the Merch Orders API are protected by OAuth 2.0 and should be POSTs with the Authorization header set to:

Authorization: Bearer {your access token}

All endpoints in the Merch Orders API require IDs to identify the entities they act on. You can query for these IDs with other endpoints, the starting place usually being the my_bands endpoint in the Account API:

To find:
Use:
label IDs, band IDs, member band IDs
my_bands in the Account API
package IDs, option IDs
get_merch_details in the Merch Orders API
payments IDs, sale items IDs
get_orders in the Merch Orders API
shipping origin IDs
get_shipping_origin_details in the Merch Orders API

Update operations are transactional, which here means all-or-nothing. If you initiate an update that affects a batch of items and any one update fails, the whole operation fails. In particular, no update will occur. In this scenario, the endpoint will return an error description to help identify the source of the trouble, for instance, to help distinguinsh between an error on your side (such as an invalid ID) and an error on our side (such as a system failure).

Parameters are passed via JSON as the body of the POST. IDs are integers; ID-types are single character codes given as a single-character quoted string; text strings are quoted; flags are boolean; times are strings formatted
YYYY-MM-DD and YYYY-MM-DD HH:MM:SS and are assumed to be UTC (these are interchangeable – time parameters will accept both dates and times). Sometimes parameters are optional, and sometimes null has its own meaning. For specifics, see the documenation for each endpoint.

Here's an example of the JSON you'd pass for a typical (fictitious) call:


{
 "some_id" : 292028440, 
 "id_type" : "i",           
 "some_date" : "2016-03-07",
 "some_flag" : true,
 "items" : [
   { "some_id" : 292028440, 
     "id_type" : "i",           
     "some_date" : "2016-03-07",
     "some_flag" : true 
   },
   { "some_id" : 292028440, 
     "id_type" : "i",           
     "some_date" : "2016-03-07",
     "some_flag" : true
   }
 ]
}

Successful calls will have a "success" member set to true, as well as an array of items, at least for query-type calls:


{ "success" : true, 
  "items" : [
       { 
            "sale_item_id": 403,
            "payment_id": 3548708385,
            "artist": "The Boys and Girls Band",
            "ship_to_country_code": "US",
            "ship_to_street": "740 Test Street",
            "buyer_email" : "jjforsyth@gmail.com",
            ...
       },
       ...
  ]
}

Return values to update-operations are simpler:


{ "success" : true }

Errors are formatted thus:


{
    "error": true,
    "error_message": "invalid id"
}

where the error_message member describes the error, to the extent possible.

band_id or member_band_id?

The Merch Orders API is designed for labels and fulfillment partners of labels. For historical reasons, both labels and bands are identified by their band_id. However, in this API, the member_band_id refers to the band or artist. So, for example, if you are querying for information about a single band, you usually will set band_id to the label's band ID, and you will filter on the actual band or artist by setting member_band_id to the band's or artist's band ID.

There is one, exceptional case in which band_id refers to a band or an artist instead of a label, and that is the case where you are a fulfillment partner and have a direct relationship with an independent band. In that case band_id will refer to the band or artist.

Endpoint Reference

The rest of this document is a reference guide for the various endpoints that make up the Merch Orders API.

get_merch_details (back to top)

Lists merchandise a label, band, or artist has available for purchase on Bandcamp

URL

https://bandcamp.com/api/merchorders/1/get_merch_details

Parameters

band_id
Bandcamp ID of your label or the (usually) label on whose behalf you are querying (get this ID from my_bands in the Account API)
member_band_id
(optional) Bandcamp ID of the band on which you wish to filter results (get this ID from my_bands in the Account API)
start_time
earliest date the items you are interested in would have been added to Bandcamp
end_time
(optional) latest date items you are in interested in would have been added to Bandcamp; defaults to the time of the call
package_ids
(optional) an array of package IDs that you wish to filter your results on

Return Values

success
always true when present, meaning the call succeeded
items
an array of merch items meeting the query parameters:
package_id
the Bandcamp ID of the merch item (use this in calls to other endpoints)
album_title
if this is music merch (cd, vinyl, cassette), the name of album it's associated with
title
name of the item for sale
image_url
URL of the image on Bandcamp associated with this item
quantity_available
number of units available for sale (i.e. which Bandcamp thinks it can still sell) across all shipping origins; null means unlimited
quantity_sold
number of units that have been sold on Bandcamp across all shipping origins
price
price per item
currency
currency in which price is listed
subdomain
the Bandcamp subdomain where the item can be found
is_set_price
can the user pay more than the asking price if they want?
sku
item sku
options
options information in array form, one item for each option; null when there are no options. Each item in the array contains these fields:
- option_id (i.e., the unique Bandcamp ID for this option)
- quantity_sold
- quantity_available
- title
- sku
origin_quantities
quantities per shipping origin. Each item in the array contains these fields:
- origin_id (i.e., the unique Bandcamp ID for this shipping origin)
- quantity_available
- quantity_sold
- option_quantities quantities at this shipping origin per option. Each item in the array contains these fields:
- option_id (i.e., the unique Bandcamp ID for this option)
- quantity_available
- quantity_sold

Example

Request
{
  "band_id": 1633770804,
  "start_time": "2015-12-31",
  "end_time": "2016-01-01",
  "member_band_id": 1925197437,
  "package_ids": [175167691, 1154611570]      
}
Response
{
  "items": [
    {
      "album_title": null,
      "package_id": 1154611570,
      "quantity_sold": 4,
      "options": null,
      "quantity_available": 16,
      "subdomain": "the-best-band",
      "is_set_price": null,
      "title": "Band Tote",
      "image_url": "https://www.bandcamp.com/img/12345.jpg",
      "currency": "USD",
      "price": 12,
      "sku": "GGRA3-1",
      "origin_quantities": [
        {
          "origin_id": 12345678,
          "quantity_available": 12,
          "quantity_sold": 2,
          "option_quantities": []
        },
        {
          "origin_id": 12345679,
          "quantity_available": 4,
          "quantity_sold": 2,
          "option_quantities": []
        }
      ]
    },
    {
      "album_title": "Demain est un autre jour",
      "package_id": 175167691,
      "is_set_price": 1,
      "title": "Vinyl LP",
      "currency": "USD",
      "price": 25.5,
      "sku": "AFIB",
      "quantity_sold": 2,
      "quantity_available": 210,
      "subdomain": "some-other-band",
      "options": [
        {
          "quantity_sold": 1,
          "quantity_available": 190,
          "title": "Red",
          "option_id": 1842702675,
          "sku": "AFIB-R"
        },
        {
          "quantity_sold": 1,
          "quantity_available": 20,
          "title": "Yellow",
          "option_id": 1842702676,
          "sku": "AFIB-B"
        },
        ...
      ],
      "origin_quantities": [
        {
          "origin_id": 12345678,
          "quantity_available": 110,
          "quantity_sold": 1,
          "option_quantities": [
            {
              "option_id": 1842702675,
              "quantity_available": 100,
              "quantity_sold": 0
            },
            {
              "option_id": 1842702676,
              "quantity_available": 10,
              "quantity_sold": 1
            }
          ]
        },
        {
          "origin_id": 12345679,
          "quantity_available": 100,
          "quantity_sold": 1,
          "option_quantities": [
            {
              "option_id": 1842702675,
              "quantity_available": 90,
              "quantity_sold": 1
            },
            {
              "option_id": 1842702676,
              "quantity_available": 10,
              "quantity_sold": 0
            }
          ]
        }
      ]
    }
    ...
  ]
}

get_shipping_origin_details (back to top)

Lists the shipping origins for artists and labels linked to your account on Bandcamp

URL

https://bandcamp.com/api/merchorders/1/get_shipping_origin_details

Parameters

band_id
(optional) Bandcamp ID of your label or the (usually) label on whose behalf you are querying (get this ID from my_bands in the Account API)
origin_id
(optional) Bandcamp ID of a specific shipping origin you want to retrieve details for

Return Values

success
always true when present, meaning the call succeeded
shipping_origins
an array of shipping origins, each containing:
origin_id
the Bandcamp ID of the shipping origin (use this in calls to other endpoints)
band_id
the Bandcamp ID of the artist or label this shipping origin is associated with
country_name
the name of the country that this shipping origin is located in
state_name
the name of the state that this shipping origin is located in, if available
state_code
the two-character code for the state that this shipping origin is located in, if available

Examples

Empty Request - If no parameters are sent with the request, a list of all shipping origins associated with any of the user's accounts will be returned. Note: if a band or label has more than one origin, that band or label or label will have more than one items in the return array. (The return array is not ordered.)

Response
{
  "success": true,
  "shipping_origins": [
    {
      "state_name": "Massachusetts",
      "origin_id": 262687009,
      "band_id": 4085673277,
      "country_name": "United States",
      "state_code": "MA"
    },
    {
      "state_name": null,
      "origin_id": 262687010,
      "band_id": 4085673277,
      "country_name": "United Kingdom",
      "state_code": ""
    },
    {
      "state_name": null,
      "origin_id": 262687020,
      "band_id": 3085773287,
      "country_name": "Canada",
      "state_code": ""
    }
  ]
}
Request with band_id - If a band_id parameter is sent with the request, a list of that account's shipping origins will be returned.
{
  "band_id": 4085673277
}
Response
{
  "success": true,
  "shipping_origins": [
    {
      "state_name": "Massachusetts",
      "origin_id": 262687009,
      "band_id": 4085673277,
      "country_name": "United States",
      "state_code": "MA"
    },
    {
      "state_name": null,
      "origin_id": 262687010,
      "band_id": 4085673277,
      "country_name": "United Kingdom",
      "state_code": ""
    }
  ]
}
Request with origin_id - If a origin_id parameter is sent with the request, details for that particular shipping origin will be returned
{
  "origin_id": 262687020
}
Response
{
  "success": true,
  "shipping_origins": [
    {
      "state_name": null,
      "origin_id": 262687020,
      "band_id": 3085773287,
      "country_name": "Canada",
      "state_code": ""
    }
  ]
}

get_orders (back to top)

Lists merchandise orders placed with a band or label

version

URL

https://bandcamp.com/api/merchorders/2/get_orders

What’s changed in version 2?

  • Orders with pending payments are now included in the response (they are excluded in version 1).
  • A new payment_state field tells you whether an item is paid or pending.

Parameters

band_id
Bandcamp ID of your label or the (usually) label on whose behalf you are querying (get this ID from my_bands in the Account API)
member_band_id
(optional) Bandcamp ID of band to filter on; defaults to all
start_time
(optional) earliest sale dates you're interested in
end_time
(optional) latest sale dates you're interested in
unshipped_only
(optional) query for unshipped orders only - true or false, default is false
name
(optional) filter orders on this item name (or title)
origin_id
(optional) filter orders on a particular shipping origin
format
(optional) results format: 'csv' or 'json' (default is 'json')

Return Values

success
always true when present, meaning the call succeeded
items
array of purchased items that meet the the query criteria, listed by purchased item (not by payment or order). So if, for example, a buyer purchases a t-shirt and an album in the same checkout experience, the t-shirt and the album will each contribute a separate item to the array returned here.
order_date
date order was placed
sale_item_id
Bandcamp ID for sale item
payment_id
Bandcamp ID for payment; multiple items share the same payment_id when more than one item is purchased in the same transaction
paypal_id
PayPal's ID for the transaction, if it exists
sku
SKU applied to merch item by band or label, if a SKU has been applied to the merch item. If the thing purchased comes in several options, the SKU here is that of option purchased.
item_name
name of the merch item, on Bandcamp
item_url
URL to the item, on Bandcamp
artist
artist's or band's name
option
option name, if it exists
discount_code
discount code, if it exists
sub_total
total before taxes
tax
taxes applied to sale
quantity
number of this particular sale item
ship_from_country_name
merch store to ship from
shipping
shipping costs
currency
currency of transcation
order_total
total charge
buyer_name
buyer's name
buyer_email
buyer's email address
buyer_note
note written by the purchaser, at the time of purchase, via the Bandcamp checkout UI
ship_notes
notes written by the purchaser, at the time of purchase, via the PayPal checkout UI
buyer_phone
buyer's telephone
ship_to_name
name to ship order to
ship_to_street
street name, for shipping
ship_to_street_2
second line of street name, if exists, for shipping
ship_to_city
city name, for shipping
ship_to_state
state / region within country, if exists, for shipping
ship_to_country
country name, for shipping
ship_to_country_code
ISO two letter country code, for shipping
ship_to_zip
postal code
ship_date
date on which item is marked as shipped, null when item hasn't yet shipped
payment_state
paid or pending

Example

Request
{
          "band_id": 1633770804,
          "start_time": "2015-12-31",
          "end_time": "2016-01-31",
          "member_band_id" : 1925197437,
          "unshipped_only": "true",
          "name": "Outstanding T-Shirt",
          "origin_id": 12345248,
          "format": "json"
        }
Response
{
          "success": true,
          "items": [
            {
              "sale_item_id": 403,
              "payment_id": 3548708385,
              "artist": "The Boys and Girls Band",
              "ship_to_country_code": "US",
              "ship_to_street": "740 Test Street",
              "buyer_email": "john.smith@test.com",
              "order_date": "14 Dec 2014 23:01:10 GMT",
              "paypal_id": "7JX00846HY134744Y",
              "ship_date": null,
              "sub_total": 1,
              "ship_to_country": "United States",
              "ship_to_street_2": null,
              "discount_code": null,
              "ship_notes": "Please autograph",
              "tax": 0.73,
              "option": null,
              "ship_to_city": "San Francisco",
              "quantity": 1,
              "buyer_phone": null,
              "shipping": 1.5,
              "ship_from_country_name": "United States",
              "ship_to_state": "CA",
              "buyer_note": "Could you autograph it and make it \"To Ralph\"",
              "currency": "USD",
              "item_name": "Foo Bar: Limited Edition Compact Disc",
              "ship_to_zip": "94101",
              "item_url": "http://tbgb.bandcamp.com/album/foo-bar",
              "order_total": 1,
              "ship_to_name": "Bobbie",
              "buyer_name": "John Smith",
              "sku": "AFIB",
              "payment_state": "paid"
            },
            {
              "sale_item_id" : ...,
              "payment_id": ...,
              ...
            },
            ...
          ]
        }

URL

https://bandcamp.com/api/merchorders/1/get_orders

Parameters

band_id
Bandcamp ID of your label or the (usually) label on whose behalf you are querying (get this ID from my_bands in the Account API)
member_band_id
(optional) Bandcamp ID of band to filter on; defaults to all
start_time
(optional) earliest sale dates you're interested in
end_time
(optional) latest sale dates you're interested in
unshipped_only
(optional) query for unshipped orders only - true or false, default is false
name
(optional) filter orders on this item name (or title)
origin_id
(optional) filter orders on a particular shipping origin
format
(optional) results format: 'csv' or 'json' (default is 'json')

Return Values

success
always true when present, meaning the call succeeded
items
array of purchased items that meet the the query criteria, listed by purchased item (not by payment or order). So if, for example, a buyer purchases a t-shirt and an album in the same checkout experience, the t-shirt and the album will each contribute a separate item to the array returned here.
order_date
date order was placed
sale_item_id
Bandcamp ID for sale item
payment_id
Bandcamp ID for payment; multiple items share the same payment_id when more than one item is purchased in the same transaction
paypal_id
PayPal's ID for the transaction, if it exists
sku
SKU applied to merch item by band or label, if a SKU has been applied to the merch item. If the thing purchased comes in several options, the SKU here is that of option purchased.
item_name
name of the merch item, on Bandcamp
item_url
URL to the item, on Bandcamp
artist
artist's or band's name
option
option name, if it exists
discount_code
discount code, if it exists
sub_total
total before taxes
tax
taxes applied to sale
quantity
number of this particular sale item
ship_from_country_name
merch store to ship from
shipping
shipping costs
currency
currency of transcation
order_total
total charge
buyer_name
buyer's name
buyer_email
buyer's email address
buyer_note
note written by the purchaser, at the time of purchase, via the Bandcamp checkout UI
ship_notes
notes written by the purchaser, at the time of purchase, via the PayPal checkout UI
buyer_phone
buyer's telephone
ship_to_name
name to ship order to
ship_to_street
street name, for shipping
ship_to_street_2
second line of street name, if exists, for shipping
ship_to_city
city name, for shipping
ship_to_state
state / region within country, if exists, for shipping
ship_to_country
country name, for shipping
ship_to_country_code
ISO two letter country code, for shipping
ship_to_zip
postal code
ship_date
date on which item is marked as shipped, null when item hasn't yet shipped

Example

Request
{
          "band_id": 1633770804,
          "start_time": "2015-12-31",
          "end_time": "2016-01-31",
          "member_band_id" : 1925197437,
          "unshipped_only": "true",
          "name": "Outstanding T-Shirt",
          "origin_id": 12345248,
          "format": "json"
        }
Response
{
          "success": true,
          "items": [
            {
              "sale_item_id": 403,
              "payment_id": 3548708385,
              "artist": "The Boys and Girls Band",
              "ship_to_country_code": "US",
              "ship_to_street": "740 Test Street",
              "buyer_email": "john.smith@test.com",
              "order_date": "14 Dec 2014 23:01:10 GMT",
              "paypal_id": "7JX00846HY134744Y",
              "ship_date": null,
              "sub_total": 1,
              "ship_to_country": "United States",
              "ship_to_street_2": null,
              "discount_code": null,
              "ship_notes": "Please autograph",
              "tax": 0.73,
              "option": null,
              "ship_to_city": "San Francisco",
              "quantity": 1,
              "buyer_phone": null,
              "shipping": 1.5,
              "ship_from_country_name": "United States",
              "ship_to_state": "CA",
              "buyer_note": "Could you autograph it and make it \"To Ralph\"",
              "currency": "USD",
              "item_name": "Foo Bar: Limited Edition Compact Disc",
              "ship_to_zip": "94101",
              "item_url": "http://tbgb.bandcamp.com/album/foo-bar",
              "order_total": 1,
              "ship_to_name": "Bobbie",
              "buyer_name": "John Smith",
              "sku": "AFIB"
            },
            {
              "sale_item_id" : ...,
              "payment_id": ...,
              ...
            },
            ...
          ]
        }

update_shipped (back to top)

Updates shipped/unshipped status of merchandise orders

URL

https://bandcamp.com/api/merchorders/1/update_shipped

Parameters

items
array of payments or sale items to update, where each array item is structured:
id
unique Bandcamp ID of the payment or sale item to update
id_type
'p' when id parameter refers to a payment, 's' for sale item
shipped
(optional), true to mark as shipped, false to mark as unshipped, missing or null defaults to true
notification
(optional) true to send notification, false don't, null or missing to honor seller (band or label) default setting
notification_message
(optional) custom message to send with shipping notificaton to buyer
ship_date
(optional) date of shipment; defaults to current date

Return Values

success
always true when present, meaning the call succeeded

Example

Request
{
  "items": [
    {
      "id": 1925197437,
      "id_type": "p",
      "shipped": true,
      "notification_message":  "Your items have shipped!",
      "ship_date":  "2016-02-29 12:59:59"
    },
    {
      "id" : 4261657553,
      "id_type": "s",
      "shipped": false
    },
      ....
  ]
  ...
}
Response
{
  "success": true
}

mark_date_range_as_shipped (back to top)

Updates shipped/unshipped status of merchandise orders within given date range

URL

https://bandcamp.com/api/merchorders/1/mark_date_range_as_shipped

Parameters

band_id
identifies the label you're calling on behalf of
member_band_id
(optional) identifies the band or artist to filter on
start_time
(optional) earliest date in range of orders
end_time
most recent date in range of orders (must be in past)
origin_id
(optional) Bandcamp ID of a specific origin which the items you want to update were shipped from
email_notifications
(optional) true to send notifications, false to suppress, leave out (or send null) to honor selling band preferences

Return Values

If successful, returns a list (array) of all items marked, where each item contains info about the item

success
always true when present, meaning the call succeeded
items
sale_item_id
the Bandcamp ID of the sale item marked
title
name of the item sold
buyer_name
purchaser's name

Example

Request
{
  "band_id":  2293737955,
  "member_band_id": 4261657553,
  "start_time": "2015-12-31 23:59:59",
  "end_time": "2016-01-31 00:00:00",
  "email_notifications": true
}
Response
{
  "success": true,
  "items": [
    {
      "sale_item_id": 783500159,
      "title": "The Trvest Cassette",
      "buyer_name": "Matt Murdoch",
    },
    ...
  ]
}

update_quantities (back to top)

Updates merch items' stock quantities (inventory levels)

URL

https://bandcamp.com/api/merchorders/1/update_quantities

Note: Because of the inherent race condition, this method requires you pass in a quantity_sold parameter as well as quantity_available. You get quantity_sold by calling get_merch_details immediately before calling this endpoint. Passing in quantity_sold effectively timestamps the new inventory level you are sending so Bandcamp can make adjustments to account for intervening sales.

Parameters

items
array of items or item-options to update, where each array item is structured:
id
package (merch item) or option (merch item-option) ID - (see get_merch_details)
id_type
"p" if id is for an item (or package), or "o" for an item-option
quantity_sold
the number of items that Bandcamp has sold, as reported by get_merch_details
quantity_available
the new inventory level you want to set
origin_id
(optional, unless you have more than one shipping origin) the unique Bandcamp ID for this shipping origin

Return Values

success
always true when present, meaning the call succeeded

Example

Request
{
  "items" : [
    {
         "id_type" : "p", 
         "id" : 3387163565,
         "quantity_available" : 365, 
         "quantity_sold": 57,
         "origin_id": 12345698
    }, 
    {
         "type" : "o", 
         "id" : 6789054322,
         "quantity_available" : 45, 
         "quantity_sold": 12,
         "origin_id": 12345678
    } 
    ...
  ]
}
Response
{"success" : true }

update_sku (back to top)

Updates merch item SKUs

URL

https://bandcamp.com/api/merchorders/1/update_sku

Parameters

items
array of items or item-options to update, where each array item is structured:
id
merch item (package) and option ID (see get_merch_details)
id_type
"p" if id refers to a merch item (package), or "o" an item-option
sku
the new SKU for the merch item (package) or item-option

Return Values

success
always true when present, meaning the call succeeded

Example

Request
{
  "items": [
    {
      "id": 175167691,
      "id_type": "p",
      "sku": "AFIB"
    },{
      "id": 1154611570,
      "id_type": "o",
      "sku": "AFIB-XL"
    }
    ...
  ]
}
Response
{"success" : true }