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

GuestCart

Overview

Represents a guest shopping cart on Etsy. Users have one cart per shop.

This is a cart that is not yet associated to a single user, but to a guest ID for tracking purposes. Some important things to note about Guest Carts:

  • Each GuestID generated is associated only with the application that generated it. You may not access a guest's carts from multiple different applications.
  • Although Guest Carts do not require an authenticated user, they do require your app to have production access in order to be interacted with.
  • Guest Carts expire after 30 days of inactivity. Do not rely on a guest cart existing permanently, as they will be emptied and reset after those 30 days.

Fields

Field Visibility Level Permission Scope Type Description
cart_id public none int The numeric ID of the cart
shop_name public none string The shop name
message_to_seller public none string The message to the seller
destination_country_id public none int The numeric ID of the destination country
coupon_code public none string The alphanumeric coupon code applied to the cart
Deprecated: The Etsy API no longer supports coupons.
currency_code public none string The ISO (alphabetic) code for the currency
total public none string The total price
subtotal public none string The subtotal price
shipping_cost public none string The shipping cost
tax_cost public none string The tax cost
discount_amount public none string The line-item discount amount (does not include tax or shipping)
shipping_discount_amount public none string The shipping discount amount
tax_discount_amount public none string The tax discount amount
url public none string The full URL to the cart page on Etsy
listings public none array(CartListing) An array of purchase information for the listings
is_download_only public none boolean The cart is download only
has_vat public none boolean The cart has VAT tax
shipping_option public none ShippingOption The selected shipping option identifier for the cart

Associations

Association Visibility Level Permission Scope Type Description
Shop public none Shop The shop
Listings public none array(Listing) An array of listings
ShippingOptions public none array(ShippingOption) Available shipping options for the cart

Methods

findAllGuestCarts

Method Name findAllGuestCarts
Synopsis Get all guest's carts
HTTP Method GET
URI /guests/:guest_id/carts
Parameters
Name Required Default Type
guest_id Y   guest_id
Requires OAuth N
Permission Scope none

addToGuestCart

Method Name addToGuestCart
Synopsis Add a listing to guest's cart
HTTP Method POST
URI /guests/:guest_id/carts
Parameters
Name Required Default Type
guest_id Y   guest_id
listing_id Y   int
quantity N 1 int
selected_variations N   map(int, int)
personalization N   personalization
Requires OAuth N
Permission Scope none

updateGuestCartListingQuantity

Method Name updateGuestCartListingQuantity
Synopsis Update a guest's cart listing purchase quantity
HTTP Method PUT
URI /guests/:guest_id/carts
Parameters
Name Required Default Type
guest_id Y   guest_id
listing_id Y   int
quantity Y   int
listing_customization_id N 0 int
Requires OAuth N
Permission Scope none

removeGuestCartListing

Method Name removeGuestCartListing
Synopsis Remove a listing from a guest's cart
HTTP Method DELETE
URI /guests/:guest_id/carts
Parameters
Name Required Default Type
guest_id Y   guest_id
listing_id Y   int
listing_customization_id N 0 int
Requires OAuth N
Permission Scope none

findGuestCart

Method Name findGuestCart
Synopsis Get a guest's cart
HTTP Method GET
URI /guests/:guest_id/carts/:cart_id
Parameters
Name Required Default Type
guest_id Y   guest_id
cart_id Y   cart_id
Requires OAuth N
Permission Scope none

updateGuestCart

Method Name updateGuestCart
Synopsis Update a guest's cart
HTTP Method PUT
URI /guests/:guest_id/carts/:cart_id
Parameters
Name Required Default Type
guest_id Y   guest_id
cart_id Y   cart_id
destination_country_id N   int
message_to_seller N   string
coupon_code N   string
shipping_option_id N   string
destination_zip N   string
Requires OAuth N
Permission Scope none

deleteGuestCart

Method Name deleteGuestCart
Synopsis Delete a guest's cart
HTTP Method DELETE
URI /guests/:guest_id/carts/:cart_id
Parameters
Name Required Default Type
guest_id Y   guest_id
cart_id Y   cart_id
Requires OAuth N
Permission Scope none

Open API v3New

Your developer account