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: '
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: '
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: '
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 estimated or actual amount of import duties and taxes assessed by customs for the shipment.
format: float
nullable: true
duty_currency:
type: string
description: The currency in which the duty was paid.
nullable: true
ship_date:
type: string
description: The date package was shipped.
nullable: true
examples:
CreateReceiptShipmentRequestExample:
summary: Default createReceiptShipment request
x-microcks-default: true
value:
tracking_code: example string
carrier_name: example string
send_bcc: true
note_to_buyer: example string
mail_class: example string
weight: 1.0
weight_units: example string
length: 1.0
width: 1.0
height: 1.0
dimension_units: example string
shipping_label_cost: 1.0
shipping_label_currency: example string
revenue_eligibility: example string
ship_from_country: example string
ship_to_country: example string
incoterm: example string
customs_data:
- country_of_origin: example string
declared_value: 1.0
HS_code: example string
duty_amount: 1.0
duty_currency: example string
ship_date: example string
responses:
'200':
description: A single ShopReceipt
content:
application/json:
schema:
$ref: '#/components/schemas/ShopReceipt'
examples:
CreateReceiptShipment200Example:
summary: Default createReceiptShipment 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:
CreateReceiptShipment404Example:
summary: Default createReceiptShipment 404 response
x-microcks-default: true
value:
error: example string
'409':
description: There was a request conflict with the current state of the target resource. See the error message for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSchema'
examples:
CreateReceiptShipment409Example:
summary: Default createReceiptShipment 409 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:
CreateReceiptShipment403Example:
summary: Default createReceiptShipment 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:
CreateReceiptShipment400Example:
summary: Default createReceiptShipment 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:
CreateReceiptShipment401Example:
summary: Default createReceiptShipment 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:
CreateReceiptShipment500Example:
summary: Default createReceiptShipment 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 Create Receipt Shipment
components:
schemas:
ErrorSchema:
type: object
x-resource-id: ErrorSchema
required:
- error
properties:
error:
type: string
example: example string
ShopReceipt:
type: object
x-resource-id: ShopReceipt
description: The record of a purchase from a shop. Shop receipts display monetary values using the shop's currency.
properties:
receipt_id:
type: integer
description: The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.
format: int64
minimum: 1
example: 234567890
receipt_type:
type: integer
description: 'The numeric value for the Etsy channel that serviced the purchase: 0 or 5 for Etsy.com, 1 for a Pattern shop.'
minimum: 0
example: 1
seller_user_id:
type: integer
description: The numeric ID for the [user](/documentation/reference#tag/User) (seller) fulfilling the purchase.
format: int64
minimum: 1
example: 456789
seller_email:
type: string
description: The email address string for the seller of the listing.
format: email
nullable: true
example: seller@example.com
buyer_user_id:
type: integer
description: The numeric ID for the [user](/documentation/reference#tag/User) making the purchase.
format: int64
minimum: 1
example: 456789
buyer_email:
type: string
description: The email address string for the buyer of the listing. It will be null if access hasn't been granted. Access is case-by-case and subject to approval.
nullable: true
example: seller@example.com
name:
type: string
description: The name string for the recipient in the shipping address.
example: Handmade Ceramic Mug
first_line:
type: string
description: The first address line string for the recipient in the shipping address.
nullable: true
example: 123 Main St
second_line:
type: string
description: The optional second address line string for the recipient in the shipping address.
nullable: true
example: Apt 4B
city:
type: string
description: The city string for the recipient in the shipping address.
nullable: true
example: Brooklyn
state:
type: string
description: The state string for the recipient in the shipping address.
nullable: true
example: example string
zip:
type: string
description: The zip code string (not necessarily a number) for the recipient in the shipping address.
nullable: true
example: '11201'
status:
type: string
description: 'The current order status string. One of: `paid`, `completed`, `open`, `payment processing` or `canceled`.'
enum:
- paid
- completed
- open
- payment processing
- canceled
- fully refunded
- partially refunded
example: paid
formatted_address:
type: string
description: The formatted shipping address string for the recipient in the shipping address.
nullable: true
example: example string
country_iso:
type: string
description: The ISO-3166 alpha-2 country code string for the recipient in the shipping address.
nullable: true
example: US
payment_method:
type: string
description: 'The payment method string identifying purchaser''s payment method, which must be one of: ''cc'' (credit card), ''paypal'', ''check'', ''mo'' (money order), ''bt'' (bank transfer), ''other'', ''ideal'', ''sofort'', ''apple_pay'', ''google'', ''android_pay'', ''google_pay'', ''klarna'', ''k_pay_in_4'' (klarna), ''k_pay_in_3'' (klarna), or ''k_financing'' (klarna).'
example: example string
payment_email:
type: string
description: The email address string for the email address to which to send payment confirmation
nullable: true
example: seller@example.com
message_from_seller:
type: string
description: An optional message string from the seller.
nullable: true
example: Thanks for your order! Shipping out tomorrow.
message_from_buyer:
type: string
description: An optional message string from the buyer.
nullable: true
example: Thanks for your order! Shipping out tomorrow.
message_from_payment:
type: string
description: The machine-generated acknowledgement string from the payment system.
nullable: true
example: Thanks for your order! Shipping out tomorrow.
is_paid:
type: boolean
description: When true, buyer paid for this purchase.
example: true
is_shipped:
type: boolean
description: When true, seller shipped the products.
example: true
create_timestamp:
type: integer
description: The receipt's creation time, in epoch seconds.
minimum: 946684800
example: 1758153645
created_timestamp:
type: integer
description: The receipt's creation time, in epoch seconds.
minimum: 946684800
example: 1758153645
update_timestamp:
type: integer
description: The time of the last update to the receipt, in epoch seconds.
minimum: 946684800
example: 1758153645
updated_timestamp:
type: integer
description: The time of the last update to the receipt, in epoch seconds.
minimum: 946684800
example: 1758153645
is_gift:
type: boolean
description: When true, the buyer indicated this purchase is a gift.
example: true
gift_message:
type: string
description: A gift message string the buyer requests delivered with the product.
example: Thanks for your order! Shipping out tomorrow.
gift_sender:
type: string
description: The name of the person who sent the gift.
example: example string
grandtotal:
description: A number equal to the total_price minus the coupon discount plus tax and shipping costs.
oneOf:
- $ref: '#/components/schemas/Money'
example: example
subtotal:
description: A number equal to the total_price minus coupon discounts. Does not include tax or shipping costs.
oneOf:
- $ref: '#/components/schemas/Money'
example: example
total_price:
description: A number equal to the sum of the individual listings' (price * quantity). Does not include tax or shipping costs.
oneOf:
- $ref: '#/components/schemas/Money'
example: example
total_shipping_cost:
description: A number equal to the total shipping cost of the receipt.
oneOf:
- $ref: '#/components/schemas/Money'
example: example
total_tax_cost:
description: The total sales tax of the receipt.
oneOf:
- $ref: '#/components/schemas/Money'
example: example
total_vat_cost:
description: A number equal to the total value-added tax (VAT) of the receipt.
oneOf:
- $ref: '#/components/schemas/Money'
example: example
discount_amt:
description: The numeric total discounted price for the receipt when using a discount (percent or fixed) coupon. Free shipping coupons are not included in this discount amount.
oneOf:
- $ref: '#/components/schemas/Money'
example: example
gift_wrap_price:
description: The numeric price of gift wrap for this receipt.
oneOf:
- $ref: '#/components/schemas/Money'
example: example
shipments:
type: array
description: A list of shipment statements for this receipt.
items:
description: A list of shipment statements for this receipt.
oneOf:
- $ref: '#/components/schemas/ShopReceiptShipment'
transactions:
type: array
description: Array of transactions for the receipt.
items:
description: Array of transactions for the receipt.
oneOf:
- $ref: '#/components/schemas/ShopReceiptTransaction'
refunds:
type: array
description: Refunds for a given receipt.
items:
description: Refunds for a given receipt.
oneOf:
- $ref: '#/components/schemas/ShopRefund'
ShopReceiptTransaction:
type: object
x-resource-id: ShopReceiptTransaction
description: A transaction object associated with a shop receipt. Etsy generates one transaction per listing purchased as recorded on the order receipt.
properties:
transaction_id:
type: integer
description: The unique numeric ID for a transaction.
format: int64
minimum: 1
example: 345678901
title:
type: string
description: The title string of the [listing](/documentation/reference#tag/ShopListing) purchased in this transaction.
nullable: true
example: Handmade Ceramic Mug — Stoneware
description:
type: string
description: The description string of the [listing](/documentation/reference#tag/ShopListing) purchased in this transaction.
nullable: true
example: Beautifully crafted handmade ceramic mug, kiln-fired in our Brooklyn studio.
seller_user_id:
type: integer
description: The numeric user ID for the seller in this transaction.
format: int64
minimum: 1
example: 456789
buyer_user_id:
type: integer
description: The numeric user ID for the buyer in this transaction.
format: int64
minimum: 1
example: 456789
create_timestamp:
type: integer
description: The transaction's creation date and time, in epoch seconds.
minimum: 946684800
example: 1758153645
created_timestamp:
type: integer
description: The transaction's creation date and time, in epoch seconds.
minimum: 946684800
example: 1758153645
paid_timestamp:
type: integer
description: The transaction's paid date and time, in epoch seconds.
nullable: true
minimum: 946684800
example: 1758153645
shipped_timestamp:
type: integer
description: The transaction's shipping date and time, in epoch seconds.
nullable: true
minimum: 946684800
example: 1758153645
quantity:
type: integer
description: The numeric quantity of products purchased in this transaction.
minimum: 0
example: 1
listing_image_id:
type: integer
description: The numeric ID of the primary [listing image](/documentation/reference#tag/ShopListing-Image) for this transaction.
format: int64
nullable: true
minimum: 1
example: 1
receipt_id:
type: integer
description: The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.
format: int64
minimum: 1
example: 234567890
is_digital:
type: boolean
description: When true, the transaction recorded the purchase of a digital listing.
example: true
file_data:
type: string
description: A string describing the files purchased in this transaction.
example: example string
listing_id:
type: integer
description: The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.
nullable: true
minimum: 0
example: 123456789
transaction_type:
type: string
description: The type string for the transaction, usually "listing".
example: example string
product_id:
type: integer
description: The numeric ID for a specific [product](/documentation/reference#tag/ShopListing-Product) purchased from a listing.
format: int64
nullable: true
minimum: 1
example: 567890123
sku:
type: string
description: The SKU string for the product
nullable: true
example: SKU-12345
price:
description: A money object representing the price recorded the transaction.
oneOf:
- $ref: '#/components/schemas/Money'
example: example
shipping_cost:
description: A money object representing the shipping cost for this transaction.
oneOf:
- $ref: '#/components/schemas/Money'
example: example
variations:
type: array
description: Array of variations and personalizations the buyer chose.
items:
description: Array of variations and personalizations the buyer chose.
oneOf:
- $ref: '#/components/schemas/TransactionVariations'
product_data:
type: array
description: 'A list of property value entries for this product. Note: parenthesis characters (`(` and `)`) are not allowed.'
items:
description: 'A list of property value entries for this product. Note: parenthesis characters (`(` and `)`) are not allowed.'
oneOf:
- $ref: '#/components/schemas/ListingPropertyValue'
shipping_profile_id:
type: integer
description: The ID of the shipping profile selected for this listing.
format: int64
nullable: true
minimum: 1
example: 1
min_processing_days:
type: integer
description: The minimum number of days for processing the listing.
nullable: true
minimum: 0
example: 1
max_processing_days:
type: integer
description: The maximum number of days for processing the listing.
nullable: true
minimum: 0
example: 1
shipping_method:
type: string
description: Name of the selected shipping method.
nullable: true
example: example string
shipping_upgrade:
type: string
description: The name of the shipping upgrade selected for this listing. Default value is null.
nullable: true
example: example string
expected_ship_date:
type: integer
description: The date & time of the expected ship date, in epoch seconds.
nullable: true
minimum: 946684800
example: 1
buyer_coupon:
type: number
description: The amount of the buyer coupon that was discounted in the shop's currency.
format: float
default: 0
example: 1.0
shop_coupon:
type: number
description: The amount of the shop coupon that was discounted in the shop's currency.
format: float
default: 0
example: 1.0
ListingPropertyValue:
type: object
x-resource-id: ListingPropertyValue
description: A representation of structured data values.
properties:
property_id:
type: integer
description: The numeric ID of the Property.
format: int64
minimum: 1
example: 1
property_name:
type: string
description: The name of the Property.
nullable: true
example: Handmade Ceramic Mug
scale_id:
type: integer
description: The numeric ID of the scale (if any).
format: int64
nullable: true
minimum: 1
example: 1
scale_name:
type: string
description: The label used to describe the chosen scale (if any).
nullable: true
example: Handmade Ceramic Mug
value_ids:
type: array
description: The numeric IDs of the Property values
items:
type: integer
format: int64
minimum: 1
values:
type: array
description: The Property values
items:
type: string
ShopRefund:
type: object
x-resource-id: ShopRefund
description: The refund record for a receipt.
properties:
amount:
description: A number equal to the refund total.
oneOf:
- $ref: '#/components/schemas/Money'
example: example
created_timestamp:
type: integer
description: The date & time of the refund, in epoch seconds.
minimum: 946684800
example: 1758153645
reason:
type: string
description: The reason string given for the refund.
nullable: true
example: example string
note_from_issuer:
type: string
description: The note string created by the refund issuer.
nullable: true
example: Thanks for your order! Shipping out tomorrow.
status:
type: string
description: The status indication string for the refund.
nullable: true
example: example string
Money:
type: object
x-resource-id: Money
description: A representation of an amount of money.
properties:
amount:
type: integer
description: The amount of represented by this data.
example: 2500
divisor:
type: integer
description: The divisor to render the amount.
minimum: 0
example: 1
currency_code:
type: string
description: The ISO currency code for this data.
example: USD
ShopReceipts:
type: object
x-resource-id: ShopReceipts
description: The receipts for a specific Shop.
properties:
count:
type: integer
description: The number of Shop Receipts found.
example: 1
results:
type: array
description: List of Shop Receipt resources found, with all Shop Receipt fields for each resource.
items:
description: List of Shop Receipt resources found, with all Shop Receipt fields for each resource.
oneOf:
- $ref: '#/components/schemas/ShopReceipt'
ShopReceiptShipment:
type: object
x-resource-id: ShopReceiptShipment
description: The record of one shipment event for a ShopReceipt. A receipt may have many ShopReceiptShipment records.
properties:
receipt_shipping_id:
type: integer
description: The unique numeric ID of a Shop Receipt Shipment record.
format: int64
nullable: true
minimum: 1
example: 1
shipment_notification_timestamp:
type: integer
description: The time at which Etsy notified the buyer of the shipment event, in epoch seconds.
minimum: 946684800
example: 1758153645
carrier_name:
type: string
description: The name string for the carrier/company responsible for delivering the shipment.
example: usps
tracking_code:
type: string
description: The tracking code string provided by the carrier/company for the shipment.
example: 1Z999AA10123456784
TransactionVariations:
type: object
x-resource-id: TransactionVariations
description: A list of variations chosen by the buyer during checkout.
properties:
property_id:
type: integer
description: The variation property ID.
example: 1
value_id:
type: integer
description: The ID of the variation value selected.
nullable: true
example: 1
formatted_name:
type: string
description: Formatted name of the variation.
example: Handmade Ceramic Mug
formatted_value:
type: string
description: Value of the variation entered by the buyer.
example: example string
question_id:
type: integer
description: '[Personalization only] The ID of the original personalization question.'
nullable: true
example: 1
securitySchemes:
api_key:
type: apiKey
name: x-api-key
in: header
description: Every request to a v3 API endpoint must include this data in the format `keystring:shared_secret`. Your keystring and shared secret are available on the [Your Apps](https://www.etsy.com/developers/your-apps) page.
oauth2:
type: oauth2
description: Open API v3 supports authenticating via OAuth 2.0. More information about Etsy's specific implementation of OAuth2 can be found [here](/documentation/essentials/oauth2).
flows:
authorizationCode:
authorizationUrl: https://www.etsy.com/oauth/connect
tokenUrl: https://openapi.etsy.com/v3/public/oauth/token
scopes:
address_r: see billing and shipping addresses
address_w: update billing and shipping addresses
billing_r: see all billing statement data
cart_r: read shopping carts
cart_w: add/remove from shopping carts
email_r: read a user profile
favorites_r: see private favorites
favorites_w: add/remove favorites
feedback_r: see purchase info in feedback
listings_d: delete listings
listings_r: see all listings (including expired etc)
listings_w: create/edit listings
profile_r: see all profile data
profile_w: update user profile, avatar, etc
recommend_r: see recommended listings
recommend_w: accept/reject recommended listings
shops_r: see private shop info
shops_w: update shop
transactions_r: see all checkout/payment data
transactions_w: update receipts
x-tagGroups:
- name: Listing Management
tags:
- BuyerTaxonomy
- SellerTaxonomy
- ShopListing
- ShopListing File
- ShopListing Image
- ShopListing Inventory
- ShopListing Offering
- ShopListing Personalization
- ShopListing Product
- ShopListing Translation
- ShopListing VariationImage
- ShopListing Video
- name: Other
tags:
- Other
- name: Payment Management
tags:
- Ledger Entry
- Payment
- name: Receipt Management
tags:
- Shop Receipt
- Shop Receipt Transactions
- name: Review Management
tags:
- Review
- name: Shipping Management
tags:
- Shop HolidayPreferences
- Shop ProcessingProfiles
- Shop ShippingProfile
- name: Shop Management
tags:
- Shop
- Shop ProductionPartner
- Shop Section
- name: Shop Policy Management
tags:
- Shop Return Policy
- name: User Management
tags:
- User
- UserAddress