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

Receipt

Overview

Represents proof of payment from a user to a shop for one or more transactions.

Fields

Field Visibility Level Permission Scope Type Description
receipt_id private transactions_r int The receipt's numeric ID.
receipt_type private transactions_r int The enum of the order type this receipt is associated with.
order_id private transactions_r int The numeric ID of the order this receipt is associated with.
seller_user_id private transactions_r int The numeric ID of the seller for this receipt.
buyer_user_id private transactions_r int The numeric ID of the buyer for this receipt.
creation_tsz private transactions_r float Creation time, in epoch seconds.
can_refund private transactions_r boolean Whether or not a refund is allowed for this Receipt.
last_modified_tsz private transactions_r float Last modification time, in epoch seconds.
name private transactions_r string The name portion of the buyer's address.
first_line private transactions_r string The first line of the buyer's address.
second_line private transactions_r string The second line of the buyer's address.
city private transactions_r string The city for the buyer's address.
state private transactions_r string The state for the buyer's address.
zip private transactions_r string The zip code of the buyer's address.
formatted_address private transactions_r string The locally formatted address strng of the buyer's shipping address.
country_id private transactions_r int The numeric ID of the buyer's country.
payment_method private transactions_r string The payment method used. May be pp, cc, ck, mo, or other (stands for paypal, credit card, check, money order, other).
payment_email private transactions_r string The email address where payment confirmation is sent.
message_from_seller private transactions_r string An optional message from the seller.
message_from_buyer private transactions_r string An optional message from the buyer.
was_paid private transactions_r boolean True if the receipt was paid.
total_tax_cost private transactions_r float The total sales tax of the receipt.
total_vat_cost private transactions_r float The total VAT of the receipt.
total_price private transactions_r float Sum of the individual listings' (price * quantity). Does not included tax or shipping costs.
total_shipping_cost private transactions_r float The total shipping cost of the receipt.
currency_code private transactions_r string The ISO code (alphabetic) for the seller's native currency.
message_from_payment private transactions_r string The machine generated acknowledgement from the payment system.
was_shipped private transactions_r boolean True if the items in the receipt were shipped.
buyer_email private transactions_r string The email address of the buyer. Access to this field is granted on a case by case basis for third-party integrations that require full access. Sellers using private apps to manage their shops can still access this field.
seller_email private transactions_r string The email address of the seller.
is_gift private transactions_r boolean Whether the buyer marked item as a gift.
needs_gift_wrap private transactions_r boolean Whether the buyer purchased gift wrap.
gift_message private transactions_r string The message the buyer wants sent with the gift.
gift_wrap_price private transactions_r float The gift wrap price of the receipt.
discount_amt private transactions_r float The total discount for the receipt, if using a discount (percent or fixed) Coupon. Free shipping Coupons are not reflected here.
etsy_coupon_discount_amt private transactions_r float The total discount for the receipt, if using an Etsy-funded coupon.
subtotal private transactions_r float total_price minus coupon discounts. Does not included tax or shipping costs.
grandtotal private transactions_r float total_price minus coupon discount plus tax and shipping costs.
adjusted_grandtotal private transactions_r float grand total after payment adjustments.
buyer_adjusted_grandtotal private transactions_r float grand total after payment adjustments from the buyer's perspective
shipments private transactions_r array(ReceiptShipment) Shipment information associated to this receipt.

Associations

Association Visibility Level Permission Scope Type Description
Country private transactions_r Country The country to which the order was shipped.
Buyer private transactions_r User The buyer of the items in this receipt.
GuestBuyer private transactions_r GuestUser The guest buyer of the items in this receipt.
Seller private transactions_r User The seller of the items in this receipt.
Transactions private transactions_r array(Transaction) The transactions associated to this receipt. You will find the personalization details for an order within the 'variations' arrays returned for this association.
Listings private transactions_r array(Listing) The listings associated to this receipt. Please note that this association will return the current listing details, not the details at the time of purchase.

Methods

getShop_Receipt2

Method Name getShop_Receipt2
Synopsis Retrieves a Shop_Receipt2 by id.
HTTP Method GET
URI /receipts/:receipt_id
Parameters
Name Required Default Type
receipt_id Y   array(int)
Requires OAuth Y
Permission Scope transactions_r

updateReceipt

Method Name updateReceipt
Synopsis Updates a Shop_Receipt2
HTTP Method PUT
URI /receipts/:receipt_id
Parameters
Name Required Default Type
receipt_id Y   int
was_paid N   boolean
was_shipped N   boolean
Requires OAuth Y
Permission Scope transactions_w

findAllShopReceipts

Method Name findAllShopReceipts
Synopsis Retrieves a set of Receipt objects associated to a Shop.
HTTP Method GET
URI /shops/:shop_id/receipts
Parameters
Name Required Default Type
shop_id Y   shop_id_or_name
min_created N   epoch
max_created N   epoch
min_last_modified N   epoch
max_last_modified N   epoch
limit N 25 int
offset N 0 int
page N   int
was_paid N   boolean
was_shipped N   boolean
Requires OAuth Y
Permission Scope transactions_r
Notes
Please note that cancelled orders will only be surfaced when making direct requests to the receipt_id.

submitTracking

Method Name submitTracking
Synopsis Submits tracking information and sends a shipping notification email to the buyer. If send_bcc is true, the shipping notification will be sent to the seller as well. Refer to additional documentation.
HTTP Method POST
URI /shops/:shop_id/receipts/:receipt_id/tracking
Parameters
Name Required Default Type
tracking_code Y   string
carrier_name Y   string
send_bcc N boolean
Requires OAuth Y
Permission Scope transactions_w

findAllShopReceiptsByStatus

Method Name findAllShopReceiptsByStatus
Synopsis Retrieves a set of Receipt objects associated to a Shop based on the status.
HTTP Method GET
URI /shops/:shop_id/receipts/:status
Parameters
Name Required Default Type
shop_id Y   shop_id_or_name
status Y   enum(open, unshipped, unpaid, completed, processing, all)
limit N 25 int
offset N 0 int
page N   int
Requires OAuth Y
Permission Scope transactions_r

searchAllShopReceipts

Method Name searchAllShopReceipts
Synopsis Searches the set of Receipt objects associated to a Shop by a query
HTTP Method GET
URI /shops/:shop_id/receipts/search
Parameters
Name Required Default Type
shop_id Y   shop_id_or_name
search_query Y   string
limit N 25 int
offset N 0 int
page N   int
Requires OAuth Y
Permission Scope transactions_r

findAllUserBuyerReceipts

Method Name findAllUserBuyerReceipts
Synopsis Retrieves a set of Receipt objects associated to a User.
HTTP Method GET
URI /users/:user_id/receipts
Parameters
Name Required Default Type
user_id Y   user_id_or_name
limit N 25 int
offset N 0 int
page N   int
Requires OAuth Y
Permission Scope transactions_r

Open API v3New

Your developer account