• Getting Access
• Account API
• Sales Report API
• Merch Orders API
  • get_merch_details
  • get_shipping_origin_details
  • get_orders
  • update_shipped
  • mark_date_range_as_shipped
  • update_quantities
  • update_sku

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

{
  "band_id": 1633770804,
  "start_time": "2015-12-31",
  "end_time": "2016-01-01",
  "member_band_id": 1925197437,
  "package_ids": [175167691, 1154611570]      
}

{
  "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.)

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

{
  "band_id": 4085673277
}

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

{
  "origin_id": 262687020
}

{
  "success": true,
  "shipping_origins": [
    {
      "state_name": null,
      "origin_id": 262687020,
      "band_id": 3085773287,
      "country_name": "Canada",
      "state_code": ""
    }
  ]
}

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

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

{
  "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": "refunded"
    },
    {
      "sale_item_id" : ...,
      "payment_id": ...,
      ...
    },
    ...
  ]
}

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

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

{
  "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": "refunded"
    },
    {
      "sale_item_id" : ...,
      "payment_id": ...,
      ...
    },
    ...
  ]
}

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

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

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

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

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

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

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

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

{
  "success": true
}

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

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

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

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

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

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

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

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

{"success" : true }