AddItem

Use this call to create and publish a new listing on an eBay site. Upon successful creation of a listing using the AddItem call, an Item ID is returned in the response along with the estimated listing fees. For information on listing fees, see Fees. Note that the fees returned from AddItem do not include any transaction fees; these fees cannot be calculated until the item is sold.

You must use one AddItem call to create and publish each listing. Alternatively, you can use the AddItems call to create and publish up to five listings per call. The AddItem call can be used to create a single-variation, fixed-price listing, but if you wish to create a multiple-variation, fixed-price listing (for example, the same shirt in varying sizes and colors), use the AddFixedPriceItem call instead.

Note that sellers who engage in cross-border trade on sites that require a recoupment agreement must agree to the recoupment terms before adding items to the site. This agreement allows eBay to reimburse a buyer during a dispute and then recoup the cost from the seller.

Note: Sellers may be subject to call-rate limits for Add calls. The Add calls include AddItem, AddFixedPriceItem, AddItems, VerifyAddItem, and VerifyAddFixedPriceItem.

Users who exceed these call frequency limits for Add calls will be temporarily blocked from listing, and an error message (ErrorCode 21919144) will alert them to this fact. These call frequency limits are subject to change without notice.

Usage Details

For a detailed, step-by-step description of listing an item using AddItem, see Create item listings.

In addition, AddItem has specific usages for certain cases. some special use cases are detailed here:

• For information on including pictures of the item with the item definition, see Add pictures.
• For information on eBay for Charity listing, see Charitable listings.
• For an example showing how to list items in an eBay store in a custom store category, see the AddItem Samples.

Note that AddItem returns error information if your call is missing required information. Because of this, it is best to test your item listings with VerifyAddItem before you list your items to the production site. See Testing AddItem for more details.

Note to Sell Feed API users: When you use this call with the Sell Feed API, you must wrap the file to be uploaded within BulkDataExchangeRequest tags, which will also be returned in the response. This container is not shown in the standard Input/Output sections for this call. See XML data files overview in the LMS Feed API Guide for additional information.

Working with the Response

AddItem returns data for the new item listing into the properties of the AddItem response object. Response data includes the new listing's item ID, the start and end dates for the listing, and the estimated fees for the new listing.

• Inspect the ItemID property to get the new listing's item ID.
• Inspect the StartDate property to get the new listing's starting date and time.
• Inspect the EndDate property to get the new listing's ending date and time (which will be as many days after the value in StartDate as the seller specified for the ListingDuration input).
• Inspect the child elements of the Fees property to get the estimated listing fees for the new item. However, note that Fees does not contain any transaction fees, which can not be calculated until the item is sold.

Best Practices

Do not test item insertions with AddItem. Instead, use VerifyAddItem to test an item's definition before using making it live with AddItem. Also of note, testing with VerifyAddItem can reduce the number of item listing errors your application needs to handle. Do not, however, use VerifyAddItem if you are adding items in bulk.

It is a good idea to use VerifyAddItem in your application if users are able to actively interact with the system.

A suspected error condition can occur when a user submits an AddItem request, but they do not receive a response. In this case, the user does not know whether or not the listing was successfully submitted. To prepare for this condition, submit the AddItem request with a UUID.

Items that qualify for a free re-listing should be listed with RelistItem, not AddItem. This can save the seller certain listing fees.

Testing AddItem

Because calling AddItem in the production environment incurs fees, it is best to test AddItem in the Sandbox. Ensure that the test user in the Sandbox environment has sufficient feedback and other qualifications needed to list the type of item you want to test.

In the Sandbox, use a data retrieval call like GetSellerList or GetItem to retrieve data for items just listed with AddItem. Verify that the listing has all of the desired values.

To reduce AddItem errors (and potential listing fee costs), use VerifyAddItem to test item definitions before making your listings active with AddItem calls.

For applications that list items with catalog product details, create listings by specifying an ISBN, EAN, or UPC code.

To test CategoryMappingAllowed, use GetCategoryMappings to find an old category that has been mapped to a new category. Pass the old category ID as input to AddItem and set CategoryMappingAllowed to true. See Category ID mapping and GetCategoryMappings.

Users can only add eBay for Charity listings if the seller is a registered charity seller with the PayPal Giving Fund. To test this functionality, contact Developer Support to obtains Sandbox test users who are set up as registered charity sellers.

Related Information

See:
    List an item
    Create item listings
    Add pictures

See also the reference documentation for these calls:

• AddFixedPriceItem - Defines and publishes a single or multiple-variation fixed-price listing.
• AddItems - Base request type for the AddItems call, which is used to create one to five fixed-price, auction, or classified ad listings.
• VerifyAddItem - Enables a seller to specify the definition of a new item and submit the definition to eBay without creating a listing.

Input

See also Samples.

The box below lists all fields that could be included in the call request. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are (or soon will be) non-operational.

The XML prototype does not include requester credentials. This is a documentation limitation only (see Standard Requester Credentials for Making Calls).

<?xml version="1.0" encoding="utf-8"?>
<AddItemRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Input Fields -->
  <Item> ItemType
    <ApplicationData> string </ApplicationData>
    <AutoPay> boolean </AutoPay>
    <BestOfferDetails> BestOfferDetailsType
      <BestOfferEnabled> boolean </BestOfferEnabled>
    </BestOfferDetails>
    <BuyerResponsibleForShipping> boolean </BuyerResponsibleForShipping>
    <BuyItNowPrice currencyID="CurrencyCodeType"> AmountType (double) </BuyItNowPrice>
    <CategoryMappingAllowed> boolean </CategoryMappingAllowed>
    <Charity> CharityType
      <CharityID> string </CharityID>
      <DonationPercent> float </DonationPercent>
    </Charity>
    <ConditionDescription> string </ConditionDescription>
    <ConditionDescriptors> ConditionDescriptorsType
      <ConditionDescriptor> ConditionDescriptorType
        <AdditionalInfo> string </AdditionalInfo>
        <Name> string </Name>
        <Value> string </Value>
        <!-- ... more Value values allowed here ... -->
      </ConditionDescriptor>
      <!-- ... more ConditionDescriptor nodes allowed here ... -->
    </ConditionDescriptors>
    <ConditionID> int </ConditionID>
    <Country> CountryCodeType </Country>
    <CrossBorderTrade> string </CrossBorderTrade>
    <!-- ... more CrossBorderTrade values allowed here ... -->
    <Currency> CurrencyCodeType </Currency>
    <CustomPolicies> CustomPoliciesType
      <ProductCompliancePolicyID> long </ProductCompliancePolicyID>
      <!-- ... more ProductCompliancePolicyID values allowed here ... -->
      <RegionalProductCompliancePolicies> CountryPoliciesArrayType
        <CountryPolicies> CountryPoliciesType
          <Country> CountryCodeType </Country>
          <PolicyID> long </PolicyID>
          <!-- ... more PolicyID values allowed here ... -->
        </CountryPolicies>
        <!-- ... more CountryPolicies nodes allowed here ... -->
      </RegionalProductCompliancePolicies>
      <RegionalTakeBackPolicies> CountryPoliciesArrayType
        <CountryPolicies> CountryPoliciesType
          <Country> CountryCodeType </Country>
          <PolicyID> long </PolicyID>
          <!-- ... more PolicyID values allowed here ... -->
        </CountryPolicies>
        <!-- ... more CountryPolicies nodes allowed here ... -->
      </RegionalTakeBackPolicies>
      <TakeBackPolicyID> long </TakeBackPolicyID>
    </CustomPolicies>
    <Description> string </Description>
    <DigitalGoodInfo> DigitalGoodInfoType
      <DigitalDelivery> boolean </DigitalDelivery>
    </DigitalGoodInfo>
    <DisableBuyerRequirements> boolean </DisableBuyerRequirements>
    <DiscountPriceInfo> DiscountPriceInfoType
      <MadeForOutletComparisonPrice currencyID="CurrencyCodeType"> AmountType (double) </MadeForOutletComparisonPrice>
      <MinimumAdvertisedPrice currencyID="CurrencyCodeType"> AmountType (double) </MinimumAdvertisedPrice>
      <MinimumAdvertisedPriceExposure> MinimumAdvertisedPriceExposureCodeType </MinimumAdvertisedPriceExposure>
      <OriginalRetailPrice currencyID="CurrencyCodeType"> AmountType (double) </OriginalRetailPrice>
      <SoldOffeBay> boolean </SoldOffeBay>
      <SoldOneBay> boolean </SoldOneBay>
    </DiscountPriceInfo>
    <DispatchTimeMax> int </DispatchTimeMax>
    <eBayPlus> boolean </eBayPlus>
    <ExtendedProducerResponsibility> ExtendedProducerResponsibilityType
      <EcoParticipationFee currencyID="CurrencyCodeType"> AmountType (double) </EcoParticipationFee>
    </ExtendedProducerResponsibility>
    <ExtendedSellerContactDetails> ExtendedContactDetailsType
      <ClassifiedAdContactByEmailEnabled> boolean </ClassifiedAdContactByEmailEnabled>
      <ContactHoursDetails> ContactHoursDetailsType
        <Hours1AnyTime> boolean </Hours1AnyTime>
        <Hours1Days> DaysCodeType </Hours1Days>
        <Hours1From> time </Hours1From>
        <Hours1To> time </Hours1To>
        <Hours2AnyTime> boolean </Hours2AnyTime>
        <Hours2Days> DaysCodeType </Hours2Days>
        <Hours2From> time </Hours2From>
        <Hours2To> time </Hours2To>
        <TimeZoneID> string </TimeZoneID>
      </ContactHoursDetails>
    </ExtendedSellerContactDetails>
    <ItemCompatibilityList> ItemCompatibilityListType
      <Compatibility> ItemCompatibilityType
        <CompatibilityNotes> string </CompatibilityNotes>
        <NameValueList> NameValueListType
          <Name> string </Name>
          <Value> string </Value>
          <!-- ... more Value values allowed here ... -->
        </NameValueList>
        <!-- ... more NameValueList nodes allowed here ... -->
      </Compatibility>
      <!-- ... more Compatibility nodes allowed here ... -->
    </ItemCompatibilityList>
    <ItemSpecifics> NameValueListArrayType
      <NameValueList> NameValueListType
        <Name> string </Name>
        <Value> string </Value>
        <!-- ... more Value values allowed here ... -->
      </NameValueList>
      <!-- ... more NameValueList nodes allowed here ... -->
    </ItemSpecifics>
    <ListingDetails> ListingDetailsType
      <BestOfferAutoAcceptPrice currencyID="CurrencyCodeType"> AmountType (double) </BestOfferAutoAcceptPrice>
      <LocalListingDistance> string </LocalListingDistance>
      <MinimumBestOfferPrice currencyID="CurrencyCodeType"> AmountType (double) </MinimumBestOfferPrice>
    </ListingDetails>
    <ListingDuration> token </ListingDuration>
    <ListingEnhancement> ListingEnhancementsCodeType </ListingEnhancement>
    <!-- ... more ListingEnhancement values allowed here ... -->
    <ListingSubtype2> ListingSubtypeCodeType </ListingSubtype2>
    <ListingType> ListingTypeCodeType </ListingType>
    <Location> string </Location>
    <LotSize> int </LotSize>
    <PaymentDetails> PaymentDetailsType
      <DaysToFullPayment> int </DaysToFullPayment>
      <DepositAmount currencyID="CurrencyCodeType"> AmountType (double) </DepositAmount>
      <DepositType> DepositTypeCodeType </DepositType>
      <HoursToDeposit> int </HoursToDeposit>
    </PaymentDetails>
    <PaymentMethods> BuyerPaymentMethodCodeType </PaymentMethods>
    <!-- ... more PaymentMethods values allowed here ... -->
    <PayPalEmailAddress> string </PayPalEmailAddress>
    <PickupInStoreDetails> PickupInStoreDetailsType
      <EligibleForPickupInStore> boolean </EligibleForPickupInStore>
    </PickupInStoreDetails>
    <PictureDetails> PictureDetailsType
      <GalleryType> GalleryTypeCodeType </GalleryType>
      <PictureURL> anyURI </PictureURL>
      <!-- ... more PictureURL values allowed here ... -->
    </PictureDetails>
    <PostalCode> string </PostalCode>
    <PrimaryCategory> CategoryType
      <CategoryID> string </CategoryID>
    </PrimaryCategory>
    <PrivateListing> boolean </PrivateListing>
    <ProductListingDetails> ProductListingDetailsType
      <BrandMPN> BrandMPNType
        <Brand> string </Brand>
        <MPN> string </MPN>
      </BrandMPN>
      <EAN> string </EAN>
      <IncludeeBayProductDetails> boolean </IncludeeBayProductDetails>
      <IncludeStockPhotoURL> boolean </IncludeStockPhotoURL>
      <ISBN> string </ISBN>
      <ProductReferenceID> string </ProductReferenceID>
      <ReturnSearchResultOnDuplicates> boolean </ReturnSearchResultOnDuplicates>
      <UPC> string </UPC>
      <UseFirstProduct> boolean </UseFirstProduct>
      <UseStockPhotoURLAsGallery> boolean </UseStockPhotoURLAsGallery>
    </ProductListingDetails>
    <Quantity> int </Quantity>
    <QuantityRestrictionPerBuyer> QuantityRestrictionPerBuyerInfoType
      <MaximumQuantity> int </MaximumQuantity>
    </QuantityRestrictionPerBuyer>
    <Regulatory> RegulatoryType
      <Documents> DocumentsType
        <Document> DocumentType
          <DocumentID> string </DocumentID>
        </Document>
        <!-- ... more Document nodes allowed here ... -->
      </Documents>
      <EnergyEfficiencyLabel> EnergyEfficiencyType
        <ImageDescription> string </ImageDescription>
        <ImageURL> anyURI </ImageURL>
        <ProductInformationsheet> anyURI </ProductInformationsheet>
      </EnergyEfficiencyLabel>
      <Hazmat> HazmatType
        <Component> string </Component>
        <Pictograms> PictogramsType
          <Pictogram> string </Pictogram>
          <!-- ... more Pictogram values allowed here ... -->
        </Pictograms>
        <SignalWord> string </SignalWord>
        <Statements> StatementsType
          <Statement> string </Statement>
          <!-- ... more Statement values allowed here ... -->
        </Statements>
      </Hazmat>
      <Manufacturer> ManufacturerType
        <CityName> string </CityName>
        <CompanyName> string </CompanyName>
        <Country> CountryCodeType </Country>
        <Email> string </Email>
        <Phone> string </Phone>
        <PostalCode> string </PostalCode>
        <StateOrProvince> string </StateOrProvince>
        <Street1> string </Street1>
        <Street2> string </Street2>
      </Manufacturer>
      <ProductSafety> ProductSafetyType
        <Component> string </Component>
        <Pictograms> PictogramsType
          <Pictogram> string </Pictogram>
          <!-- ... more Pictogram values allowed here ... -->
        </Pictograms>
        <Statements> StatementsType
          <Statement> string </Statement>
          <!-- ... more Statement values allowed here ... -->
        </Statements>
      </ProductSafety>
      <RepairScore> double </RepairScore>
      <ResponsiblePersons> ResponsiblePersonsType
        <ResponsiblePerson> ResponsiblePersonType
          <CityName> string </CityName>
          <CompanyName> string </CompanyName>
          <Country> CountryCodeType </Country>
          <Email> string </Email>
          <Phone> string </Phone>
          <PostalCode> string </PostalCode>
          <StateOrProvince> string </StateOrProvince>
          <Street1> string </Street1>
          <Street2> string </Street2>
          <Types> ResponsiblePersonCodeTypes
            <Type> ResponsiblePersonCodeType </Type>
            <!-- ... more Type values allowed here ... -->
          </Types>
        </ResponsiblePerson>
        <!-- ... more ResponsiblePerson nodes allowed here ... -->
      </ResponsiblePersons>
    </Regulatory>
    <ReservePrice currencyID="CurrencyCodeType"> AmountType (double) </ReservePrice>
    <ReturnPolicy> ReturnPolicyType
      <Description> string </Description>
      <InternationalRefundOption> token </InternationalRefundOption>
      <InternationalReturnsAcceptedOption> token </InternationalReturnsAcceptedOption>
      <InternationalReturnsWithinOption> token </InternationalReturnsWithinOption>
      <InternationalShippingCostPaidByOption> token </InternationalShippingCostPaidByOption>
      <RefundOption> token </RefundOption>
      <ReturnsAcceptedOption> token </ReturnsAcceptedOption>
      <ReturnsWithinOption> token </ReturnsWithinOption>
      <ShippingCostPaidByOption> token </ShippingCostPaidByOption>
    </ReturnPolicy>
    <ScheduleTime> dateTime </ScheduleTime>
    <SecondaryCategory> CategoryType
      <CategoryID> string </CategoryID>
    </SecondaryCategory>
    <Seller> UserType </Seller>
    <SellerContactDetails> AddressType
      <CompanyName> string </CompanyName>
      <County> string </County>
      <PhoneAreaOrCityCode> string </PhoneAreaOrCityCode>
      <PhoneCountryCode> CountryCodeType </PhoneCountryCode>
      <PhoneLocalNumber> string </PhoneLocalNumber>
      <Street> string </Street>
      <Street2> string </Street2>
    </SellerContactDetails>
    <SellerProfiles> SellerProfilesType
      <SellerPaymentProfile> SellerPaymentProfileType
        <PaymentProfileID> long </PaymentProfileID>
        <PaymentProfileName> string </PaymentProfileName>
      </SellerPaymentProfile>
      <SellerReturnProfile> SellerReturnProfileType
        <ReturnProfileID> long </ReturnProfileID>
        <ReturnProfileName> string </ReturnProfileName>
      </SellerReturnProfile>
      <SellerShippingProfile> SellerShippingProfileType
        <ShippingProfileID> long </ShippingProfileID>
        <ShippingProfileName> string </ShippingProfileName>
      </SellerShippingProfile>
    </SellerProfiles>
    <SellerProvidedTitle> string </SellerProvidedTitle>
    <ShippingDetails> ShippingDetailsType
      <CalculatedShippingRate> CalculatedShippingRateType
        <InternationalPackagingHandlingCosts currencyID="CurrencyCodeType"> AmountType (double) </InternationalPackagingHandlingCosts>
        <PackagingHandlingCosts currencyID="CurrencyCodeType"> AmountType (double) </PackagingHandlingCosts>
      </CalculatedShippingRate>
      <ExcludeShipToLocation> string </ExcludeShipToLocation>
      <!-- ... more ExcludeShipToLocation values allowed here ... -->
      <GlobalShipping> boolean </GlobalShipping>
      <InternationalPromotionalShippingDiscount> boolean </InternationalPromotionalShippingDiscount>
      <InternationalShippingDiscountProfileID> string </InternationalShippingDiscountProfileID>
      <InternationalShippingServiceOption> InternationalShippingServiceOptionsType
        <ShippingService> token </ShippingService>
        <ShippingServiceAdditionalCost currencyID="CurrencyCodeType"> AmountType (double) </ShippingServiceAdditionalCost>
        <ShippingServiceCost currencyID="CurrencyCodeType"> AmountType (double) </ShippingServiceCost>
        <ShippingServicePriority> int </ShippingServicePriority>
        <ShipToLocation> string </ShipToLocation>
        <!-- ... more ShipToLocation values allowed here ... -->
      </InternationalShippingServiceOption>
      <!-- ... more InternationalShippingServiceOption nodes allowed here ... -->
      <PromotionalShippingDiscount> boolean </PromotionalShippingDiscount>
      <RateTableDetails> RateTableDetailsType
        <DomesticRateTable> string </DomesticRateTable>
        <DomesticRateTableId> string </DomesticRateTableId>
        <InternationalRateTable> string </InternationalRateTable>
        <InternationalRateTableId> string </InternationalRateTableId>
      </RateTableDetails>
      <SalesTax> SalesTaxType
        <SalesTaxPercent> float </SalesTaxPercent>
        <SalesTaxState> string </SalesTaxState>
        <ShippingIncludedInTax> boolean </ShippingIncludedInTax>
      </SalesTax>
      <ShippingDiscountProfileID> string </ShippingDiscountProfileID>
      <ShippingServiceOptions> ShippingServiceOptionsType
        <FreeShipping> boolean </FreeShipping>
        <ShippingService> token </ShippingService>
        <ShippingServiceAdditionalCost currencyID="CurrencyCodeType"> AmountType (double) </ShippingServiceAdditionalCost>
        <ShippingServiceCost currencyID="CurrencyCodeType"> AmountType (double) </ShippingServiceCost>
        <ShippingServicePriority> int </ShippingServicePriority>
      </ShippingServiceOptions>
      <!-- ... more ShippingServiceOptions nodes allowed here ... -->
      <ShippingType> ShippingTypeCodeType </ShippingType>
    </ShippingDetails>
    <ShippingPackageDetails> ShipPackageDetailsType
      <MeasurementUnit> MeasurementSystemCodeType </MeasurementUnit>
      <PackageDepth> MeasureType (decimal) </PackageDepth>
      <PackageLength> MeasureType (decimal) </PackageLength>
      <PackageWidth> MeasureType (decimal) </PackageWidth>
      <ShippingIrregular> boolean </ShippingIrregular>
      <ShippingPackage> ShippingPackageCodeType </ShippingPackage>
      <WeightMajor> MeasureType (decimal) </WeightMajor>
      <WeightMinor> MeasureType (decimal) </WeightMinor>
    </ShippingPackageDetails>
    <ShippingServiceCostOverrideList> ShippingServiceCostOverrideListType
      <ShippingServiceCostOverride> ShippingServiceCostOverrideType
        <ShippingServiceAdditionalCost currencyID="CurrencyCodeType"> AmountType (double) </ShippingServiceAdditionalCost>
        <ShippingServiceCost currencyID="CurrencyCodeType"> AmountType (double) </ShippingServiceCost>
        <ShippingServicePriority> int </ShippingServicePriority>
        <ShippingServiceType> ShippingServiceType </ShippingServiceType>
      </ShippingServiceCostOverride>
      <!-- ... more ShippingServiceCostOverride nodes allowed here ... -->
    </ShippingServiceCostOverrideList>
    <ShipToLocations> string </ShipToLocations>
    <!-- ... more ShipToLocations values allowed here ... -->
    <Site> SiteCodeType </Site>
    <SKU> SKUType (string) </SKU>
    <StartPrice currencyID="CurrencyCodeType"> AmountType (double) </StartPrice>
    <Storefront> StorefrontType
      <StoreCategory2ID> long </StoreCategory2ID>
      <StoreCategory2Name> string </StoreCategory2Name>
      <StoreCategoryID> long </StoreCategoryID>
      <StoreCategoryName> string </StoreCategoryName>
    </Storefront>
    <SubTitle> string </SubTitle>
    <TaxCategory> string </TaxCategory>
    <Title> string </Title>
    <UseTaxTable> boolean </UseTaxTable>
    <UUID> UUIDType (string) </UUID>
    <VATDetails> VATDetailsType
      <BusinessSeller> boolean </BusinessSeller>
      <RestrictedToBusiness> boolean </RestrictedToBusiness>
      <VATPercent> float </VATPercent>
    </VATDetails>
    <VideoDetails> VideoDetailsType
      <VideoID> string </VideoID>
      <!-- ... more VideoID values allowed here ... -->
    </VideoDetails>
    <VIN> string </VIN>
    <VRM> string </VRM>
  </Item>
  <!-- Standard Input Fields -->
  <ErrorHandling> ErrorHandlingCodeType </ErrorHandling>
  <ErrorLanguage> string </ErrorLanguage>
  <MessageID> string </MessageID>
  <Version> string </Version>
  <WarningLevel> WarningLevelCodeType </WarningLevel>
</AddItemRequest>

 Item.ListingDetails.BestOfferAutoAcceptPrice 

 Item.ListingDetails.BestOfferAutoAcceptPrice 

 Item.ListingDetails.MinimumBestOfferPrice 

 Item.ListingDetails.MinimumBestOfferPrice 

Output

See also Samples.

The box below lists all fields that might be returned in the response. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).