REST API reference

Bandcamp API

13 endpoints for Bandcamp. Each one is a POST with a JSON body, called with your API key.

Base URL
https://cotlet.dev/api/v1/bandcamp
Connects with
Your own Bandcamp artist or label account
Integration page
Bandcamp
Bandcamp Endpoints
Endpoint Access Description
list_releases read Albums and tracks on your account with price, release date and visibility.
list_sales read Sales line items for a date range, with the net amount of each.
export_sales_report read One of the three reports from your Tools page for a date range.
list_merch_orders read Orders from your Merch Orders page with items, buyer and shipping address.
list_merch_items read Merch items with price, SKU, quantity sold and quantity available, per option.
list_track_album_codes read Your code batches with how many are redeemed; with batch_id, the codes of one batch.
mark_order_shipped write Mark a merch order shipped; Bandcamp emails the buyer with the tracking number and note.
refund_merch_order write Refund a physical order from the last 180 days and optionally return the item to stock.
update_merch_quantity write Set how many of a merch item or option are available.
update_release write Change the price, title or release date of an album or track.
create_discount_code write New discount code that fans enter in the Buy Now dialog.
generate_track_album_codes write New batch of one-use codes fans redeem for a download, counted against your code allowance.
send_community_message write Post a message to your Community page; followers get it by email and in the Bandcamp app.

List releases

read

POST https://cotlet.dev/api/v1/bandcamp/list_releases

Lists the releases on your account, the same items the Bulk Edit page shows. Filter by digital or physical and by public, private or draft. Use release_id from each item in the other tools.

Parameters

Parameters: list_releases
NameTypeDescription
format enum digital, physical or all. Default: all.
visibility enum public, private, draft or all. Default: all.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bandcamp/list_releases \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("bandcamp", "list_releases")
Node.js
const result = await cotlet.call('bandcamp', 'list_releases');
CLI
cotlet call bandcamp list_releases

Example response

{
  "releases": [
    {
      "release_id": "r_1840221",
      "title": "Night Drive",
      "format": "digital",
      "visibility": "public",
      "price": 9,
      "currency": "USD",
      "release_date": "2025-11-14",
      "url": "https://yourname.bandcamp.com/album/night-drive"
    },
    {
      "release_id": "r_1902254",
      "title": "Tour EP",
      "format": "digital",
      "visibility": "draft",
      "price": 5,
      "currency": "USD",
      "release_date": "2026-11-01",
      "url": "https://yourname.bandcamp.com/album/tour-ep"
    }
  ]
}

List sales

read

POST https://cotlet.dev/api/v1/bandcamp/list_sales

Returns the lines of your raw data sales report, oldest first: each line is the sale of an item, a payout or a sale reversal. Use export_sales_report for the revenue summary or the payout statement.

Parameters

Parameters: list_sales
NameTypeDescription
since date Start of the date range. Default: 30 days ago.
until date End of the date range. Default: today.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bandcamp/list_sales \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("bandcamp", "list_sales")
Node.js
const result = await cotlet.call('bandcamp', 'list_sales');
CLI
cotlet call bandcamp list_sales

Example response

{
  "sales": [
    {
      "date": "2026-09-03T18:22:11Z",
      "type": "sale",
      "item_type": "album",
      "item_name": "Night Drive",
      "quantity": 1,
      "currency": "USD",
      "net_amount": 8.5
    },
    {
      "date": "2026-09-04T09:10:42Z",
      "type": "sale",
      "item_type": "package",
      "item_name": "Night Drive (12\" vinyl)",
      "quantity": 1,
      "currency": "USD",
      "net_amount": 24.1
    }
  ]
}

Export sales report

read

POST https://cotlet.dev/api/v1/bandcamp/export_sales_report

Returns the report you pick: revenue_summary (gross and net revenue, shipping and tax for a release or the whole catalog), payout_statement (which sales are in each bulk payout) or raw_data. For revenue_summary you can narrow the report to one release.

Parameters

Parameters: export_sales_report
NameTypeDescription
report required enum revenue_summary, payout_statement or raw_data.
since date Start of the date range. Default: 30 days ago.
until date End of the date range. Default: today.
release_id string revenue_summary only: limit the report to this release.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bandcamp/export_sales_report \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"report":"revenue_summary","since":"2026-09-01","until":"2026-09-30"}'
Python
result = client.call("bandcamp", "export_sales_report", {"report":"revenue_summary","since":"2026-09-01","until":"2026-09-30"})
Node.js
const result = await cotlet.call('bandcamp', 'export_sales_report', {"report":"revenue_summary","since":"2026-09-01","until":"2026-09-30"});
CLI
cotlet call bandcamp export_sales_report --data '{"report":"revenue_summary","since":"2026-09-01","until":"2026-09-30"}'

Example response

{
  "report": "revenue_summary",
  "since": "2026-09-01",
  "until": "2026-09-30",
  "currency": "USD",
  "gross_revenue": 1842.5,
  "net_revenue": 1713.1,
  "releases": [
    {
      "release_id": "r_1840221",
      "title": "Night Drive",
      "net_revenue": 1204.3
    },
    {
      "release_id": "r_1902254",
      "title": "Tour EP",
      "net_revenue": 508.8
    }
  ]
}

List merch orders

read

POST https://cotlet.dev/api/v1/bandcamp/list_merch_orders

Lists physical orders from your Merch Orders page, newest first, with the items bought, the buyer, the shipping address and whether the order shipped. By default only unshipped orders. Search by email, last name or Bandcamp payment ID. Pass order_id to mark_order_shipped or refund_merch_order.

Parameters

Parameters: list_merch_orders
NameTypeDescription
unshipped_only boolean Only orders not marked shipped. Default: true.
search string Buyer email, last name or Bandcamp payment ID.
since date Start of the date range. Default: 30 days ago.
until date End of the date range. Default: today.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bandcamp/list_merch_orders \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("bandcamp", "list_merch_orders")
Node.js
const result = await cotlet.call('bandcamp', 'list_merch_orders');
CLI
cotlet call bandcamp list_merch_orders

Example response

{
  "orders": [
    {
      "order_id": "4471025938",
      "ordered_at": "2026-10-08T14:03:00Z",
      "shipped": false,
      "buyer": {
        "name": "Maya Brandt",
        "email": "maya@example.com"
      },
      "ship_to": {
        "name": "Maya Brandt",
        "city": "Leeds",
        "country": "United Kingdom",
        "country_code": "GB"
      },
      "items": [
        {
          "title": "Night Drive (12\" vinyl)",
          "option": "Black",
          "quantity": 1
        }
      ]
    }
  ]
}

List merch items

read

POST https://cotlet.dev/api/v1/bandcamp/list_merch_items

Lists the merch on your account with price, SKU, how many were sold and how many are available. Items with sizes or colors list each option. Quantities are kept per shipping origin. An item with no limit shows quantity_available as null.

Parameters

Parameters: list_merch_items
NameTypeDescription
low_stock_below integer Only items with fewer available than this.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bandcamp/list_merch_items \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("bandcamp", "list_merch_items")
Node.js
const result = await cotlet.call('bandcamp', 'list_merch_items');
CLI
cotlet call bandcamp list_merch_items

Example response

{
  "items": [
    {
      "item_id": "p_1154611570",
      "title": "Band Tote",
      "sku": "GGRA3-1",
      "price": 12,
      "currency": "USD",
      "quantity_sold": 4,
      "quantity_available": 6,
      "options": []
    },
    {
      "item_id": "p_175167691",
      "title": "Night Drive (12\" vinyl)",
      "sku": "ND-LP",
      "price": 25.5,
      "currency": "USD",
      "quantity_sold": 12,
      "quantity_available": 8,
      "options": [
        {
          "item_id": "o_1842702675",
          "title": "Black",
          "sku": "ND-LP-B",
          "quantity_sold": 9,
          "quantity_available": 3
        },
        {
          "item_id": "o_1842702676",
          "title": "Red",
          "sku": "ND-LP-R",
          "quantity_sold": 3,
          "quantity_available": 5
        }
      ]
    }
  ]
}

List track/album codes

read

POST https://cotlet.dev/api/v1/bandcamp/list_track_album_codes

Without batch_id, returns each batch with its release, size and redeemed count, as the Track/album codes section of your Tools page does. With batch_id, returns every code of that batch and whether it was redeemed.

Parameters

Parameters: list_track_album_codes
NameTypeDescription
batch_id string Batch ID from a previous call. Returns the codes of this batch.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bandcamp/list_track_album_codes \
  -H "Authorization: Bearer $COTLET_API_KEY"
Python
result = client.call("bandcamp", "list_track_album_codes")
Node.js
const result = await cotlet.call('bandcamp', 'list_track_album_codes');
CLI
cotlet call bandcamp list_track_album_codes

Example response

{
  "batches": [
    {
      "batch_id": "b_0042",
      "batch_name": "tour-2026",
      "release_title": "Tour EP",
      "codes": 100,
      "redeemed": 37
    }
  ]
}

Mark order shipped

write Confirm

POST https://cotlet.dev/api/v1/bandcamp/mark_order_shipped

Marks one order shipped. Bandcamp then emails the buyer with the tracking number and note you pass. One order per call. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: mark_order_shipped
NameTypeDescription
order_id required string Order ID from list_merch_orders.
tracking_number string Tracking number shown to the buyer.
note string Note for the buyer in the shipping email.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bandcamp/mark_order_shipped \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"4471025938","tracking_number":"9400111899223344556677","note":"Thanks for the support! Your LP is on its way."}'
Python
result = client.call("bandcamp", "mark_order_shipped", {"order_id":"4471025938","tracking_number":"9400111899223344556677","note":"Thanks for the support! Your LP is on its way."})
Node.js
const result = await cotlet.call('bandcamp', 'mark_order_shipped', {"order_id":"4471025938","tracking_number":"9400111899223344556677","note":"Thanks for the support! Your LP is on its way."});
CLI
cotlet call bandcamp mark_order_shipped --data '{"order_id":"4471025938","tracking_number":"9400111899223344556677","note":"Thanks for the support! Your LP is on its way."}'

Example response

{
  "order_id": "4471025938",
  "status": "shipped",
  "tracking_number": "9400111899223344556677",
  "note": "Thanks for the support! Your LP is on its way.",
  "buyer_notified": true,
  "items": [
    {
      "title": "Night Drive (12\" vinyl)",
      "option": "Black",
      "quantity": 1
    }
  ]
}

Refund merch order

write Confirm

POST https://cotlet.dev/api/v1/bandcamp/refund_merch_order

Refunds a physical order the way the "refund this order" link on the Merch Orders page does, and your revenue share adjusts. It works for orders placed in the last 180 days and not under a dispute; for older orders the call fails and you refund the fan yourself, for example through PayPal. Digital purchases are refunded through Bandcamp Support. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: refund_merch_order
NameTypeDescription
order_id required string Order ID from list_merch_orders.
return_to_stock boolean Put the item back into your inventory. Default: false.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bandcamp/refund_merch_order \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"order_8c41d2"}'
Python
result = client.call("bandcamp", "refund_merch_order", {"order_id":"order_8c41d2"})
Node.js
const result = await cotlet.call('bandcamp', 'refund_merch_order', {"order_id":"order_8c41d2"});
CLI
cotlet call bandcamp refund_merch_order --data '{"order_id":"order_8c41d2"}'

Example response

{
  "order_id": "4471025938",
  "status": "refunded",
  "restocked": true
}

Update merch quantity

write

POST https://cotlet.dev/api/v1/bandcamp/update_merch_quantity

Sets the available quantity of an item or one of its options at a shipping origin. Bandcamp lowers it by itself when an item sells, so use this when you also sell elsewhere. 0 marks the item Sold Out. It runs without asking first: it reaches no one and one more call sets the old number back.

Parameters

Parameters: update_merch_quantity
NameTypeDescription
item_id required string Item or option ID from list_merch_items.
quantity_available required integer New stock level. 0 marks the item Sold Out.
shipping_origin string Shipping origin to change. Default: your main origin.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bandcamp/update_merch_quantity \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"item_id":"o_1842702675","quantity_available":6,"shipping_origin":"Tour van"}'
Python
result = client.call("bandcamp", "update_merch_quantity", {"item_id":"o_1842702675","quantity_available":6,"shipping_origin":"Tour van"})
Node.js
const result = await cotlet.call('bandcamp', 'update_merch_quantity', {"item_id":"o_1842702675","quantity_available":6,"shipping_origin":"Tour van"});
CLI
cotlet call bandcamp update_merch_quantity --data '{"item_id":"o_1842702675","quantity_available":6,"shipping_origin":"Tour van"}'

Example response

{
  "item_id": "p_1154611570",
  "title": "Band Tote",
  "quantity_available": 40,
  "previous_quantity_available": 6
}

Update release

write Confirm

POST https://cotlet.dev/api/v1/bandcamp/update_release

Changes the price, title or release date of one album or track, like the edit button on its page or the Bulk Edit page. Pass only the fields you want to change. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: update_release
NameTypeDescription
release_id required string Album or track ID from list_releases.
price number New price.
title string New title.
release_date date New release date.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bandcamp/update_release \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"release_id":"release_8c41d2"}'
Python
result = client.call("bandcamp", "update_release", {"release_id":"release_8c41d2"})
Node.js
const result = await cotlet.call('bandcamp', 'update_release', {"release_id":"release_8c41d2"});
CLI
cotlet call bandcamp update_release --data '{"release_id":"release_8c41d2"}'

Example response

{
  "release_id": "r_1840221",
  "title": "Night Drive",
  "price": 7,
  "currency": "USD",
  "release_date": "2025-11-14",
  "updated": [
    "price"
  ]
}

Create discount code

write Confirm

POST https://cotlet.dev/api/v1/bandcamp/create_discount_code

Creates a discount code. The percentage applies to the base price of the item, never to shipping or taxes. Codes cannot take a release priced at zero, and 100% off is not offered. If you set expires_on, Bandcamp disables the code on that day. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: create_discount_code
NameTypeDescription
name required string The code fans type, e.g. summersale.
percent_off required integer Percent off the base price. 100 is not offered.
applies_to enum anything, anything_except_preorders, digital_only, physical_only or single_item. Default: anything.
item_id string Release or package ID when applies_to is single_item.
expires_on date Bandcamp disables the code on this day.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bandcamp/create_discount_code \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"NIGHTDRIVE20","percent_off":20,"applies_to":"single_item","item_id":"r_1840221","expires_on":"2026-10-31"}'
Python
result = client.call("bandcamp", "create_discount_code", {"name":"NIGHTDRIVE20","percent_off":20,"applies_to":"single_item","item_id":"r_1840221","expires_on":"2026-10-31"})
Node.js
const result = await cotlet.call('bandcamp', 'create_discount_code', {"name":"NIGHTDRIVE20","percent_off":20,"applies_to":"single_item","item_id":"r_1840221","expires_on":"2026-10-31"});
CLI
cotlet call bandcamp create_discount_code --data '{"name":"NIGHTDRIVE20","percent_off":20,"applies_to":"single_item","item_id":"r_1840221","expires_on":"2026-10-31"}'

Example response

{
  "code": "summersale",
  "percent_off": 20,
  "applies_to": "single_item",
  "item_id": "r_1840221",
  "expires_on": "2026-08-31",
  "status": "active"
}

Generate track/album codes

write Confirm

POST https://cotlet.dev/api/v1/bandcamp/generate_track_album_codes

Creates a batch of track/album codes for a release you choose. Codes come in multiples of 100 with a minimum of 100 per batch, never expire, and count against the code allowance shown on your Tools page. The batch name is private to you. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: generate_track_album_codes
NameTypeDescription
release_id required string Album or track ID from list_releases.
batch_name required string Private label for the batch, e.g. tour-2026.
count required integer Multiples of 100, at least 100.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bandcamp/generate_track_album_codes \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"release_id":"release_8c41d2","batch_name":"batch name","count":20}'
Python
result = client.call("bandcamp", "generate_track_album_codes", {"release_id":"release_8c41d2","batch_name":"batch name","count":20})
Node.js
const result = await cotlet.call('bandcamp', 'generate_track_album_codes', {"release_id":"release_8c41d2","batch_name":"batch name","count":20});
CLI
cotlet call bandcamp generate_track_album_codes --data '{"release_id":"release_8c41d2","batch_name":"batch name","count":20}'

Example response

{
  "batch_id": "b_0042",
  "batch_name": "tour-2026",
  "release_id": "r_1902254",
  "codes_created": 100
}

Send Community message

write Confirm

POST https://cotlet.dev/api/v1/bandcamp/send_community_message

Posts a message under your artist name. Fans who follow you receive it by email and in the Bandcamp app, and it appears on your Community page. Fans need to follow you to receive messages and to buy a release before they can comment. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: send_community_message
NameTypeDescription
body required string Message text.

Request

cURL
curl -X POST https://cotlet.dev/api/v1/bandcamp/send_community_message \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"body"}'
Python
result = client.call("bandcamp", "send_community_message", {"body":"body"})
Node.js
const result = await cotlet.call('bandcamp', 'send_community_message', {"body":"body"});
CLI
cotlet call bandcamp send_community_message --data '{"body":"body"}'

Example response

{
  "message_id": "cm_2207",
  "status": "published",
  "published_at": "2026-10-11T10:00:00+02:00"
}