Etsy · Schema

ShopReceipt

The record of a purchase from a shop. Shop receipts display monetary values using the shop's currency.

MarketplaceEcommerceHandmadeListingsOrdersPaymentsReviewsShippingTaxonomyOAuth2

Properties

Name Type Description
receipt_id integer The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.
receipt_type integer The numeric value for the Etsy channel that serviced the purchase: 0 or 5 for Etsy.com, 1 for a Pattern shop.
seller_user_id integer The numeric ID for the [user](/documentation/reference#tag/User) (seller) fulfilling the purchase.
seller_email string The email address string for the seller of the listing.
buyer_user_id integer The numeric ID for the [user](/documentation/reference#tag/User) making the purchase.
buyer_email string 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.
name string The name string for the recipient in the shipping address.
first_line string The first address line string for the recipient in the shipping address.
second_line string The optional second address line string for the recipient in the shipping address.
city string The city string for the recipient in the shipping address.
state string The state string for the recipient in the shipping address.
zip string The zip code string (not necessarily a number) for the recipient in the shipping address.
status string The current order status string. One of: `paid`, `completed`, `open`, `payment processing` or `canceled`.
formatted_address string The formatted shipping address string for the recipient in the shipping address.
country_iso string The ISO-3166 alpha-2 country code string for the recipient in the shipping address.
payment_method string 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', 'ap
payment_email string The email address string for the email address to which to send payment confirmation
message_from_seller string An optional message string from the seller.
message_from_buyer string An optional message string from the buyer.
message_from_payment string The machine-generated acknowledgement string from the payment system.
is_paid boolean When true, buyer paid for this purchase.
is_shipped boolean When true, seller shipped the products.
create_timestamp integer The receipt's creation time, in epoch seconds.
created_timestamp integer The receipt's creation time, in epoch seconds.
update_timestamp integer The time of the last update to the receipt, in epoch seconds.
updated_timestamp integer The time of the last update to the receipt, in epoch seconds.
is_gift boolean When true, the buyer indicated this purchase is a gift.
gift_message string A gift message string the buyer requests delivered with the product.
gift_sender string The name of the person who sent the gift.
grandtotal object A number equal to the total_price minus the coupon discount plus tax and shipping costs.
subtotal object A number equal to the total_price minus coupon discounts. Does not include tax or shipping costs.
total_price object A number equal to the sum of the individual listings' (price * quantity). Does not include tax or shipping costs.
total_shipping_cost object A number equal to the total shipping cost of the receipt.
total_tax_cost object The total sales tax of the receipt.
total_vat_cost object A number equal to the total value-added tax (VAT) of the receipt.
discount_amt object 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.
gift_wrap_price object The numeric price of gift wrap for this receipt.
shipments array A list of shipment statements for this receipt.
transactions array Array of transactions for the receipt.
refunds array Refunds for a given receipt.
View JSON Schema on GitHub

JSON Schema

open-api-v3-shop-receipt-schema.json Raw ↑ 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ShopReceipt",
  "description": "The record of a purchase from a shop. Shop receipts display monetary values using the shop's currency.",
  "$id": "https://raw.githubusercontent.com/api-evangelist/etsy/refs/heads/main/json-schema/open-api-v3-shop-receipt-schema.json",
  "type": "object",
  "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": "[email protected]"
    },
    "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": "[email protected]"
    },
    "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": "[email protected]"
    },
    "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"
          }
        ]
      }
    }
  }
}