Open API v2 will be deprecated on April 3, 2023. Please begin transitioning to Open API v3 as soon as possible. As of September 29, 2022 all new apps will only be permitted to use Open API v3.

API Documentation

BillCharge

Overview

Represents a charge to an Etsy member's account.

BillCharge Types

The type field of BillCharge indicates what the charge is:

Type Associated type_id Meaning
listing listing_id Seller fee for listing an item.
edit listing_id Seller fee if listing quantity increased.
renew listing_id Seller fee for renewing active listing.
renew_sold listing_id Seller fee for renewing sold listing.
renew_sold_auto listing_id Seller fee for (automatically) renewing listing after a sale.
transaction_quantity transaction_id Seller fee for a sale of listing with multiple quantity.
renew_expired listing_id Seller fee for renewing expired listing.
transaction transaction_id Seller fee for sold item.
wholesale_contract Seller fee for a wholesale contract.
wholesale_transaction transaction_id Seller fee for sold wholesale item.
shipping_labels shipping_label_id Seller fee for postage and additional fees.
shipping_label_insurance shipping_label_id Seller fee for postage insurance (USPS only).
shipping_label_coverage shipping_label_id Seller fee for postage coverage (Canada Post only).
shipping_label_taxes shipping_label_id Seller fee for postage taxes (Canada Post only).
shipping_label_adjustment shipping_label_id Seller fee for adjusted postage (Canada Post only).
shipping_label_adjustment_taxes shipping_label_id Seller fee for adjusted postage taxes (Canada Post only).
etsy_asap postmates_delivery_id Seller fee for Etsy ASAP Delivery.
search_ads campaign_instance_id Seller fee for purchased search ads.
listing_private listing_id Seller fee for listing a private listing.
showcase_category showcase_reservation_id Seller fee for current Showcase feature.
prolist Seller fee for a promoted listing.
wholesale_setup_fee Seller fee for joining the wholesale marketplace.
vat_tax transaction_id Seller fee for sold digital download to buyer in VAT-eligible country
showcase showcase_reservation_id (DEPRECATED) Seller fee for original Showcase feature.
alchemy listing_id (DEPRECATED) Seller fee for Alchemy feature.

getUserChargesMetadata

Method Name getUserChargesMetadata
Synopsis Metadata for the set of BillCharges objects associated to a User
HTTP Method GET
URI /users/:user_id/charges/meta
Parameters
Name Required Default Type
user_id Y   user_id_or_name
Requires OAuth Y
Permission Scope billing_r

Fields

Field Visibility Level Permission Scope Type Description
bill_charge_id private billing_r int The numeric ID for this bill charge record.
creation_tsz private billing_r float Creation time, in epoch seconds.
type private billing_r string The name of the type of charge.
type_id private billing_r int The Listing, Transaction or Shipping Label ID to which the charge applies.
user_id private billing_r int The user's numeric ID.
amount private billing_r float The amount charged.
currency_code private billing_r string The currency of the charge.
creation_year private billing_r int Year that the charge was created.
creation_month private billing_r int Month that the charge was created.
last_modified_tsz private billing_r float Time when charge was last modified.

Associations

This resource has no associations.

Methods

findAllUserCharges

Method Name findAllUserCharges
Synopsis Retrieves a set of BillCharge objects associated to a User. NOTE: from 8/8/12 the min_created and max_created arguments will be mandatory and can be no more than 31 days apart.
HTTP Method GET
URI /users/:user_id/charges
Parameters
Name Required Default Type
limit N 25 int
offset N 0 int
page N   int
user_id Y   user_id_or_name
sort_order N up enum(up, down)
min_created N   epoch
max_created N   epoch
Requires OAuth Y
Permission Scope billing_r

Open API v3New

Your developer account