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

ShippingInfo

Overview

Shipping fees for a listing and a specific destination.

ShippingTemplate, ShippingTemplateEntry, and ShippingInfo

The diagram below is an ERD of the relevant portion of the database related to Listings. Each Listing has a User, and each User can have 0 or more ShippingTemplates. We are enforcing that a user create at least one ShippingTemplate before creating a listing. When that listing is created, the ShippingTemplate gets copied into the ShippingInfo table and is associated to that listing. You can then edit the ShippingInfo directly for a listing, or update your ShippingTemplate and update the listing with it.

  • A ShippingTemplate has a title and is owned by a user.
  • ShippingInfo is a set of records that define shipping information for a specific listing. They are created from a ShippingTemplate.
  • ShippingTemplateEntries are a set of rows that correspond to this template.
    • They hold an origin country, and a destination, as well as the primary and secondary cost.
    • There is only one origin per template, so this is changed on the ShippingTemplate resource instead of the ShippingTemplateEntry.
  • You can pass a destination id or a region id when creating a ShippingTemplateEntry, but not both—if you leave them both blank then the destination is assumed to be "everywhere".
  • If you create a ShippingTemplateEntry with a region, this implies several destinations and will insert a row for each destination within that region.
  • If you delete a ShippingTemplateEntry that is a region, it will delete all corresponding destinations for that region.
  • You can update a ShippingTemplateEntry, but because a region defines many rows, and different regions may have a different number of rows, you cannot update the region. You must first delete an entry corresponding to that region, and then add an entry with the new region.

Fields

Field Visibility Level Permission Scope Type Description
shipping_info_id public none int The numeric ID of this shipping info record.
origin_country_id public none int The numeric ID of the country from which the listing ships.
destination_country_id public none int The numeric ID of the country to which the listing ships (optional). If missing, these fees apply to all destinations.
currency_code public none string Identifies the currency unit for shipping fees (currently, always 'USD').
primary_cost public none float The shipping fee for this item, if shipped alone.
secondary_cost public none float The shipping fee for this item, if shipped with another item.
listing_id public none int The numeric ID of the listing to which this shipping info applies.
region_id public none int The numeric ID of the region to which this shipping info applies (optional). If missing, no region is selected. Regions are shorthand for lists of individual countries.
shipping_carrier_id public none int The numeric ID of the shipping carrier.
mail_class private none string The string representation of a shipping carrier's mail class.
min_delivery_time private none int The minimum delivery time that a shipment will take, in days.
max_delivery_time private none int The maximum delivery time that a shipment will take, in days.
origin_country_name public none string The name of the country from which this item ships.
destination_country_name public none string The name of the country to which this item ships.

Associations

Association Visibility Level Permission Scope Type Description
DestinationCountry public none Country The full Country record for the shipping destination.
OriginCountry public none Country The full Country record for the shipping origin.
Region public none Region The full Region record for the shipping destination region.

Methods

findAllListingShippingProfileEntries

Method Name findAllListingShippingProfileEntries
Synopsis Retrieves a set of ShippingProfileEntries objects associated to a Listing.
HTTP Method GET
URI /listings/:listing_id/shipping/info
Parameters none
Requires OAuth N
Permission Scope none

Open API v3New

Your developer account