Etsy Shop Receipt Transactions API

openapi: 3.0.2
info:
  title: Etsy Open API v3 BuyerTaxonomy Shop Receipt Transactions 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>&copy; 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 Transactions
paths:
  /v3/application/shops/{shop_id}/listings/{listing_id}/transactions:
    get:
      operationId: getShopReceiptTransactionsByListing
      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 the list of transactions associated with a listing.'
      tags:
      - Shop Receipt Transactions
      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: listing_id
        in: path
        description: The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.
        required: true
        schema:
          type: integer
          description: The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.
          format: int64
          minimum: 1
        example: 123456789
      - 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: 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 transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopReceiptTransactions'
              examples:
                GetShopReceiptTransactionsByListing200Example:
                  summary: Default getShopReceiptTransactionsByListing 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:
                GetShopReceiptTransactionsByListing403Example:
                  summary: Default getShopReceiptTransactionsByListing 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:
                GetShopReceiptTransactionsByListing404Example:
                  summary: Default getShopReceiptTransactionsByListing 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:
                GetShopReceiptTransactionsByListing400Example:
                  summary: Default getShopReceiptTransactionsByListing 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:
                GetShopReceiptTransactionsByListing401Example:
                  summary: Default getShopReceiptTransactionsByListing 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:
                GetShopReceiptTransactionsByListing500Example:
                  summary: Default getShopReceiptTransactionsByListing 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 Transactions by Listing
  /v3/application/shops/{shop_id}/receipts/{receipt_id}/transactions:
    get:
      operationId: getShopReceiptTransactionsByReceipt
      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 the list of transactions associated with a specific receipt.'
      tags:
      - Shop Receipt Transactions
      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 list of transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopReceiptTransactions'
              examples:
                GetShopReceiptTransactionsByReceipt200Example:
                  summary: Default getShopReceiptTransactionsByReceipt 200 response
                  x-microcks-default: true
                  value:
                    count: 1
                    results:
                    - null
        '404':
          description: A resource could not be found. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShopReceiptTransactionsByReceipt404Example:
                  summary: Default getShopReceiptTransactionsByReceipt 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:
                GetShopReceiptTransactionsByReceipt403Example:
                  summary: Default getShopReceiptTransactionsByReceipt 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:
                GetShopReceiptTransactionsByReceipt400Example:
                  summary: Default getShopReceiptTransactionsByReceipt 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:
                GetShopReceiptTransactionsByReceipt401Example:
                  summary: Default getShopReceiptTransactionsByReceipt 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:
                GetShopReceiptTransactionsByReceipt500Example:
                  summary: Default getShopReceiptTransactionsByReceipt 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 Transactions by Receipt
  /v3/application/shops/{shop_id}/transactions/{transaction_id}:
    get:
      operationId: getShopReceiptTransaction
      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 transaction by transaction ID.'
      tags:
      - Shop Receipt Transactions
      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: transaction_id
        in: path
        description: The unique numeric ID for a transaction.
        required: true
        schema:
          type: integer
          description: The unique numeric ID for a transaction.
          format: int64
          minimum: 1
        example: 345678901
      responses:
        '200':
          description: A single transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopReceiptTransaction'
              examples:
                GetShopReceiptTransaction200Example:
                  summary: Default getShopReceiptTransaction 200 response
                  x-microcks-default: true
                  value:
                    transaction_id: 345678901
                    title: Handmade Ceramic Mug — Stoneware
                    description: Beautifully crafted handmade ceramic mug, kiln-fired in our Brooklyn studio.
                    seller_user_id: 456789
                    buyer_user_id: 456789
                    create_timestamp: 1758153645
                    created_timestamp: 1758153645
                    paid_timestamp: 1758153645
                    shipped_timestamp: 1758153645
                    quantity: 1
                    listing_image_id: 1
                    receipt_id: 234567890
                    is_digital: true
                    file_data: example string
                    listing_id: 123456789
                    transaction_type: example string
                    product_id: 567890123
                    sku: SKU-12345
                    price: example
                    shipping_cost: example
                    variations:
                    - null
                    product_data:
                    - null
                    shipping_profile_id: 1
                    min_processing_days: 1
                    max_processing_days: 1
                    shipping_method: example string
                    shipping_upgrade: example string
                    expected_ship_date: 1
                    buyer_coupon: 1.0
                    shop_coupon: 1.0
        '404':
          description: A resource could not be found. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShopReceiptTransaction404Example:
                  summary: Default getShopReceiptTransaction 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:
                GetShopReceiptTransaction403Example:
                  summary: Default getShopReceiptTransaction 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:
                GetShopReceiptTransaction400Example:
                  summary: Default getShopReceiptTransaction 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:
                GetShopReceiptTransaction401Example:
                  summary: Default getShopReceiptTransaction 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:
                GetShopReceiptTransaction500Example:
                  summary: Default getShopReceiptTransaction 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 Transaction
  /v3/application/shops/{shop_id}/transactions:
    get:
      operationId: getShopReceiptTransactionsByShop
      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 the list of transactions associated with a shop.'
      tags:
      - Shop Receipt Transactions
      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: 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: 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 transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopReceiptTransactions'
              examples:
                GetShopReceiptTransactionsByShop200Example:
                  summary: Default getShopReceiptTransactionsByShop 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:
                GetShopReceiptTransactionsByShop403Example:
                  summary: Default getShopReceiptTransactionsByShop 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:
                GetShopReceiptTransactionsByShop404Example:
                  summary: Default getShopReceiptTransactionsByShop 404 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:
                GetShopReceiptTransactionsByShop401Example:
                  summary: Default getShopReceiptTransactionsByShop 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:
                GetShopReceiptTransactionsByShop500Example:
                  summary: Default getShopReceiptTransactionsByShop 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 Transactions by Shop
components:
  schemas:
    ErrorSchema:
      type: object
      x-resource-id: ErrorSchema
      required:
      - error
      properties:
        error:
          type: string
          example: example string
    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
    ShopReceiptTransactions:
      type: object
      x-resource-id: ShopReceiptTransactions
      description: A set of ShopReceiptTransaction resources
      properties:
        count:
          type: integer
          description: The number of ShopReceiptTransaction resources found.
          example: 1
        results:
          type: array
          description: The ShopReceiptTransaction resources found.
          items:
            description: The ShopReceiptTransaction resources found.
            oneOf:
            - $ref: '#/components/schemas/ShopReceiptTransaction'
    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
    TransactionVariations:
      type: object
      x-re

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/etsy/refs/heads/main/openapi/etsy-shop-receipt-transactions-api-openapi.yml