Bandcamp Gift Cards  and  Merch
×
view site
Log out

Bandcamp
cancel

Bandcamp API

Sales API

The Bandcamp Sales Report API gives you access to your sales report in JSON format. This report is also available through the Tools page on your band or label account.

The sales_report endpoint provides a synchronous response, which can take a while for larger reports. For more robust access to larger reports, the generate_sales_report and fetch_sales_report endpoints let you trigger asynchronous generation of a report and fetch it in a separate request. The asynchronous endpoints also offer a CSV download format.

All API calls should be POSTs with the Authorization header set to: 

Authorization: Bearer {your access token}

The unique ids for all your affiliated artists and labels can be found using the my_bands call to the Account API.

sales_report

version

URL

https://bandcamp.com/api/sales/4/sales_report

What’s changed in version 4?

  • Breaking: json output format changed from an object with arbitrary keys to an array. This fixes an issue where items with the same key could be lost.
  • Breaking: the csv format is deprecated. If you prefer a CSV, we recommend using the generate_sales_report and fetch_sales_report endpoints, which still accept the csv format option and give you a URL to download the CSV.
  • New bandcamp_transaction_item_id property added to JSON output format, which uniquely identifies an item within an order.
  • New bandcamp_related_transaction_id property added to refunds and reversals in the JSON output format, pointing to the bandcamp_transaction_id of the original payment.
Parameters
band_id
the unique id of the band or label you are calling as or on behalf of
member_band_id
(optional) the unique id of a band you wish to filter your results on, if you're calling as or on behalf of a label (you don't need this if you are calling on behalf of a band, just use that band's id in the band_id field)
start_time
the earliest UTC sale time an item could have and still be included in the results, i.e. start_time <= sale_item
end_time
(optional) the earliest UTC sale time (after start_time) an item could have and be excluded in the results, i.e. sale_item < end_time (default is the time of the call)
format
(deprecated) 'json' is the only format available

Example

Request

{
    "band_id": 1633770804,
    "member_band_id": 1925197437,
    "start_time": "2021-01-01 00:00:00",
    "end_time": "2021-02-01 00:00:00"
}

Response

The json format returns a report array within an object (this is different to v3): 

{
    "report": [
        (line item),
        (line item),
        ...
    ]
}

Line items look like:

{
    "bandcamp_transaction_id": 2095918850,
    "bandcamp_transaction_item_id": 142901548, // new in v4
    "bandcamp_related_transaction_id": null, // new in v4
    "date": "04 Jan 2021 23:22:11 GMT",
    "paid_to": "Bandcamp",
    "item_type": "album",
    "item_name": "Very Cool Band Greatest Hits",
    "artist": "Very Cool Band",
    "currency": "USD",
    "item_price": 9.99,
    "quantity": 1,
    "discount_code": null,
    "sub_total": 9.99,
    "additional_fan_contribution": 1.00,
    "seller_tax": null,
    "marketplace_tax": null,
    "tax_rate": null,
    "collection_society_share": null,
    "shipping": null,
    "ship_from_country_name": null,
    "transaction_fee": 0.49,
    "fee_type": "paypal",
    "item_total": 10.99,
    "amount_you_received":10.5,
    "paypal_transaction_id": null,
    "net_amount": 9.5,
    "package": "digital download",
    "option": null,
    "item_url": "https://verycoolband.bandcamp.com/album/very-cool-band-greatest-hits",
    "catalog_number": null,
    "upc": "",
    "isrc": "",
    "buyer_name": "Chris Jones",
    "buyer_email": "cjones@email.com",
    "buyer_phone": null,
    "buyer_note": null,
    "ship_to_name": "",
    "ship_to_street": "",
    "ship_to_street_2": "",
    "ship_to_city": null,
    "ship_to_state": null,
    "ship_to_zip": null,
    "ship_to_country": null,
    "ship_to_country_code": null,
    "ship_date": null,
    "ship_notes": null,
    "country": "United States",
    "country_code": "US",
    "region_or_state": "IL",
    "city": "Townsville",
    "referer": "Bandcamp search",
    "referer_url": "bandcamp.com/app/android/search",
    "sku": null
}

URL

https://bandcamp.com/api/sales/3/sales_report

What’s changed in version 3?

  • New columns have been added: tax rate and additional fan contribution. More info here.
Parameters
band_id
the unique id of the band or label you are calling as or on behalf of
member_band_id
(optional) the unique id of a band you wish to filter your results on, if you're calling as or on behalf of a label (you don't need this if you are calling on behalf of a band, just use that band's id in the band_id field)
start_time
the earliest UTC sale time an item could have and still be included in the results, i.e. start_time <= sale_item
end_time
(optional) the earliest UTC sale time (after start_time) an item could have and be excluded in the results, i.e. sale_item < end_time (default is the time of the call)
format
(optional) the format you wish to receive results in - either 'csv' or 'json' (default is 'json')

Example

JSON

Request

{
    "band_id": 1633770804,
    "member_band_id": 1925197437,
    "start_time": "2021-01-01 00:00:00",
    "end_time": "2021-02-01 00:00:00",
    "format": "json"
}

Response

Note: the fields here are ordered for the purposes of documentation, the actual response is an unordered JSON object. 
{
    "142901548": {
        "date": "04 Jan 2021 23:22:11 GMT",
        "paid_to": "Bandcamp",
        "item_type": "album",
        "item_name": "Very Cool Band Greatest Hits",
        "artist": "Very Cool Band",
        "currency": "USD",
        "item_price": 9.99,
        "quantity": 1,
        "discount_code": null,
        "sub_total": 9.99,
        "additional_fan_contribution": 1.00,
        "seller_tax": null,
        "marketplace_tax": null,
        "tax_rate": null,
        "collection_society_share": null,
        "shipping": null,
        "ship_from_country_name": null,
        "transaction_fee": 0.49,
        "fee_type": "paypal",
        "item_total": 10.99,
        "amount_you_received":10.5,
        "bandcamp_transaction_id": 2095918850,
        "paypal_transaction_id": null,
        "net_amount": 9.5,
        "package": "digital download",
        "option": null,
        "item_url": "https://verycoolband.bandcamp.com/album/very-cool-band-greatest-hits",
        "catalog_number": null,
        "upc": "",
        "isrc": "",
        "buyer_name": "Chris Jones",
        "buyer_email": "cjones@email.com",
        "buyer_phone": null,
        "buyer_note": null,
        "ship_to_name": "",
        "ship_to_street": "",
        "ship_to_street_2": "",
        "ship_to_city": null,
        "ship_to_state": null,
        "ship_to_zip": null,
        "ship_to_country": null,
        "ship_to_country_code": null,
        "ship_date": null,
        "ship_notes": null,
        "country": "United States",
        "country_code": "US",
        "region_or_state": "IL",
        "city": "Townsville",
        "referer": "Bandcamp search",
        "referer_url": "bandcamp.com/app/android/search",
        "sku": null
        },
    ...
}

CSV

Request

{
    "band_id": 1633770804,
    "member_band_id": 1925197437,
    "start_time": "2021-01-01 00:00:00",
    "end_time": "2021-02-01 00:00:00",
    "format": "csv"
}

Response

Note: the CSV fields here match the order of the fields in the JSON section. 
{
    "csv": "Mon Jan 04 23:22:11 UTC 2021,Bandcamp,album,Very Cool Band Greatest Hits,Very Cool Band,USD,9.99,1,,9.99,1.00,,,,,,,0.49,paypal,9.99,9.5,2095918850,,8.5,digital download,,https://verycoolband.bandcamp.com/album/very-cool-band-greatest-hits,,,,Chris Jones,cjones@email.com,,,,,,,,,,,,United States,US,IL,Townsville,Bandcamp search,bandcamp.com/app/android/search,|
    ..."
}

URL

https://bandcamp.com/api/sales/2/sales_report

What’s changed in version 2?

  • The tax column has been split into seller tax and marketplace tax. More info here.
Parameters
band_id
the unique id of the band or label you are calling as or on behalf of
member_band_id
(optional) the unique id of a band you wish to filter your results on, if you're calling as or on behalf of a label (you don't need this if you are calling on behalf of a band, just use that band's id in the band_id field)
start_time
the earliest UTC sale time an item could have and still be included in the results, i.e. start_time <= sale_item
end_time
(optional) the earliest UTC sale time (after start_time) an item could have and be excluded in the results, i.e. sale_item < end_time (default is the time of the call)
format
(optional) the format you wish to receive results in - either 'csv' or 'json' (default is 'json')

Example

JSON

Request

{
    "band_id": 1633770804,
    "member_band_id": 1925197437,
    "start_time": "2021-01-01 00:00:00",
    "end_time": "2021-02-01 00:00:00",
    "format": "json"
}

Response

Note: the fields here are ordered for the purposes of documentation, the actual response is an unordered JSON object. 
{
    "142901548": {
        "date": "04 Jan 2021 23:22:11 GMT",
        "paid_to": "Bandcamp",
        "item_type": "album",
        "item_name": "Very Cool Band Greatest Hits",
        "artist": "Very Cool Band",
        "currency": "USD",
        "item_price": 9.99,
        "quantity": 1,
        "discount_code": null,
        "sub_total": 9.99,
        "seller_tax": null,
        "marketplace_tax": null,
        "shipping": null,
        "ship_from_country_name": null,
        "transaction_fee": 0.49,
        "fee_type": "paypal",
        "item_total": 9.99,
        "amount_you_received": 9.5,
        "bandcamp_transaction_id": 2095918850,
        "paypal_transaction_id": null,
        "net_amount": 8.5,
        "package": "digital download",
        "option": null,
        "item_url": "https://verycoolband.bandcamp.com/album/very-cool-band-greatest-hits",
        "catalog_number": null,
        "upc": "",
        "isrc": "",
        "buyer_name": "Chris Jones",
        "buyer_email": "cjones@email.com",
        "buyer_phone": null,
        "buyer_note": null,
        "ship_to_name": "",
        "ship_to_street": "",
        "ship_to_street_2": "",
        "ship_to_city": null,
        "ship_to_state": null,
        "ship_to_zip": null,
        "ship_to_country": null,
        "ship_to_country_code": null,
        "ship_date": null,
        "ship_notes": null,
        "country": "United States",
        "country_code": "US",
        "region_or_state": "IL",
        "city": "Townsville",
        "referer": "Bandcamp search",
        "referer_url": "bandcamp.com/app/android/search",
        "sku": null
        },
    ...
}

CSV

Request

{
    "band_id": 1633770804,
    "member_band_id": 1925197437,
    "start_time": "2021-01-01 00:00:00",
    "end_time": "2021-02-01 00:00:00",
    "format": "csv"
}

Response

Note: the CSV fields here match the order of the fields in the JSON section. 
{
    "csv": "Mon Jan 04 23:22:11 UTC 2021,Bandcamp,album,Very Cool Band Greatest Hits,Very Cool Band,USD,9.99,1,,9.99,,,,,0.49,paypal,9.99,9.5,2095918850,,8.5,digital download,,https://verycoolband.bandcamp.com/album/very-cool-band-greatest-hits,,,,Chris Jones,cjones@email.com,,,,,,,,,,,,United States,US,IL,Townsville,Bandcamp search,bandcamp.com/app/android/search,|
    ..."
}

URL

https://bandcamp.com/api/sales/1/sales_report
Parameters
band_id
the unique id of the band or label you are calling as or on behalf of
member_band_id
(optional) the unique id of a band you wish to filter your results on, if you're calling as or on behalf of a label (you don't need this if you are calling on behalf of a band, just use that band's id in the band_id field)
start_time
the earliest UTC sale time an item could have and still be included in the results, i.e. start_time <= sale_item
end_time
(optional) the earliest UTC sale time (after start_time) an item could have and be excluded in the results, i.e. sale_item < end_time (default is the time of the call)
format
(optional) the format you wish to receive results in - either 'csv' or 'json' (default is 'json')

Example

JSON

Request

{
    "band_id": 1633770804,
    "member_band_id": 1925197437,
    "start_time": "2016-01-01 00:00:00",
    "end_time": "2016-02-01 00:00:00",
    "format": "json"
}

Response

Note: the fields here are ordered for the purposes of documentation, the actual response is an unordered JSON object. 
{
    "142901548": {
        "date": "04 Jan 2016 23:22:11 GMT",
        "paid_to": "Bandcamp",
        "item_type": "album",
        "item_name": "Very Cool Band Greatest Hits",
        "artist": "Very Cool Band",
        "currency": "USD",
        "item_price": 9.99,
        "quantity": 1,
        "discount_code": null,
        "sub_total": 9.99,
        "tax": null,
        "shipping": null,
        "ship_from_country_name": null,
        "transaction_fee": 0.49,
        "fee_type": "paypal",
        "item_total": 9.99,
        "amount_you_received": 9.5,
        "bandcamp_transaction_id": 2095918850,
        "paypal_transaction_id": null,
        "net_amount": 8.5,
        "package": "digital download",
        "option": null,
        "item_url": "https://verycoolband.bandcamp.com/album/very-cool-band-greatest-hits",
        "catalog_number": null,
        "upc": "",
        "isrc": "",
        "buyer_name": "Chris Jones",
        "buyer_email": "cjones@email.com",
        "buyer_phone": null,
        "buyer_note": null,
        "ship_to_name": "",
        "ship_to_street": "",
        "ship_to_street_2": "",
        "ship_to_city": null,
        "ship_to_state": null,
        "ship_to_zip": null,
        "ship_to_country": null,
        "ship_to_country_code": null,
        "ship_date": null,
        "ship_notes": null,
        "country": "United States",
        "country_code": "US",
        "region_or_state": "IL",
        "city": "Townsville",
        "referer": "Bandcamp search",
        "referer_url": "bandcamp.com/app/android/search",
        "sku": null
        },
    ...
}

CSV

Request

{
    "band_id": 1633770804,
    "member_band_id": 1925197437,
    "start_time": "2016-01-01 00:00:00",
    "end_time": "2016-02-01 00:00:00",
    "format": "csv"
}

Response

Note: the CSV fields here match the order of the fields in the JSON section. 
{
    "csv": "Mon Jan 04 23:22:11 UTC 2016,Bandcamp,album,Very Cool Band Greatest Hits,Very Cool Band,USD,9.99,1,,9.99,,,,0.49,paypal,9.99,9.5,2095918850,,8.5,digital download,,https://verycoolband.bandcamp.com/album/very-cool-band-greatest-hits,,,,Chris Jones,cjones@email.com,,,,,,,,,,,,United States,US,IL,Townsville,Bandcamp search,bandcamp.com/app/android/search,|
    ..."
}

generate_sales_report

version

Triggers generation of a sales report. Returns a token used to retrieve the generated report later.

URL

https://bandcamp.com/api/sales/4/generate_sales_report

What’s changed in version 4?

  • Breaking: json output format changed from an object with arbitrary keys to an array. This fixes an issue where items with the same key could be lost.
  • New bandcamp_transaction_item_id property added to JSON output format, which uniquely identifies an item within an order.
  • New bandcamp_related_transaction_id property added to refunds and reversals in the JSON output format, pointing to the bandcamp_transaction_id of the original payment.
Parameters
band_id
the unique id of the band or label you are calling as or on behalf of
member_band_id
(optional) the unique id of a band you wish to filter your results on, if you're calling as or on behalf of a label (you don't need this if you are calling on behalf of a band, just use that band's id in the band_id field)
start_time
the earliest UTC sale time an item could have and still be included in the results, i.e. start_time <= sale_item
end_time
(optional) the earliest UTC sale time (after start_time) an item could have and be excluded in the results, i.e. sale_item < end_time (default is the time of the call)
format
(optional) the format you wish to generate a report in - 'csv' or 'json' (default is 'json')

Example

Request

{
    "band_id": 1633770804,
    "member_band_id": 1925197437,
    "start_time": "2021-01-01 00:00:00",
    "end_time": "2021-02-01 00:00:00",
    "format": "json"
}

Response

{
    "token": "1633770804-c3e3910398c0009a2e43a01b286c9a60"
}

Triggers generation of a sales report. Returns a token used to retrieve the generated report later.

URL

https://bandcamp.com/api/sales/2/generate_sales_report
Parameters
band_id
the unique id of the band or label you are calling as or on behalf of
member_band_id
(optional) the unique id of a band you wish to filter your results on, if you're calling as or on behalf of a label (you don't need this if you are calling on behalf of a band, just use that band's id in the band_id field)
start_time
the earliest UTC sale time an item could have and still be included in the results, i.e. start_time <= sale_item
end_time
(optional) the earliest UTC sale time (after start_time) an item could have and be excluded in the results, i.e. sale_item < end_time (default is the time of the call)
format
(optional) the format you wish to generate a report in - 'csv' or 'json' (default is 'json')

Example

Request

{
    "band_id": 1633770804,
    "member_band_id": 1925197437,
    "start_time": "2021-01-01 00:00:00",
    "end_time": "2021-02-01 00:00:00",
    "format": "json"
}

Response

{
    "token": "1633770804-c3e3910398c0009a2e43a01b286c9a60"
}

fetch_sales_report

version

Returns a URL to download the sales report for a given token.

Note: reports generated in csv format include a header row.

URL

https://bandcamp.com/api/sales/4/fetch_sales_report

What’s changed in version 4?

  • Version number updated to match generate_sales_report
Parameters
token
the unique token returned from the generate_sales_report request

Example

Request

{
    "token": "1633770804-c3e3910398c0009a2e43a01b286c9a60"
}

Response

{
    "url": "https://bandcamp.com/file?id=93001130&name=1633770804-c3e3910398c0009a2e43a01b286c9a60&sig=yLkNPB4CEYOUKNuI5BttJ00KQo8%3D"
}

Error responses

{
    "error": true,
    "error_message": "Invalid token"
}
{
    "error": true,
    "error_message": "Report hasn't generated yet"
}

Returns a URL to download the sales report for a given token.

Note: reports generated in csv format include a header row.

URL

https://bandcamp.com/api/sales/2/fetch_sales_report
Parameters
token
the unique token returned from the generate_sales_report request

Example

Request

{
    "token": "1633770804-c3e3910398c0009a2e43a01b286c9a60"
}

Response

{
    "url": "https://bandcamp.com/file?id=93001130&name=1633770804-c3e3910398c0009a2e43a01b286c9a60&sig=yLkNPB4CEYOUKNuI5BttJ00KQo8%3D"
}

Error responses

{
    "error": true,
    "error_message": "Invalid token"
}
{
    "error": true,
    "error_message": "Report hasn't generated yet"
}