openapi: 3.0.2
info:
title: Etsy Open API v3 BuyerTaxonomy Shop Receipt API
description: <div class="wt-text-body-01"><p class="wt-pt-xs-2 wt-pb-xs-2">Etsy's Open API provides a simple RESTful interface for various Etsy.com features.</p><p class="wt-pb-xs-2">If you'd like to report an issue or provide feedback on the API design, <a target="_blank" class="wt-text-link wt-p-xs-0" href="https://github.com/etsy/open-api/discussions">please add an issue in Github</a>.</p></div>© 2021-2026 Etsy, Inc. All Rights Reserved. Use of this code is subject to Etsy's <a class='wt-text-link wt-p-xs-0' target='_blank' href='https://www.etsy.com/legal/api'>API Developer Terms of Use</a>.
termsOfService: https://www.etsy.com/legal/api
contact:
email: developers@etsy.com
version: 3.0.0
x-generated-from: https://www.etsy.com/openapi/generated/oas/3.0.0.json
x-last-validated: '2026-05-30'
servers:
- url: https://openapi.etsy.com
description: Etsy Open API v3 base URL (per Etsy developer documentation; live calls also resolve at https://api.etsy.com/v3/application).
security:
- api_key: []
tags:
- name: Shop Receipt
paths:
/v3/application/shops/{shop_id}/receipts/{receipt_id}:
get:
operationId: getShopReceipt
description: '<div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><span class="wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2">General Release</span><a class="wt-text-link" href="https://github.com/etsy/open-api/discussions" target="_blank" rel="noopener noreferrer">Report bug</a></div><div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><p class="wt-text-body-01 banner-text">This endpoint is ready for production use.</p></div>
Retrieves a receipt, identified by a receipt id, from an Etsy shop. **NOTE** Access to ShopReceipt''s first_line, second_line, city, state, zip, country_iso and formatted_address is contingent in some regions to a preferred partnership status with Etsy'
tags:
- Shop Receipt
parameters:
- name: shop_id
in: path
description: The unique positive non-zero numeric ID for an Etsy Shop.
required: true
schema:
type: integer
description: The unique positive non-zero numeric ID for an Etsy Shop.
format: int64
minimum: 1
example: 123456
- name: receipt_id
in: path
description: The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.
required: true
schema:
type: integer
description: The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.
format: int64
minimum: 1
example: 234567890
- name: legacy
in: query
description: This parameter needed to enable new parameters and response values related to processing profiles.
required: false
schema:
type: boolean
description: This parameter needed to enable new parameters and response values related to processing profiles.
example: true
responses:
'200':
description: A single Shop Receipt
content:
application/json:
schema:
$ref: '#/components/schemas/ShopReceipt'
examples:
GetShopReceipt200Example:
summary: Default getShopReceipt 200 response
x-microcks-default: true
value:
receipt_id: 234567890
receipt_type: 1
seller_user_id: 456789
seller_email: seller@example.com
buyer_user_id: 456789
buyer_email: seller@example.com
name: Handmade Ceramic Mug
first_line: 123 Main St
second_line: Apt 4B
city: Brooklyn
state: example string
zip: '11201'
status: paid
formatted_address: example string
country_iso: US
payment_method: example string
payment_email: seller@example.com
message_from_seller: Thanks for your order! Shipping out tomorrow.
message_from_buyer: Thanks for your order! Shipping out tomorrow.
message_from_payment: Thanks for your order! Shipping out tomorrow.
is_paid: true
is_shipped: true
create_timestamp: 1758153645
created_timestamp: 1758153645
update_timestamp: 1758153645
updated_timestamp: 1758153645
is_gift: true
gift_message: Thanks for your order! Shipping out tomorrow.
gift_sender: example string
grandtotal: example
subtotal: example
total_price: example
total_shipping_cost: example
total_tax_cost: example
total_vat_cost: example
discount_amt: example
gift_wrap_price: example
shipments:
- null
transactions:
- null
refunds:
- null
'404':
description: A resource could not be found. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetShopReceipt404Example:
summary: Default getShopReceipt 404 response
x-microcks-default: true
value:
error: example string
'403':
description: The request attempted to perform an operation it is not allowed to. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetShopReceipt403Example:
summary: Default getShopReceipt 403 response
x-microcks-default: true
value:
error: example string
'400':
description: There was a problem with the request data. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetShopReceipt400Example:
summary: Default getShopReceipt 400 response
x-microcks-default: true
value:
error: example string
'401':
description: The request lacks valid authentication credentials. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetShopReceipt401Example:
summary: Default getShopReceipt 401 response
x-microcks-default: true
value:
error: example string
'500':
description: The server encountered an internal error. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetShopReceipt500Example:
summary: Default getShopReceipt 500 response
x-microcks-default: true
value:
error: example string
security:
- api_key: []
oauth2:
- transactions_r
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
summary: Etsy Get Shop Receipt
put:
operationId: updateShopReceipt
description: '<div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><span class="wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2">General Release</span><a class="wt-text-link" href="https://github.com/etsy/open-api/discussions" target="_blank" rel="noopener noreferrer">Report bug</a></div><div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><p class="wt-text-body-01 banner-text">This endpoint is ready for production use.</p></div>
Updates the status of a receipt, identified by a receipt id, from an Etsy shop. **NOTE** Access to ShopReceipt''s first_line, second_line, city, state, zip, country_iso and formatted_address is contingent in some regions to a preferred partnership status with Etsy'
tags:
- Shop Receipt
parameters:
- name: shop_id
in: path
description: The unique positive non-zero numeric ID for an Etsy Shop.
required: true
schema:
type: integer
description: The unique positive non-zero numeric ID for an Etsy Shop.
format: int64
minimum: 1
example: 123456
- name: receipt_id
in: path
description: The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.
required: true
schema:
type: integer
description: The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.
format: int64
minimum: 1
example: 234567890
- name: legacy
in: query
description: This parameter needed to enable new parameters and response values related to processing profiles.
required: false
schema:
type: boolean
description: This parameter needed to enable new parameters and response values related to processing profiles.
example: true
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
was_shipped:
type: boolean
description: When `true`, returns receipts where the seller shipped the product(s) in this receipt. When `false`, returns receipts where shipment has not been set.
nullable: true
was_paid:
type: boolean
description: When `true`, returns receipts where the seller has received payment for the receipt. When `false`, returns receipts where payment has not been received.
nullable: true
examples:
UpdateShopReceiptRequestExample:
summary: Default updateShopReceipt request
x-microcks-default: true
value:
was_shipped: true
was_paid: true
responses:
'200':
description: Update A Shop Receipt
content:
application/json:
schema:
$ref: '#/components/schemas/ShopReceipt'
examples:
UpdateShopReceipt200Example:
summary: Default updateShopReceipt 200 response
x-microcks-default: true
value:
receipt_id: 234567890
receipt_type: 1
seller_user_id: 456789
seller_email: seller@example.com
buyer_user_id: 456789
buyer_email: seller@example.com
name: Handmade Ceramic Mug
first_line: 123 Main St
second_line: Apt 4B
city: Brooklyn
state: example string
zip: '11201'
status: paid
formatted_address: example string
country_iso: US
payment_method: example string
payment_email: seller@example.com
message_from_seller: Thanks for your order! Shipping out tomorrow.
message_from_buyer: Thanks for your order! Shipping out tomorrow.
message_from_payment: Thanks for your order! Shipping out tomorrow.
is_paid: true
is_shipped: true
create_timestamp: 1758153645
created_timestamp: 1758153645
update_timestamp: 1758153645
updated_timestamp: 1758153645
is_gift: true
gift_message: Thanks for your order! Shipping out tomorrow.
gift_sender: example string
grandtotal: example
subtotal: example
total_price: example
total_shipping_cost: example
total_tax_cost: example
total_vat_cost: example
discount_amt: example
gift_wrap_price: example
shipments:
- null
transactions:
- null
refunds:
- null
'404':
description: A resource could not be found. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
UpdateShopReceipt404Example:
summary: Default updateShopReceipt 404 response
x-microcks-default: true
value:
error: example string
'403':
description: The request attempted to perform an operation it is not allowed to. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
UpdateShopReceipt403Example:
summary: Default updateShopReceipt 403 response
x-microcks-default: true
value:
error: example string
'400':
description: There was a problem with the request data. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
UpdateShopReceipt400Example:
summary: Default updateShopReceipt 400 response
x-microcks-default: true
value:
error: example string
'401':
description: The request lacks valid authentication credentials. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
UpdateShopReceipt401Example:
summary: Default updateShopReceipt 401 response
x-microcks-default: true
value:
error: example string
'500':
description: The server encountered an internal error. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
UpdateShopReceipt500Example:
summary: Default updateShopReceipt 500 response
x-microcks-default: true
value:
error: example string
security:
- api_key: []
oauth2:
- transactions_w
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
summary: Etsy Update Shop Receipt
/v3/application/shops/{shop_id}/receipts:
get:
operationId: getShopReceipts
description: '<div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><span class="wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2">General Release</span><a class="wt-text-link" href="https://github.com/etsy/open-api/discussions" target="_blank" rel="noopener noreferrer">Report bug</a></div><div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><p class="wt-text-body-01 banner-text">This endpoint is ready for production use.</p></div>
Requests the Shop Receipts from a specific Shop, unfiltered or filtered by receipt id range or offset, date, paid, and/or shipped purchases. **NOTE** Access to ShopReceipt''s first_line, second_line, city, state, zip, country_iso and formatted_address is contingent in some regions to a preferred partnership status with Etsy'
tags:
- Shop Receipt
parameters:
- name: shop_id
in: path
description: The unique positive non-zero numeric ID for an Etsy Shop.
required: true
schema:
type: integer
description: The unique positive non-zero numeric ID for an Etsy Shop.
format: int64
minimum: 1
example: 123456
- name: min_created
in: query
description: The earliest unix timestamp for when a record was created.
required: false
schema:
type: integer
description: The earliest unix timestamp for when a record was created.
minimum: 946684800
default: null
example: 1
- name: max_created
in: query
description: The latest unix timestamp for when a record was created.
required: false
schema:
type: integer
description: The latest unix timestamp for when a record was created.
minimum: 946684800
default: null
example: 1
- name: min_last_modified
in: query
description: The earliest unix timestamp for when a record last changed.
required: false
schema:
type: integer
description: The earliest unix timestamp for when a record last changed.
minimum: 946684800
default: null
example: 1
- name: max_last_modified
in: query
description: The latest unix timestamp for when a record last changed.
required: false
schema:
type: integer
description: The latest unix timestamp for when a record last changed.
minimum: 946684800
default: null
example: 1
- name: limit
in: query
description: The maximum number of results to return.
required: false
schema:
type: integer
description: The maximum number of results to return.
minimum: 1
maximum: 100
default: 25
example: 25
- name: offset
in: query
description: The number of records to skip before selecting the first result.
required: false
schema:
type: integer
description: The number of records to skip before selecting the first result.
minimum: 0
default: 0
example: 0
- name: sort_on
in: query
description: The value to sort a search result of listings on.
required: false
schema:
type: string
description: The value to sort a search result of listings on.
enum:
- created
- updated
- receipt_id
default: created
example: created
- name: sort_order
in: query
description: The ascending(up) or descending(down) order to sort receipts by.
required: false
schema:
type: string
description: The ascending(up) or descending(down) order to sort receipts by.
enum:
- asc
- ascending
- desc
- descending
- up
- down
default: desc
example: asc
- name: was_paid
in: query
description: When `true`, returns receipts where the seller has received payment for the receipt. When `false`, returns receipts where payment has not been received.
required: false
schema:
type: boolean
description: When `true`, returns receipts where the seller has received payment for the receipt. When `false`, returns receipts where payment has not been received.
nullable: true
example: true
- name: was_shipped
in: query
description: When `true`, returns receipts where the seller shipped the product(s) in this receipt. When `false`, returns receipts where shipment has not been set.
required: false
schema:
type: boolean
description: When `true`, returns receipts where the seller shipped the product(s) in this receipt. When `false`, returns receipts where shipment has not been set.
nullable: true
example: true
- name: was_delivered
in: query
description: When `true`, returns receipts that have been marked as delivered. When `false`, returns receipts where shipment has not been marked as delivered.
required: false
schema:
type: boolean
description: When `true`, returns receipts that have been marked as delivered. When `false`, returns receipts where shipment has not been marked as delivered.
nullable: true
example: true
- name: was_canceled
in: query
description: When `true`, the endpoint will only return the canceled receipts. When `false`, the endpoint will only return non-canceled receipts.
required: false
schema:
type: boolean
description: When `true`, the endpoint will only return the canceled receipts. When `false`, the endpoint will only return non-canceled receipts.
nullable: true
example: true
- name: legacy
in: query
description: This parameter needed to enable new parameters and response values related to processing profiles.
required: false
schema:
type: boolean
description: This parameter needed to enable new parameters and response values related to processing profiles.
example: true
responses:
'200':
description: A list of Shop Receipts
content:
application/json:
schema:
$ref: '#/components/schemas/ShopReceipts'
examples:
GetShopReceipts200Example:
summary: Default getShopReceipts 200 response
x-microcks-default: true
value:
count: 1
results:
- null
'403':
description: The request attempted to perform an operation it is not allowed to. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetShopReceipts403Example:
summary: Default getShopReceipts 403 response
x-microcks-default: true
value:
error: example string
'404':
description: A resource could not be found. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetShopReceipts404Example:
summary: Default getShopReceipts 404 response
x-microcks-default: true
value:
error: example string
'400':
description: There was a problem with the request data. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetShopReceipts400Example:
summary: Default getShopReceipts 400 response
x-microcks-default: true
value:
error: example string
'401':
description: The request lacks valid authentication credentials. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetShopReceipts401Example:
summary: Default getShopReceipts 401 response
x-microcks-default: true
value:
error: example string
'500':
description: The server encountered an internal error. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
GetShopReceipts500Example:
summary: Default getShopReceipts 500 response
x-microcks-default: true
value:
error: example string
security:
- api_key: []
oauth2:
- transactions_r
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
summary: Etsy Get Shop Receipts
/v3/application/shops/{shop_id}/receipts/{receipt_id}/tracking:
post:
operationId: createReceiptShipment
description: '<div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><span class="wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2">General Release</span><a class="wt-text-link" href="https://github.com/etsy/open-api/discussions" target="_blank" rel="noopener noreferrer">Report bug</a></div><div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><p class="wt-text-body-01 banner-text">This endpoint is ready for production use.</p></div>
Submits tracking information for a Shop Receipt, which creates a Shop Receipt Shipment entry for the given receipt_id. Each time you successfully submit tracking info, Etsy sends a notification email to the buyer User. When send_bcc is true, Etsy sends shipping notifications to the seller as well. When tracking_code and carrier_name aren''t sent, the receipt is marked as shipped only. If the carrier is not supported, you may use `other` as the carrier name so you can provide the tracking code. **NOTES** When shipping within the United States AND the order is over $10 _or_ when shipping to India, tracking code and carrier name ARE required. Access to ShopReceipt''s first_line, second_line, city, state, zip, country_iso and formatted_address is contingent in some regions to a preferred partnership status with Etsy'
tags:
- Shop Receipt
parameters:
- name: shop_id
in: path
description: The unique positive non-zero numeric ID for an Etsy Shop.
required: true
schema:
type: integer
description: The unique positive non-zero numeric ID for an Etsy Shop.
format: int64
minimum: 1
example: 123456
- name: receipt_id
in: path
description: The receipt to submit tracking for.
required: true
schema:
type: integer
description: The receipt to submit tracking for.
format: int64
minimum: 1
example: 234567890
- name: legacy
in: query
description: This parameter needed to enable new parameters and response values related to processing profiles.
required: false
schema:
type: boolean
description: This parameter needed to enable new parameters and response values related to processing profiles.
example: true
requestBody:
content:
application/json:
schema:
type: object
properties:
tracking_code:
type: string
description: The tracking code for this receipt.
carrier_name:
type: string
description: The carrier name for this receipt.
send_bcc:
type: boolean
description: If true, the shipping notification will be sent to the seller as well
note_to_buyer:
type: string
description: Message to include in notification to the buyer.
mail_class:
type: string
description: The service level of postal or carrier service selected for the shipment (e.g., First-Class, Priority, Ground, Express).
nullable: true
weight:
type: number
description: The total weight of the package.
format: float
nullable: true
weight_units:
type: string
description: Unit of measurement used for package weight (oz, grams, etc.).
nullable: true
length:
type: number
description: Longest side of the package.
format: float
nullable: true
width:
type: number
description: Second longest side of the package.
format: float
nullable: true
height:
type: number
description: Third longest side of the package.
format: float
nullable: true
dimension_units:
type: string
description: Unit of measurement used for package dimensions (in, cm...).
nullable: true
shipping_label_cost:
type: number
description: The purchase price the seller paid for the shipping label.
format: float
nullable: true
shipping_label_currency:
type: string
description: The currency in which the shipping label was purchased.
nullable: true
revenue_eligibility:
type: string
description: A flag indicating if the shipment is tied to a revenue share agreement between Etsy and the vendor.
nullable: true
ship_from_country:
type: string
description: Where the package ships from.
nullable: true
ship_to_country:
type: string
description: Package destination.
nullable: true
incoterm:
type: string
description: The specific incoterm (e.g., DDU, DDP) designated for the shipment.
nullable: true
customs_data:
type: array
description: Contains custom data like country of origin, declared value and HS code.
nullable: true
items:
type: object
properties:
country_of_origin:
type: string
description: The country in which the goods originate from.
nullable: true
default: null
declared_value:
type: number
description: The commercial value of the goods.
format: float
nullable: true
default: null
HS_code:
type: string
description: The standardized global system (Harmonized System) for classifying traded products.
nullable: true
default: null
required:
- country_of_origin
- declared_value
- HS_code
duty_amount:
type: number
description: The
# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/etsy/refs/heads/main/openapi/etsy-shop-receipt-api-openapi.yml